FBB::OFoldBuf(3bobcat)

Fold long lines
(libbobcat-dev_6.02.02)

2005-2022

NAME

SYNOPSIS

DESCRIPTION

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

OFoldBuf 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 OFoldBuf object. OFoldBuf's initial state is INDENT:

NAMESPACE

INHERITS FROM

ENUMERATION

• BLANKS:
  The default, indicating that the left margin is specified and written as a number of blanks;
• TABS:
  Indicating that the left margin is specified and written as a number of tab-characters.

The enumeration TrailingBlanks is used to configure the OFoldBuf 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:

• 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 OFoldBuf objects.
• 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

• OFoldBuf(size_t leftIndent = 0, size_t rightMargin = 80, TabsOrBlanks tob = BLANKS, TrailingBlanks tb = IGNORE_TRAILING_BLANKS):
  This constructor initializes an OFoldBuf object but does not associate it with a destination stream. It can also be used as the default constructor.

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

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

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

• void setTrailingBlanks(TrailingBlanks tb):
  This member can be used to modify the currently used TrailingBlanks parameter.

• void useBlanks():
  This member can be used to select blanks to be used when inserting left margins.

• 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

• size_t leftMargin(std::ostreambuf const *buffer):
  This member returns the current left margin setting of the OFoldBuf object passed to it as its argument. The member defines a std::streambuf parameter which is down cast to an OFoldBuf and an FBB::Exception exception is thrown if that cast fails.
• size_t rightMargin(std::ostreambuf const *buffer):
  This member returns the current right margin setting of the OFoldBuf 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 <ostream>
    #include <string>
    #include <bobcat/ofoldbuf>

    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 << '\n';
    }
        

FILES

SEE ALSO

BUGS

BOBCAT PROJECT FILES

• https://fbb-git.gitlab.io/bobcat/: gitlab project page;
• bobcat_6.02.02-x.dsc: detached signature;
• bobcat_6.02.02-x.tar.gz: source archive;
• bobcat_6.02.02-x_i386.changes: change log;
• libbobcat1_6.02.02-x_*.deb: debian package containing the libraries;
• libbobcat1-dev_6.02.02-x_*.deb: debian package containing the libraries, headers and manual pages;

BOBCAT

COPYRIGHT

AUTHOR