FBB::OFoldStreambuf(3bobcat)					  Fold long lines				      FBB::OFoldStreambuf(3bobcat)

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 (
, other white space characters (space), and non-space characters). The nine combinations result-
       ing 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	
	 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	
	 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	
	 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_TRAIL-
	      ING_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 speci-
	      fied 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 parame-
	      ter 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 sep-
       arates 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 << '
';

	       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_3.01.00-x.dsc: detached signature;

       o      bobcat_3.01.00-x.tar.gz: source archive;

       o      bobcat_3.01.00-x_i386.changes: change log;

       o      libbobcat1_3.01.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.01.00-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).

libbobcat1-dev_3.01.00-x.tar.gz 				     2005-2012					      FBB::OFoldStreambuf(3bobcat)