Provided by: libbobcat-dev_6.03.02-2_amd64 
NAME
FBB::ReadLineHistory - std::streambuf offering line-editing and history
SYNOPSIS
#include <bobcat/readlinebuf>
Linking option: -lbobcat -lreadline
DESCRIPTION
The FBB::ReadLineHistory object offers access to the history maintained by
FBB::ReadLineBuf and ReadLineStream objects.
The latter two classes use Gnu’s readline library to allow editing of input lines. The
accumulated history of these objects can be accessed from the ReadLineHistory object.
Since Gnu’s readline library maintains global data there can only be one history. The
ReadLineHistory class is therefore, like ReadLineBuf a singleton. (Gnu’s readline library
does, however, offer functions allowing programs to use multiple histories. So it would in
principle be possible to design a non-singleton ReadLineHistory class. Since programs
normally only interact with a single terminal, there is probably little use for
non-singleton ReadLineHistory class).
The ReadLineHistory class encapsulates history access. It offers limited facilities:
either forward or backward iterations over the history are offered as well as reading and
writing the history from/to streams. When reading the history from a stream it replaces
the currently available lines in Gnu’s readline history. The content of the history lines
and --if defined-- the timestamps of the lines in the history can be obtained using
iterators defined by ReadLineHistory.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are
defined in the namespace FBB.
INHERITS FROM
-
NESTED TYPES
The class ReadLineHistory defines the following nested types:
HistoryElement
The iterators made available by the ReadLineHistory object provide access to a
HistoryElement object. These objects can be copied and assigned to each other, but user
programs cannot otherwise construct HistoryElement objects.
The class HistoryElement has but two members:
o char const *line() const returns the content of the history line to which a
ReadLineHistory iterator refers;
o char const *timestamp() const returns the timestamp (if defined) of the history
line to which a ReadLineHistory iterator refers;
const_iterator and const_reverse_iterator
The iterators returned by members of the class ReadLineHistory are input iterators,
pointing to HistoryElement objects. As they are input iterators modification of the
history elements to which they refer is not allowed.
The class const_iterator allows iterations from the first to the last history element, the
class const_reverse_iterator allows iterations from the last back to the first history
element.
The iterators can be incremented, compared for (in)equality and offer operator* and
operator-> members, offering access to, respectively, HistoryElement objects and their
addresses.
CONSTRUCTORS
As the class ReadLineHistory is a singleton class, there are no publicly available
constructors, nor are assignment operators available.
STATIC MEMBER FUNCTIONS
o ReadLineHistory &instance():
A reference to the ReadLineHistory object is returned. If any history has been
accumulated it can immediately be retrieved. Using this static member will not
affect the way the ReadLineHistory object handles timestamps when saving or
retrieving history lines. When initially constructed the ReadLineHistory object
assumes that timestamps are not used.
o ReadLineHistory &instance(bool useTimestamps):
A reference to the ReadLineHistory object is returned. If any history has been
accumulated it can immediately be retrieved. The useTimestamps parameter defines
the way history lines are read from or written to a stream. When specifying true
the history inserted into a stream will include timestamps (which may be empty if
no timestamps were recorded). Likewise, when extracting the history timestamps are
extracted too (which may also be empty). When specifying false no timestamps are
read or written. A mismatch between the actual content of the stream from which the
history is extracted and the useTimestamps parameter will results in unexpected
behavior.
MEMBER FUNCTIONS
o ReadLineHistory::const_iterator begin() const:
An input iterator pointing to the first history line is returned.
o ReadLineHistory::const_iterator end() const:
An input iterator pointing beyond the last history line is returned.
o size_t maxSize() const:
The maximum number of lines that can be stored in the history is returned. After
collecting a history of maxSize lines, the next line entered will cause the initial
history line to be removed from the history, making room for the next line to be
added at the end of the history.
o ReadLineHistory::const_reverse_iterator rbegin() const:
An input iterator pointing to the last history line is returned. Incrementing this
iterator will access the previous line in the history.
o ReadLineHistory::const_reverse_iterator rend() const:
An input iterator pointing before the first history line is returned.
o ReadLineHistory &setTimestamps(bool useTimestamps):
xThe current status of the timestamps usage is set according to the value of its
parameter. When true inserting and extracting history will include the timestamps.
No timestamps are inserted or extracted when false. It returns a reference to the
updated ReadLineHistory object, allowing constructions like (assuming the
availability of ReadLineHistory &history):
cout << history.setTimestamps(true);
o size_t size() const:
The number of lines currently stored in the history is returned.
o bool timestamps() const:
The current status of the timestamps usage is returned. When returning true
inserting and extracting history will include the timestamps. No timestamps are
inserted or extracted when this member returns false
OVERLOADED OPERATORS
o std::istream &operator>>(std::istream &in, ReadLineHistory &his):
The history available at the in stream is extracted to become the current history,
replacing the existing (Gnu readline) history by the history read from in. The
useTimestamp status determines whether timestams are extracted (if true) or not (if
false). If extracting the history from in fails an exception is thrown.
o std::ostream &operator<<(std::ostream &out, ReadLineHistory &his):
The current history is written to the out stream. The useTimestamp status
determines whether timestams are inserted (if true) or not (if false).
EXAMPLE
#include <iostream>
#include <algorithm>
#include <fstream>
#include <bobcat/datetime>
#include <bobcat/readlinestream>
//#include <bobcat/readlinehistory>
#include "../readlinehistory"
using namespace std;
using namespace FBB;
void showHis(ReadLineHistory::HistoryElement const &element)
{
cout << element.timestamp() << " " << element.line() << ’\n’;
}
string timestamp()
{
return DateTime().rfc2822();
};
int main(int argc, char **argv)
{
ReadLineStream in("? ", ReadLineBuf::EXPAND_HISTORY);
in.useTimestamps(×tamp);
cout << "Enter some lines, end the input using ctrl-d\n";
string line;
while (getline(in, line))
;
// argument means: write/read
// history timestamps
ReadLineHistory &history = ReadLineHistory::instance(argc > 1);
cout << "All lines, from the first to the last:\n";
for_each(history.begin(), history.end(), showHis);
cout << "\n"
"Again: all lines, from the first to the last:\n";
for_each(history.begin(), history.end(), showHis);
cout << "\n"
"All lines, from the last to the first:\n";
for_each(history.rbegin(), history.rend(), showHis);
cout << "\n"
"History out and in:\n"
"\n";
ofstream hisout("history.out");
hisout << history;
hisout.close();
ifstream hisin("history.out");
hisin >> history;
cout << "All lines, from the first to the last:\n";
for_each(history.begin(), history.end(), showHis);
cout << "\n"
"All lines, from the last to the first:\n";
for_each(history.rbegin(), history.rend(), showHis);
}
FILES
bobcat/readlinehistory - defines the class interface
SEE ALSO
bobcat(7), readline(3), readlinebuf(3), readlinestream(3)
BUGS
None Reported.
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_6.03.02-x.dsc: detached signature;
o bobcat_6.03.02-x.tar.gz: source archive;
o bobcat_6.03.02-x_i386.changes: change log;
o libbobcat1_6.03.02-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_6.03.02-x_*.deb: debian package containing the libraries, headers
and manual pages;
BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License
(GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).