.TH "FBB::OFoldBuf" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Fold long lines" .PP .SH "NAME" FBB::OFoldBuf \- Folds long lines written to ostream .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" \fBFBB::OFoldBuf\fP is a specialization of \fIFBB::OFilterBuf\fP folding long lines written to an \fIstd::ostream\fP object\&. The \fIOFoldBuf\fP writes the (folded) lines to a second \fIostream\fP (the \fIdestination stream\fP which is either used by or opened by the \fIOFoldBuf\fP object)\&. .PP Internally the \fIOFoldBuf\fP defines its actions using a little finite state automation distinguishing three states (INDENT, WS and NON_WS) and three character categories (\fI\en\fP, other white space characters (space), and non\-space characters)\&. The nine combinations resulting from these two sets are discussed below\&. .PP \fIOFoldBuf\fP objects will never fold lines in the middle of series of non\-blank characters (called a `word\(cq\& 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\&. .PP 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\&. .PP What follows is a description of the \fIFinite State Automaton\fP (FSA) defining what happens when various character types appear at its three states\&. The phrase `\&.\&.\&. is written\(cq\& means that the described information is written to the \fIostream\fP used or opened by the \fIOFoldBuf\fP object\&. \fIOFoldBuf\fP\(cq\&s initial state is \fIINDENT\fP: .PP .TS tab(~); lll --- lll lll lll lll lll lll --- lll lll lll lll lll lll lll --- lll lll lll lll lll lll lll lll --- c. State~char\&.~description INDENT~\en~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~\en~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~\en~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; .TE .PP .SH "NAMESPACE" \fBFBB\fP .br All constructors, members, operators and manipulators, mentioned in this man\-page, are defined in the namespace \fBFBB\fP\&. .PP .SH "INHERITS FROM" \fIFBB::OFilterBuf\fP .PP .SH "ENUMERATION" The enumeration \fITabsOrBlanks\fP 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: .IP o \fBBLANKS\fP: .br The default, indicating that the left margin is specified and written as a number of blanks; .IP o \fBTABS\fP: .br Indicating that the left margin is specified and written as a number of tab\-characters\&. .PP The enumeration \fITrailingBlanks\fP is used to configure the \fIOFoldBuf\fP 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: .IP o \fBIGNORE_TRAILING_BLANKS\fP: .br 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 \fIstd::ostream\fP\&. This is the default used by \fIOFoldBuf\fP objects\&. .IP o \fBKEEP_TRAILING_BLANKS\fP: .br This indicates that trailing blanks at the final line if it is not terminated by a newline should be written to the destination \fIstd::ostream\fP .PP .SH "CONSTRUCTORS" .IP o \fBOFoldBuf(size_t leftIndent = 0, size_t rightMargin = 80, TabsOrBlanks tob = BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS)\fP: .br This constructor initializes an \fIOFoldBuf\fP object but does not associate it with a destination stream\&. It can also be used as the default constructor\&. .IP .IP o \fBOFoldBuf(char const *fname, size_t leftIndent = 0, size_t rightMargin = 80, TabsOrBlanks tob = BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS)\fP: .br This constructor initializes an \fIOFoldBuf\fP object and opens (using \fIstd::ios::out\fP) the destination stream using the name specified as its \fIfname\fP argument\&. .IP .IP o \fBOFoldBuf(std::ostream &stream, size_t leftIndent = 0, size_t rightMargin = 80, TabsOrBlanks tob = BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS)\fP: .br This constructor initializes an \fIOFoldBuf\fP object and uses as its destination stream the \fIstd::ostream stream\fP\&. .PP The destructor writes any buffered information to the destination stream and will then flush the destination stream\&. .PP Copy and move constructors (and assignment operators) are not available\&. .PP .SH "MEMBER FUNCTIONS" All members of \fBFBB::OFilterBuf\fP, in particular its \fIout()\fP and \fIreset\fP members are available, as \fBFBB::OFoldBuf\fP inherits from this class\&. .IP o \fBvoid setMargins(size_t leftMargin, size_t rightMargin)\fP: .br This member can be used to modify the left\- and right folding margins\&. Note that the left margin may also be modified using the \fIFBB::lm\fP and \fIFBB::mlm\fP manipulators\&. .IP .IP o \fBvoid setTrailingBlanks(TrailingBlanks tb)\fP: .br This member can be used to modify the currently used \fITrailingBlanks\fP parameter\&. .IP .IP o \fBvoid useBlanks()\fP: .br This member can be used to select blanks to be used when inserting left margins\&. .IP .IP o \fBvoid useTabs(size_t tabWidth = 8)\fP: .br 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\&. .PP .SH "STATIC MEMBER FUNCTIONS" .PP .IP o \fBsize_t leftMargin(std::ostreambuf const *buffer)\fP: .br This member returns the current left margin setting of the \fIOFoldBuf\fP object passed to it as its argument\&. The member defines a \fIstd::streambuf\fP parameter which is down cast to an \fIOFoldBuf\fP and an \fIFBB::Exception\fP exception is thrown if that cast fails\&. .IP o \fBsize_t rightMargin(std::ostreambuf const *buffer)\fP: .br This member returns the current right margin setting of the \fIOFoldBuf\fP object passed to it as its argument\&. The member\(cq\&s parameter is down cast in the same way as \fIleftMargin()\fP\(cq\&s argument: an \fIFBB::Exception\fP exception is thrown if that cast fails\&. .PP .SH "EXAMPLE" .nf #include #include #include #include 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 << \(cq\&\en\(cq\&; } .fi .PP .SH "FILES" \fIbobcat/ofoldbuf\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBlm\fP(3bobcat), \fBmlm\fP(3bobcat), \fBofilterbuf\fP(3bobcat), \fBofoldstream\fP(3bobcat) .PP .SH "BUGS" None Reported\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries, headers and manual pages; .PP .SH "BOBCAT" Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&. .PP .SH "COPYRIGHT" This is free software, distributed under the terms of the GNU General Public License (GPL)\&. .PP .SH "AUTHOR" Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&. .PP