.TH "FBB::ReadLineStream" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Editing input lines"

.PP 
.SH "NAME"
FBB::ReadLineStream \- std::istream offering line\-editing and history
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/readlinestream>\fP
.br 
Linking option: \-lreadline \-lbobcat
.PP 
.SH "DESCRIPTION"
A \fBFBB::ReadLineStream\fP object is a \fIstd::istream\fP objects, allowing
line\-editing and history manipulation\&.
.PP 
The \fBReadLineStream\fP class uses Gnu\(cq\&s readline library to allow editing of
input lines\&. The \fIReadLineStream\fP object can be used to construct a
\fIstd::istream\fP allowing in\-line editing of lines read from the terminal\&. All
lines may be preceded by a configurable prompt\&.
.PP 
Since Gnu\(cq\&s readline library operates on global data there can only be one
\fBReadLineStream\fP (and underlying \fBReadLineBuf\fP) object\&. 
\fBReadLineStream\fP is a singleton class: in any program there can only be one
\fBReadLineStream\fP object\&.
.PP 
\fBReadLineStream\fP offers editing capabilities while the user is entering
lines\&. Like Gnu\(cq\&s \fBreadline\fP(3) function, the line editing commands are
by default similar to those of \fBemacs\fP(1), but can easily be reconfigured,
e\&.g\&. to offer \fBvi\fP(1)\-like characteristics\&. 
.PP 
History manipulation is provided as an option\&. The collected history may be
accessed for reading using an \fBFBB::ReadLineHistory\fP object\&. 
.PP 
Specific information about the facilities offered by the Gnu software used by
\fBReadLineStream\fP is provided in the GNU Readline Library documentation
(\fIhttp://cnswww\&.cns\&.cwru\&.edu/php/chet/readline/rltop\&.html\fP)\&.
.PP 
Gnu\(cq\&s \fIreadline\fP function reads its information from the standard input
file\&. Programs using \fIReadLineStream\fP should normally not extract information
from \fIstd::cin\fP\&. However, as the standard input file has a file descriptor
(0), redirection should be possible (e\&.g\&., using \fIFBB::Redirector\fP)\&.
.PP 
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\&.
.PP 
History expansion is usually performed  immediately  after  a  complete
line  is read\&.
.PP 
The line selected from the history is called the \fIevent\fP, and the portions
of that line that are processed are called \fIwords\fP\&.  Various modifiers are
available to manipulate selected words\&. This is comparable to the way a
program like \fBbash\fP(1) breaks up its input line into `words\(cq\&\&.
.PP 
History expansion is introduced by the use of the history expansion character,
by default equal to the \fI!\fP\-character\&.  Only backslash (\fI\e\fP) and single
quotes can change the history expansion character into a normal character\&.
.PP 
The remainder of this section is copied almost verbatim from the
\fBhistory\fP(3) man\-page\&. The reader is referred to that man\-page or to the Gnu
History Library documentation for further details\&.
.PP 
The following \fBevent designators\fP are supported:
.IP o 
\fI!\fP:  starts a  history substitution, except when followed by a blank,
newline, \fI=\fP or \fI(\fP\&.
.IP o 
\fI!n\fP: refers to command line n\&.
.IP o 
\fI!\-n\fP: refers to the current command line minus n\&.
.IP o 
\fI!!\fP  refers to the previous command\&.  This is a synonym for `!\-1\(cq\&\&.
.IP o 
\fI!string\fP refers to the most recent command starting with string\&.
.IP o 
\fI!?string[?]\fP  refers to the most recent command containing string\&.
The trailing \fI?\fP may be omitted if string is followed immediately by
a newline\&.
.IP o 
\fI^string1^string2^\fP (quick substitution) repeats the last command,
replacing \fIstring1\fP with \fIstring2\fP\&.  
Equivalent to \fI!!:s/string1/string2/\fP\&.
.IP o 
\fI!#\fP the entire command line typed so far\&.

.PP 
\fBWord Designators\fP
.PP 
Word designators are used to select desired words from the event\&.  A \fI:\fP
separates the event specification from the word designator\&.  It may be omitted
if the word designator begins with a \fI^, $, *, \-\fP, or \fI%\fP\&.  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\&.
.IP o 
\fI0\fP (zero) The zeroth word\&.  For the shell, this is the command word\&.
.IP o 
\fIn\fP      The nth word\&.
.IP o 
\fI^\fP      The first argument\&.  That is, word 1\&.
.IP o 
\fI$\fP      The last argument\&.
.IP o 
\fI%\fP      The word matched by the most recent \fI?string?\fP search\&.
.IP o 
\fIx\-y\fP    A range of words; `\-y\(cq\& abbreviates `0\-y\(cq\&\&.
.IP o 
\fI*\fP      All  of  the words but the zeroth\&.  This is a synonym for 
\fI1\-$\fP\&. It is not an error to use * if there is just one word
in the event; the empty string is returned in that case\&.
.IP o 
\fIx*\fP     Abbreviates \fIx\-$\fP\&.
.IP o 
\fIx\-\fP     Abbreviates \fIx\-$\fP like \fIx*\fP, but omits the last word\&.
If  a  word  designator is supplied without an event specification, the
previous command is used as the event\&.
.PP 
\fBModifiers\fP
.PP 
After the optional word designator, there may appear a sequence of  one
or more of the following modifiers, each preceded by a \fI:\fP\&.
.IP o 
\fIh\fP removes a trailing file name component, leaving only the head\&.
.IP o 
\fIt\fP removes all leading file name components, leaving the tail\&.
.IP o 
\fIr\fP removes a trailing suffix of the form \fI\&.xxx\fP, leaving the
basename\&. 
.IP o 
\fIe\fP removes all but the trailing suffix\&.
.IP o 
\fIp\fP prints the new command but does not execute it\&.
.IP o 
\fIq\fP quotes the substituted words, escaping further substitutions\&.
.IP o 
\fIx\fP quotes the substituted words as with q, but break into words at
blanks and newlines\&.
.IP o 
\fIs/old/new/\fP substitutes new for the first occurrence of old in the
event line\&.  Any delimiter can be used in place of \fI/\fP\&.  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 \fI&\fP appears in new, it is replaced by old\&.
A single backslash will quote the \fI&\fP\&.  If \fIold\fP is null, it is
set to the last old substituted, or, if no previous history
substitutions took place, the last string in a \fI!?string[?]\fP
search\&.
.IP o 
\fI&\fP      repeats the previous substitution\&.
.IP o 
\fIg\fP Causes changes to be applied over the entire event line\&.  This is
used in conjunction with \fI:s\fP (e\&.g\&., \fI:gs/old/new/\fP) or \fI:&\fP\&.
If used with \fI:s\fP, any delimiter can be used in place of \fI/\fP,
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 \fIg\fP\&.
.IP o 
\fIG\fP Apply the following \fIs\fP modifier once to each word in the event
line\&.

.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\fIFBB::ReadLineBuf\fP (privately), \fIstd::istream\fP (publicly)
.PP 
.SH "ENUMERATIONS"

.PP 
The \fIenum Type\fP defines the following value:
.IP o 
\fIDONT_EXPAND_HISTORY\fP: history expansion is not requested;
.IP o 
\fIEXPAND_HISTORY\fP:  history expansion is requested\&.

.PP 
The \fIenum Expansion\fP provides meaningful return
values for the history expansion process\&. Its values are:
.IP o 
\fIDONT_EXEC\fP: history expansion succeeded, but the expanded line should
not be executed\&. E\&.g\&., after entering the line
.nf 

    ls *
        
.fi 
the line
.nf 

    !!:p
        
.fi 
should cause the using program to \fIdisplay\fP, rather than exectute \fIls
*\fP\&. Note that interpretation of this expansion return value is not the task of
the \fBReadLineBuf\fP object, but of the program using the \fBReadLineBuf\fP
object\&.
.IP o 
\fIERROR\fP: the history expansion failed\&. See also the member
\fIexpansionError\fP below;
.IP o 
\fIEXPANDED\fP: the history expansion succeeded;
.IP o 
\fINO_EXPANSION\fP: no history expansion took place\&.

.PP 
.SH "CONSTRUCTORS"

.PP 
Preamble: since there can only be one \fBReadLineBuf\fP object, any attempt
to define a second \fBReadLineStream\fP object will fail as there can only be a
single \fBReadLineBuf\fP object in any program\&. An attempt to define a second
\fBReadLineBuf\fP object results in a \fIlogic_error\fP exception being thrown\&.
.PP 
.IP o 
\fBReadLineStream(std::string const &prompt = \(dq\&\(dq\&, Type type =
NO_EXPANSION)\fP:
.br 
This constructor initializes the \fIReadLineStream\fP object with an
initial prompt, using a history of at most \fIstd::numeric_limits<int>::max()\fP
lines, by default not using history expansion\&.
.IP o 
\fBReadLineStream(std::string const &prompt, size_t historySize, Type
type = NO_EXPANSION)\fP:
.br 
This constructor initializes the \fIReadLineStream\fP with an initial
prompt, an initial history of a predefined maximum size, 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
\fIstd::numeric_limits<int>::max()\fP results in a history of at most
\fIstd::numeric_limits<int>::max()\fP lines\&. If no history is requested but
\fItype\fP is specified as \fIEXPAND_HISTORY\fP a \fIlogic_error\fP exception is
thrown\&.

.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "MEMBER FUNCTIONS"
All members of \fBstd::streambuf\fP are
available, as \fBFBB::ReadLineStream\fP inherits from this class\&.
.IP o 
\fBReadLineStream::Expansion expansion() const\fP:
.br 
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
\fIExpansion::ERROR\fP\&.
.IP o 
\fBstd::string const &expansionError() const\fP:
.br 
A short textual description of the nature of the error when
\fIexpansion\fP returns \fIExpansion::ERROR\fP is returned\&. If no history
expansion is requested an empty string is returned\&.
.IP o 
\fBbool setExpansion(Type type)\fP:
.br 
History expansion can be activated or stopped using this member\&. When
history expansion is requested but the \fBReadLineStream\fP object maintains no
history the function returns \fIfalse\fP\&. Otherwise it returns \fItrue\fP\&.
.IP o 
\fBvoid setPrompt(std::string const &prompt = \(dq\&\(dq\&)\fP:
.br 
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\&. \fIsetPrompt\fP 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\&.
.IP o 
\fBbool useTimestamps(std::string (*timestamp)() = 0)\fP:
.br 
When initialized with the address of a function returning a
\fIstd::string\fP the entered commands will be given a timestamp equal to the
text returned by the function pointed to by \fItimestamp\fP\&. The timestamps can
be retrieved using the \fBReadLineHistory\fP(3) object\&. By default or after
passing an explicit 0\-pointer to \fIuseTimestamps\fP no timestamps are stored\&.
The value \fIfalse\fP is returned when no history is kept, otherwise \fItrue\fP is
returned\&. 

.PP 
.SH "EXAMPLE"
.nf 
#include <iostream>
#include <istream>
#include <cstdio>
#include <sstream>
#include <iomanip>

#include <bobcat/readlinestream>

using namespace std;
using namespace FBB;

int main()
{
    ReadLineStream in(\(dq\&\(dq\&, 10, ReadLineBuf::EXPAND_HISTORY);

    size_t count = 0;
    string line;
    while (true)
    {
        ostringstream prompt;
        prompt << setw(2) << ++count << \(dq\&: \(dq\&;
        in\&.setPrompt(prompt\&.str());

        if (!getline(in, line))          // uses the last\-set prompt
            break;

        cout << \(dq\&Retrieved: \(dq\& << line << \(dq\&\en\(dq\&
                \(dq\&Expansion status: \(dq\&;

        switch (in\&.expansion())
        {
            case ReadLineBuf::ERROR:
                cout << \(dq\&ERROR: \(dq\& << in\&.expansionError() << \(cq\&\en\(cq\&;
            break;

            case ReadLineBuf::NO_EXPANSION:
                cout << \(dq\&no expansion performed\en\(dq\&;
            break;

            case ReadLineBuf::DONT_EXEC:
                cout << \(dq\&don\(cq\&t execute the expanded line\en\(dq\&;
            break;

            case ReadLineBuf::EXPANDED:
                cout << \(dq\&expansion successfully performed\en\(dq\&;
            break;
        }
    }
}

.fi 

.PP 
.SH "FILES"
\fIbobcat/readlinebuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBreadline\fP(3), \fBreadlinebuf\fP(3), 
\fBreadlinehistory\fP(3)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP