NAME

       FBB::OFoldStream - Folds long lines

SYNOPSIS

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

DESCRIPTION

       FBB::OFoldStream folds long lines written to it. The OFoldStream writes the (folded) lines
       to a second ostream which is either used by or opened by the OFoldStream object.

       OFoldStream objects never fold lines in the middle of series of non-blank  characters  but
       will always break a line at white space characters. 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.

       OFoldStream is implemented as a wrapper class around std::ostream and FBB::OFoldBuf and  a
       more complete description of the folding process can be found in the ofoldbuf(3bobcat) man
       page.

NAMESPACE

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

INHERITS FROM

       std::ostream,
       (and privately from FBB::OFoldBuf)

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 OFoldStream object with respect to
       any  trailing blanks that may appear on the final line. It is the same enumeration type as
       used with OFoldBuf (cf. ofoldbuf(3bobcat)) having 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 OFoldStream 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      OFoldStream():
              This constructor initializes an OFoldStream object but does not associate it with a
              destination   stream.    It    uses    the    values    0,    80,    BLANKS,    and
              IGNORE_TRAILING_BLANKSfor,   resp.   its  left  margin,  right  margin  left-margin
              characters and TrailingBlanks handling mode.

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

       o      OFoldStream(std::ostream &stream, size_t leftIndent = 0, size_t rightMargin  =  80,
              TabsOrBlanks tob = BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS):
              This  constructor  initializes  an  OFoldStream  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 std::ostream are available, as FBB::OFoldStream inherits from this class.

       o      void close():
              This  member  flushes  any  pending  information to the destination stream and then
              closes the destination stream.

       o      void open(char const *fname, openmode mode = std::ios::out):
              This member associates the OFilterStream object with an std::ofstream object  whose
              filename is provided and that should receive the folded information.

       o      void open(std::ostream &out):
              This member associates the OFilterStream object with the provided ostream object.

       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::ostream const &os):
              This member returns the current left  margin  setting  of  the  OFoldStream  object
              passed  to it as its argument. The member defines a std::ostream parameter since in
              many cases the OFoldStream object will be used  in  functions  themselves  defining
              std::ostream parameters. Internally, the std::ostream’s std::streambuf is down cast
              to an OFoldBuf and an FBB::Exception exception is thrown if that cast fails.

       o      size_t rightMargin(std::ostream const &os):
              This member returns the current right margin  setting  of  the  OFoldStream  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 <string>
       #include <bobcat/ofoldstream>

       using namespace std;
       using namespace FBB;

       void margins(ostream &out)
       {
           cout << OFoldStream::leftMargin(out) << ", " <<
                   OFoldStream::rightMargin(out) << endl;
       }

       int main()
       {
           OFoldStream out(cout, 4, 40);

           out << lm(4);

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

           margins(out);
       }

FILES

       bobcat/ofoldstream - defines the class interface

SEE ALSO

       bobcat(7),  lm(3bobcat), mlm(3bobcat), ofoldbuf(3bobcat)

BUGS

       None Reported.

BOBCAT PROJECT FILES

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       o      bobcat_6.04.00-x.dsc: detached signature;

       o      bobcat_6.04.00-x.tar.gz: source archive;

       o      bobcat_6.04.00-x_i386.changes: change log;

       o      libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.04.00-x_*.deb:  debian  package  containing the libraries, headers
              and manual pages;

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