NAME¶
FBB::ReadLineHistory - std::streambuf offering line-editing and history
SYNOPSIS¶
#include <bobcat/readlinebuf>
Linking option: -lreadline -lbobcat
DESCRIPTION¶
FBB::ReadLineHistory objects offer 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. The contents 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 contents 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
ReadLineBuf is a singleton class, there are no publicly
available constructors.
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 contents 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 &FBB::operator>>(std::istream &in,
ReadLineHistory &his):
The history available at the in stream is extracted as the current
history. The existing history is removed first. The useTimestamp
status determines whether timestams are extracted (if true) or not
(if false). A mismatch between the actual contents of the stream
and the useTimestamp status will result in unexpected
behavior.
- o
- std::ostream &FBB::operator<<(std::ostream &out,
ReadLineHistory &his):
The current history is inserted into 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>
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"
"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);
}
FILES¶
bobcat/readlinehistory - defines the class interface
SEE ALSO¶
bobcat(7),
readline(3),
readlinebuf(3),
readlinestream(3)
BUGS¶
None Reported.
DISTRIBUTION FILES¶
- o
- bobcat_3.23.01-x.dsc: detached signature;
- o
- bobcat_3.23.01-x.tar.gz: source archive;
- o
- bobcat_3.23.01-x_i386.changes: change log;
- o
- libbobcat1_3.23.01-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_3.23.01-x_*.deb: debian package holding the
libraries, headers and manual pages;
- o
- http://sourceforge.net/projects/bobcat: public archive location;
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).