Provided by: libbobcat-dev_5.00.02-2_amd64 bug

NAME

       FBB::OFoldBuf - Folds long lines written to ostream

SYNOPSIS

       #include <bobcat/ofoldbuf>
       Linking option: -lbobcat

DESCRIPTION

       FBB::OFoldBuf  is  a  specialization  of  FBB::OFilterBuf folding long lines written to an
       std::ostream object. The OFoldBuf writes the (folded)  lines  to  a  second  ostream  (the
       destination stream which is either used by or opened by the OFoldBuf object).

       Internally  the  OFoldBuf  defines  its  actions  using  a  little finite state automation
       distinguishing three states (INDENT, WS and NON_WS) and three  character  categories  (\n,
       other  white  space  characters  (space), and non-space characters). The nine combinations
       resulting from these two sets are discussed below.

       OFoldBuf objects will never fold lines in the middle of  series  of  non-blank  characters
       (called  a  `word’  below)  but  will  always break a line at a white space character. The
       resulting lines will always appear to the right of a configurable left margin and  to  the
       left  of  a configurable right margin. There is a somewhat pathological exception to this:
       if a word is too long to fit in between the margins then the word will  exceed  the  right
       hand margin.

       The  indentation  used for the left margins is configurable to either blanks (the default)
       or tabs. When tabs are used the width of a tab character is configurable, using a  default
       of 8 positions in the destination stream.

       What  follows  is  a description of the Finite State Automaton (FSA) defining what happens
       when various character types appear at its three states. The phrase `... is written’ means
       that  the  described  information is written to the ostream used or opened by the OFoldBuf
       object. OFoldBuf’s initial state is INDENT:

       State    char.    description
       ───────────────────────────────────────────────────────────────────────
       INDENT   \n       a new line character is written
                space    the indentation is set;
                         the space character is added to the indentation;
                         next state: WS
                non-ws   the character is added to the currently stored word;
                         next state: NON_WS
       ───────────────────────────────────────────────────────────────────────
       WS       \n       a new line character is written;
                         stored white-space is erased;
                         next state: INDENT
                space    white space character is added to the currently
                         stored space characters;
                non-ws   the character is added to the currently stored word;
                         next state: NON_WS
       ───────────────────────────────────────────────────────────────────────
       NON_WS   \n       stored white space and word are written;
                         a new line is written;
                         next state: INDENT
                space    stored white space and word are written;
                         white space character is added to the currently
                         stored space characters;
                         next state: WS
                non-ws   the character is added to the currently stored word;
       ───────────────────────────────────────────────────────────────────────

NAMESPACE

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

INHERITS FROM

       FBB::OFilterBuf

ENUMERATION

       The  enumeration  TabsOrBlanks  is  used  to  select  tabs  or  blanks  when  writing  the
       indentation. The default is blanks. When tabs are  selected  the  display  width  of  tabs
       characters  can  be  configured  as  well  (using  the  default  of  8  positions for each
       tab-character). The enumeration has two values:

       o      BLANKS:
              The default, indicating that the left margin is specified and written as  a  number
              of blanks;

       o      TABS:
              Indicating  that  the  left  margin  is  specified  and  written  as  a  number  of
              tab-characters.

       The enumeration TrailingBlanks is used to configure the OFoldBuf object  with  respect  to
       any trailing blanks that may appear on the final line. These trailing blanks can appear on
       the final line it it is not properly terminated with a newline character but instead  ends
       in  white space. By default these white space characters are ignored, but they may be kept
       as well. The enumeration has two values:

       o      IGNORE_TRAILING_BLANKS:
              This indicates that trailing blanks appearing at  the  final  line  if  it  is  not
              terminated by a newline should not be written to the destination std::ostream. This
              is the default used by OFoldBuf objects.

       o      KEEP_TRAILING_BLANKS:
              This indicates that trailing blanks at the final line if it is not terminated by  a
              newline should be written to the destination std::ostream

CONSTRUCTORS

       o      OFoldBuf(size_t leftIndent = 0, size_t rightMargin = 80, TabsOrBlanks tob = BLANKS,
              TrailingBlanks tb = IGNORE_TRAILING_BLANKS):
              This constructor initializes an OFoldBuf object but does not associate  it  with  a
              destination stream. It can also be used as the default constructor.

       o      OFoldBuf(char  const  *fname,  size_t  leftIndent  =  0,  size_t  rightMargin = 80,
              TabsOrBlanks tob = BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS):
              This constructor initializes an OFoldBuf object and opens (using std::ios::out) the
              destination stream using the name specified as its fname argument.

       o      OFoldBuf(std::ostream  &stream,  size_t  leftIndent  =  0, size_t rightMargin = 80,
              TabsOrBlanks tob = BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS):
              This constructor initializes an OFoldBuf object and uses as its destination  stream
              the std::ostream stream.

       The  destructor  writes  any  buffered information to the destination stream and will then
       flush the destination stream.

       Copy and move constructors (and assignment operators) are not available.

MEMBER FUNCTIONS

       All members of FBB::OFilterBuf, in particular its out() and reset members  are  available,
       as FBB::OFoldBuf inherits from this class.

       o      void setMargins(size_t leftMargin, size_t rightMargin):
              This  member  can  be used to modify the left- and right folding margins. Note that
              the left margin may also be modified using the FBB::lm and FBB::mlm manipulators.

       o      void setTrailingBlanks(TrailingBlanks tb):
              This member can be used to modify the currently used TrailingBlanks parameter.

       o      void useBlanks():
              This member can be used to select blanks  to be used when inserting left margins.

       o      void useTabs(size_t tabWidth = 8):
              This member can be used to select tab-characters to be  used  when  inserting  left
              margins.  The  second  parameter  is  used  to  specify  the  display  width  of  a
              tab-character.

STATIC MEMBER FUNCTIONS

       o      size_t leftMargin(std::ostreambuf const *buffer):
              This member returns the current left margin setting of the OFoldBuf  object  passed
              to  it as its argument. The member defines a std::streambuf parameter which is down
              cast to an OFoldBuf and an FBB::Exception exception is thrown if that cast fails.

       o      size_t rightMargin(std::ostreambuf const *buffer):
              This member returns the current right margin setting of the OFoldBuf object  passed
              to  it  as  its  argument.  The  member’s parameter is down cast in the same way as
              leftMargin()’s argument: an FBB::Exception exception is thrown if that cast fails.

EXAMPLE

           #include <iostream>
           #include <ostream>
           #include <string>
           #include <bobcat/ofoldbuf>

           using namespace std;
           using namespace FBB;

           int main()
           {
               OFoldBuf fb(cout, 4, 40);
               ostream out(&fb);

               out << lm(4);

               string line;
               while (getline(cin, line))
                   out << line << ’\n’;
           }

FILES

       bobcat/ofoldbuf - defines the class interface

SEE ALSO

       bobcat(7),  lm(3bobcat), mlm(3bobcat), ofilterbuf(3bobcat), ofoldstream(3bobcat)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_5.00.02-x.dsc: detached signature;

       o      bobcat_5.00.02-x.tar.gz: source archive;

       o      bobcat_5.00.02-x_i386.changes: change log;

       o      libbobcat1_5.00.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.00.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).