Provided by: libbobcat-dev_2.20.01-1_amd64 bug

NAME

       FBB::OFoldStreambuf - Folds long lines written to ostream

SYNOPSIS

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

DESCRIPTION

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

       Internally the OFoldStreambuf 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.

       OFoldStreambuf  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
       OFoldStreambuf object. OFoldStreambuf’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::OFilterStreambuf

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 OFoldStreambuf 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 OFoldStreambuf 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      OFoldStreambuf(size_t leftIndent = 0, size_t rightMargin = 80, TabsOrBlanks  tob  =
              BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS):
              This  constructor  initializes  an  OFoldStreambuf object but does not associate it
              with a destination stream. It can also be used as the default constructor.

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

       o      OFoldStreambuf(std::ostream  &stream,  size_t  leftIndent = 0, size_t rightMargin =
              80, TabsOrBlanks tob = BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS):
              This constructor initializes an OFoldStreambuf 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.

MEMBER FUNCTIONS

       All members of FBB::OFilterStreambuf, in particular  its  out()  and  open()  members  are
       available, as FBB::OFoldStreambuf 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  OFoldStreambuf  object
              passed  to  it as its argument. The member defines a std::streambuf parameter which
              is down cast to an OFoldStreambuf and an FBB::Errno 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 OFoldStreambuf object
              passed to it as its argument. The member’s parameter is down cast in the  same  way
              as leftMargin()’s argument: an FBB::Errno exception is thrown if that cast fails.

PROTECTED MEMBER FUNCTION

       The  member  listed  in  this section implements the tasks of the comparably named virtual
       function in the class’s private interface. This separates the redefinable  interface  from
       the user-interface. The class OFoldStreambuf can, in accordance with Liskov’s Substitution
       Principle, be used as a std:streambuf; but it also offers a facility for classes  deriving
       from OFoldStreambuf. This facility is listed here.

       o      int pSync():
              The contents of the OFoldStreambuf’s internal buffer is flushed.

EXAMPLE

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

           using namespace std;
           using namespace FBB;

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

               out << lm(4);

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

               return 0;
           }

FILES

       bobcat/ofoldstreambuf - defines the class interface

SEE ALSO

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

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_2.20.01-x.dsc: detached signature;

       o      bobcat_2.20.01-x.tar.gz: source archive;

       o      bobcat_2.20.01-x_i386.changes: change log;

       o      libbobcat1_2.20.01-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_2.20.01-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).