FBB::ReadLineBuf(3bobcat)

Editing input lines
(libbobcat-dev_4.08.03-x.tar.gz)

2005-2018

NAME

FBB::ReadLineBuf - std::streambuf offering line-editing and history

SYNOPSIS

#include <bobcat/readlinebuf>
Linking option: -lreadline -lbobcat

DESCRIPTION

The FBB::ReadLineBuf object may be used as a std::streambuf of std::istream objects, allowing line-editing and history manipulation.

The ReadLineBuf class uses Gnu's readline library to allow editing of input lines. The ReadLineBuf object can be used to construct a 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 ReadLineBuf object. Therefore ReadLineBuf is a singleton class: in any program there can only be one 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 ReadLineBuf class. Since programs normally only interact with a single terminal, there is probably little use for non-singleton ReadLineBuf class).

ReadLineBuf offers editing capabilities while the user is entering lines. Like Gnu's readline(3) function, the line editing commands are by default similar to those of emacs(1), but can easily be reconfigured, e.g. to offer vi(1)-like characteristics.

History manipulation is provided as an option. The collected history may be accessed for reading using an FBB::ReadLineHistory object.

Specific information about the facilities offered by the Gnu software used by ReadLineBuf is provided in the GNU Readline Library documentation (http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html).

Gnu's readline function reads its information from the standard input file. Programs using ReadLineBuf should normally not extract information from std::cin. However, as the standard input file has a file descriptor (0), redirection should be possible (e.g., using 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 event, and the portions of that line that are processed are called words. Various modifiers are available to manipulate selected words. This is comparable to the way a program like 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 !-character. Only backslash (\) and single quotes can change the history expansion character into a normal character.

The remainder of this section is copied almost verbatim from the history(3) man-page. The reader is referred to that man-page or to the Gnu History Library documentation for further details.

The following event designators are supported:

Word Designators

Word designators are used to select desired words from the event. A : separates the event specification from the word designator. It may be omitted if the word designator begins with a ^, $, *, -, or %. 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.

If a word designator is supplied without an event specification, the previous command is used as the event.

Modifiers

After the optional word designator, there may appear a sequence of one or more of the following modifiers, each preceded by a :.

NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

std::streambuf

ENUMERATIONS

The enum Type defines the following value:

The enum Expansion provides meaningful return values for the history expansion process. Its values are:

STATIC MEMBERS

CONSTRUCTORS

As the class ReadLineBuf is a singleton class it offers no public constructors.

MEMBER FUNCTIONS

All members of std::streambuf are available, as FBB::ReadLineBuf inherits from this class.

EXAMPLE

#include <iostream>
#include <istream>
#include <cstdio>
#include <sstream>
#include <iomanip>

#include <bobcat/readlinebuf>

using namespace std;
using namespace FBB;

int main()
{
    ReadLineBuf &readlineBuf = 
            ReadLineBuf::initialize("", 10, ReadLineBuf::EXPAND_HISTORY);

    istream in(&readlineBuf);

    size_t count = 0;
    string line;
    while (true)
    {
        ostringstream prompt;
        prompt << setw(2) << ++count << ": ";
        readlineBuf.setPrompt(prompt.str());

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

        cout << "Retrieved: " << line << "\n"
                "Expansion status: ";

        switch (readlineBuf.expansion())
        {
            case ReadLineBuf::ERROR:
                cout << "ERROR: " << readlineBuf.expansionError() << '\n';
            break;

            case ReadLineBuf::NO_EXPANSION:
                cout << "no expansion performed\n";
            break;

            case ReadLineBuf::DONT_EXEC:
                cout << "don't execute the expanded line\n";
            break;

            case ReadLineBuf::EXPANDED:
                cout << "expansion successfully performed\n";
            break;
        }
    }
}

FILES

bobcat/readlinebuf - defines the class interface

SEE ALSO

bobcat(7), readline(3), readlinehistory(3), readlinestream(3)

BUGS

None Reported.

DISTRIBUTION FILES

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).