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::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
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::Exception 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_3.23.01-x.dsc: detached signature;
- o
- bobcat_3.23.01-x.tar.gz: source archive;
- o
- bobcat_3.23.01-x_i386.changes: change log;
- o
- libbobcat1_3.23.01-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_3.23.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).