Provided by: libbobcat-dev_4.08.02-2build1_amd64 bug

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 &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 &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(&timestamp);

           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_4.08.02-x.dsc: detached signature;

       o      bobcat_4.08.02-x.tar.gz: source archive;

       o      bobcat_4.08.02-x_i386.changes: change log;

       o      libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.08.02-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).