1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::ReadLineHistory)(3bobcat)(_CurYrs_)
(libbobcat-dev__CurVers_)
(Editing input lines)
manpagename(FBB::ReadLineHistory)
(std::streambuf offering line-editing and history)
manpagesynopsis()
bf(#include <bobcat/readlinebuf>)nl()
Linking option: -lbobcat -lreadline
manpagedescription()
The bf(FBB::ReadLineHistory) object offers access to the history
maintained by bf(FBB::ReadLineBuf) and bf(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 bf(ReadLineHistory) object.
Since Gnu's readline library maintains global data there can only be one
history. The bf(ReadLineHistory) class is therefore, like bf(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 tt(ReadLineHistory) class. Since programs normally only
interact with a single terminal, there is probably little use for
non-singleton bf(ReadLineHistory) class).
The bf(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 bf(ReadLineHistory).
includefile(include/namespace)
manpagesection(INHERITS FROM)
-
manpagesection(NESTED TYPES)
The class bf(ReadLineHistory) defines the following nested types:
bf(HistoryElement)
The iterators made available by the bf(ReadLineHistory) object provide access
to a bf(HistoryElement) object. These objects can be copied and assigned to
each other, but user programs cannot otherwise construct bf(HistoryElement)
objects.
The class bf(HistoryElement) has but two members:
itemization(
itt(char const *line() const) returns the content of the
history line to which a bf(ReadLineHistory) iterator refers;
itt(char const *timestamp() const) returns the timestamp (if defined) of
the history line to which a bf(ReadLineHistory) iterator refers;
)
bf(const_iterator) and bf(const_reverse_iterator)
The iterators returned by members of the class bf(ReadLineHistory) are input
iterators, pointing to bf(HistoryElement) objects. As they are input
iterators modification of the history elements to which they refer is not
allowed.
The class bf(const_iterator) allows iterations from the first to the last
history element, the class bf(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
tt(operator*) and tt(operator->) members, offering access to, respectively,
bf(HistoryElement) objects and their addresses.
manpagesection(CONSTRUCTORS)
As the class bf(ReadLineHistory) is a singleton class, there are no
publicly available constructors, nor are assignment operators available.
manpagesection(STATIC MEMBER FUNCTIONS)
itemization(
itb(ReadLineHistory &instance())
A reference to the bf(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 bf(ReadLineHistory) object handles
timestamps when saving or retrieving history lines. When initially constructed
the tt(ReadLineHistory) object assumes that timestamps are not used.
itb(ReadLineHistory &instance(bool useTimestamps))
A reference to the bf(ReadLineHistory) object is returned. If any
history has been accumulated it can immediately be retrieved. The
tt(useTimestamps) parameter defines the way history lines are read from or
written to a stream. When specifying tt(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 tt(false) no timestamps are read
or written. A mismatch between the actual content of the stream from which
the history is extracted and the tt(useTimestamps) parameter will
results in unexpected behavior.
)
manpagesection(MEMBER FUNCTIONS)
itemization(
itb(ReadLineHistory::const_iterator begin() const)
An input iterator pointing to the first history line is returned.
itb(ReadLineHistory::const_iterator end() const)
An input iterator pointing beyond the last history line is returned.
itb(size_t maxSize() const)
The maximum number of lines that can be stored in the history is
returned. After collecting a history of tt(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.
itb(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.
itb(ReadLineHistory::const_reverse_iterator rend() const)
An input iterator pointing before the first history line is returned.
itb(ReadLineHistory &setTimestamps(bool useTimestamps))
xThe current status of the timestamps usage is set according to the
value of its parameter. When tt(true) inserting and extracting history
will include the timestamps. No timestamps are inserted or extracted
when tt(false). It returns a reference to the updated
bf(ReadLineHistory) object, allowing constructions like (assuming
the availability of tt(ReadLineHistory &history)):
verb(
cout << history.setTimestamps(true);
)
itb(size_t size() const)
The number of lines currently stored in the history is returned.
itb(bool timestamps() const)
The current status of the timestamps usage is returned. When returning
tt(true) inserting and extracting history will include the
timestamps. No timestamps are inserted or extracted when this member
returns tt(false)
)
manpagesection(OVERLOADED OPERATORS)
itemization(
itb(std::istream &operator>>(std::istream &in, ReadLineHistory &his))
The history available at the tt(in) stream is extracted to become the
current history, replacing the existing (Gnu readline) history by the
history read from tt(in). The tt(useTimestamp) status determines
whether timestams are extracted (if tt(true)) or not (if
tt(false)). If extracting the history from tt(in) fails an exception
is thrown.
itb(std::ostream &operator<<(std::ostream &out,
ReadLineHistory &his))
The current history is written to the tt(out) stream. The
tt(useTimestamp) status determines whether timestams are inserted (if
tt(true)) or not (if tt(false)).
)
manpagesection(EXAMPLE)
verbinclude(../../readlinehistory/driver/driver.cc)
manpagefiles()
em(bobcat/readlinehistory) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(readline)(3), bf(readlinebuf)(3),
bf(readlinestream)(3)
manpagebugs()
None Reported.
includefile(include/trailer)
|
