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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::ReadLineBuf)(3bobcat)(_CurYrs_)
(libbobcat-dev__CurVers_)
(Editing input lines)
manpagename(FBB::ReadLineBuf)
(std::streambuf offering line-editing and history)
manpagesynopsis()
bf(#include <bobcat/readlinebuf>)nl()
Linking option: -lbobcat -lreadline
manpagedescription()
The bf(FBB::ReadLineBuf) object may be used as a tt(std::streambuf)
of tt(std::istream) objects, allowing line-editing and history manipulation.
The bf(ReadLineBuf) class uses Gnu's readline library to allow editing of
input lines. The tt(ReadLineBuf) object can be used to construct a
tt(std::istream) allowing in-line editing of lines read from the terminal. All
lines may be preceded by a configurable prompt.
Since Gnu's readline library operates on global data there can only be one
bf(ReadLineBuf) object. Therefore bf(ReadLineBuf) is a singleton class: in any
program there can only be one bf(ReadLineBuf) object (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(ReadLineBuf)
class. Since programs normally only interact with a single terminal, there is
probably little use for non-singleton bf(ReadLineBuf) class).
bf(ReadLineBuf) offers editing capabilities while the user is entering
lines. Like Gnu's bf(readline)(3) function, the line editing commands are
by default similar to those of bf(emacs)(1), but can easily be reconfigured,
e.g. to offer bf(vi)(1)-like characteristics.
History manipulation is provided as an option. The collected history may be
accessed for reading using an bf(FBB::ReadLineHistory) object.
Specific information about the facilities offered by the Gnu software used by
bf(ReadLineBuf) is provided in the GNU Readline Library documentation
(tt(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html)).
Gnu's tt(readline) function reads its information from the standard input
file. Programs using tt(ReadLineBuf) should normally not extract information
from tt(std::cin). However, as the standard input file has a file descriptor
(0), redirection should be possible (e.g., using tt(FBB::Redirector)).
When the command line is kept, history expansion is offered as an option.
History expansion introduces words from the history list into the input
stream, making it easy to repeat commands, to insert elements of a
previous input line into the current input line, or to fix errors in previous
command lines.
History expansion is usually performed immediately after a complete
line is read.
The line selected from the history is called the tt(event), and the portions
of that line that are processed are called tt(words). Various modifiers are
available to manipulate selected words. This is comparable to the way a
program like bf(bash)(1) breaks up its input line into `words'.
History expansion is introduced by the use of the history expansion character,
by default equal to the tt(!)-character. Only backslash (tt(\)) and single
quotes can change the history expansion character into a normal character.
The remainder of this section is copied almost verbatim from the
bf(history)(3) man-page. The reader is referred to that man-page or to the Gnu
History Library documentation for further details.
The following bf(event designators) are supported:
itemization(
itt(!): starts a history substitution, except when followed by a blank,
newline, tt(=) or tt(CHAR(40)).
itt(!n): refers to command line n.
itt(!-n): refers to the current command line minus n.
itt(!!) refers to the previous command. This is a synonym for `!-1'.
itt(!string) refers to the most recent command starting with string.
itt(!?string[?]) refers to the most recent command containing string.
The trailing tt(?) may be omitted if string is followed immediately by
a newline.
itt(^string1^string2^) (quick substitution) repeats the last command,
replacing tt(string1) with tt(string2).
Equivalent to tt(!!:s/string1/string2/).
itt(!#) the entire command line typed so far.
)
bf(Word Designators)
Word designators are used to select desired words from the event. A tt(:)
separates the event specification from the word designator. It may be omitted
if the word designator begins with a tt(^, $, *, -), or tt(%). Words are
numbered from the beginning of the line, with the first word being denoted by
0 (zero). Words are inserted into the current line separated by single
spaces.
itemization(
itt(0) (zero) The zeroth word. For the shell, this is the command word.
itt(n) The nth word.
itt(^) The first argument. That is, word 1.
itt($) The last argument.
itt(%) The word matched by the most recent tt(?string?) search.
itt(x-y) A range of words; `-y' abbreviates `0-y'.
itt(*) All of the words but the zeroth. This is a synonym for
tt(1-$). It is not an error to use * if there is just one word
in the event; the empty string is returned in that case.
itt(x*) Abbreviates tt(x-$).
itt(x-) Abbreviates tt(x-$) like tt(x*), but omits the last word.
)
If a word designator is supplied without an event specification, the
previous command is used as the event.
bf(Modifiers)
After the optional word designator, there may appear a sequence of one
or more of the following modifiers, each preceded by a tt(:).
itemization(
itt(h) removes a trailing file name component, leaving only the head.
itt(t) removes all leading file name components, leaving the tail.
itt(r) removes a trailing suffix of the form tt(.xxx), leaving the
basename.
itt(e) removes all but the trailing suffix.
itt(p) prints the new command but does not execute it.
itt(q) quotes the substituted words, escaping further substitutions.
itt(x) quotes the substituted words as with q, but break into words at
blanks and newlines.
itt(s/old/new/) substitutes new for the first occurrence of old in the
event line. Any delimiter can be used in place of tt(/). The
final delimiter is optional if it is the last character of the
event line. The delimiter may be quoted in old and new with a
single backslash. If tt(&) appears in new, it is replaced by old.
A single backslash will quote the tt(&). If tt(old) is null, it is
set to the last old substituted, or, if no previous history
substitutions took place, the last string in a tt(!?string[?])
search.
itt(&) repeats the previous substitution.
itt(g) Causes changes to be applied over the entire event line. This is
used in conjunction with tt(:s) (e.g., tt(:gs/old/new/)) or tt(:&).
If used with tt(:s), any delimiter can be used in place of tt(/),
and the final delimiter is optional if it is the last character of
the event line. An a may be used as a synonym for tt(g).
itt(G) Apply the following tt(s) modifier once to each word in the event
line.
)
includefile(include/namespace)
manpagesection(INHERITS FROM)
tt(std::streambuf)
manpagesection(ENUMERATIONS)
The tt(enum Type) defines the following value:
itemization(
itt(DONT_EXPAND_HISTORY): history expansion is not requested;
itt(EXPAND_HISTORY): history expansion is requested.
)
The tt(enum Expansion) provides meaningful return
values for the history expansion process. Its values are:
itemization(
itt(DONT_EXEC): history expansion succeeded, but the expanded line should
not be executed. E.g., after entering the line
verb(
ls *
)
the line
verb(
!!:p
)
should cause the using program to em(display), rather than exectute tt(ls
*). Note that interpretation of this expansion return value is not the task of
the bf(ReadLineBuf) object, but of the program using the bf(ReadLineBuf)
object.
itt(ERROR): the history expansion failed. See also the member
tt(expansionError) below;
itt(EXPANDED): the history expansion succeeded;
itt(NO_EXPANSION): no history expansion took place.
)
manpagesection(STATIC MEMBERS)
itemization(
itb(ReadLineBuf &initialize(std::string const &prompt = "", Type type =
NO_EXPANSION))
This static member returns the tt(ReadLineBuf) using an initial
prompt, using a history of at most tt(std::numeric_limits<int>::max()) lines, and by default not using
history expansion. If the object has already been initialized a
tt(logic_error) exception is thrown.
itb(ReadLineBuf &initialize(std::string const &prompt, size_t historySize,
Type type = NO_EXPANSION))
This static member initializes the tt(ReadLineBuf) using an initial
prompt, an initial history of a predefined maximum size, and by default not
using history expansion. Specifying a history size 0 results in no history
being kept, any value equal to or exceeding the predefined constant
tt(std::numeric_limits<int>::max()) results in a history of at most tt(std::numeric_limits<int>::max()) lines. If no history
is requested but tt(type) is specified as tt(EXPAND_HISTORY) a tt(logic_error)
exception is thrown. A tt(logic_error) is also thrown if the object has
already been initialized.
itb(ReadLineBuf &instance())
This static member returns the already initialized tt(ReadLineBuf)
object. If the object has not yet been initialized a tt(logic_error)
exception is thrown.
)
manpagesection(CONSTRUCTORS)
As the class bf(ReadLineBuf) is a singleton class it offers no public
constructors, nor are overloaded assignment operators available.
manpagesection(MEMBER FUNCTIONS)
All members of bf(std::streambuf) are
available, as bf(FBB::ReadLineBuf) inherits from this class.
itemization(
itb(ReadLineBuf::Expansion expansion() const)
The status of the history expansion after retrieving a line from the
terminal is returned. Its value is determined after each line retrieved from
the terminal. If no history expansion is requested it returns
tt(Expansion::ERROR).
itb(std::string const &expansionError() const)
A short textual description of the nature of the error when
tt(expansion) returns tt(Expansion::ERROR) is returned. If no history
expansion is requested an empty string is returned.
itb(bool setExpansion(Type type))
History expansion can be activated or stopped using this member. When
history expansion is requested but the bf(ReadLineBuf) object maintains no
history the function returns tt(false). Otherwise it returns tt(true).
itb(void setPrompt(std::string const &prompt = ""))
The prompt that is displayed in front of the next line read from the
terminal can be modified by this member. When called without arguments no
prompt will be displayed. tt(setPrompt) can be called while input lines are
being received. The new prompt will be active after the current line has been
read from the terminal.
itb(bool useTimestamps(std::string (*timestamp)() = 0))
When initialized with the address of a function returning a
tt(std::string) the entered commands will be given a timestamp equal to the
text returned by the function pointed to by tt(timestamp). The timestamps can
be retrieved using the bf(ReadLineHistory)(3) object. By default or after
passing an explicit 0-pointer to tt(useTimestamps) no timestamps are stored.
The value tt(false) is returned when no history is kept, otherwise tt(true) is
returned.
)
manpagesection(EXAMPLE)
verbinclude(../../readlinebuf/driver/driver.cc)
manpagefiles()
em(bobcat/readlinebuf) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(readline)(3), bf(readlinehistory)(3),
bf(readlinestream)(3)
manpagebugs()
None Reported.
includefile(include/trailer)
|
