#include <balxml_formatter.h>
List of all members.
Public Types |
typedef
FormatterWhitespaceType::Enum | WhitespaceType |
Public Member Functions |
| Formatter (bsl::streambuf *output, int indentLevel=0, int spacesPerLevel=4, int wrapColumn=80, bslma::Allocator *basicAllocator=0) |
| Formatter (bsl::ostream &output, int indentLevel=0, int spacesPerLevel=4, int wrapColumn=80, bslma::Allocator *basicAllocator=0) |
| Formatter (bsl::streambuf *output, const EncoderOptions &encoderOptions, int indentLevel=0, int spacesPerLevel=4, int wrapColumn=80, bslma::Allocator *basicAllocator=0) |
| Formatter (bsl::ostream &output, const EncoderOptions &encoderOptions, int indentLevel=0, int spacesPerLevel=4, int wrapColumn=80, bslma::Allocator *basicAllocator=0) |
template<class TYPE > |
void | addAttribute (const bsl::string_view &name, const TYPE &value, int formattingMode=0) |
void | addBlankLine () |
void | addComment (const bsl::string_view &comment, bool forceNewline=true) |
template<class TYPE > |
void | addData (const TYPE &value, int formattingMode=0) |
template<class TYPE > |
void | addElementAndData (const bsl::string_view &name, const TYPE &value, int formattingMode=0) |
void | addHeader (const bsl::string_view &encoding="UTF-8") |
template<class TYPE > |
void | addListData (const TYPE &value, int formattingMode=0) |
void | addNewline () |
int | addValidComment (const bsl::string_view &comment, bool forceNewline=true, bool omitEnclosingWhitespace=false) |
void | closeElement (const bsl::string_view &name) |
void | flush () |
void | openElement (const bsl::string_view &name, WhitespaceType whitespaceMode=e_PRESERVE_WHITESPACE) |
bsl::ostream & | rawOutputStream () |
void | reset () |
const EncoderOptions & | encoderOptions () const |
int | indentLevel () const |
int | outputColumn () const |
int | spacesPerLevel () const |
int | status () const |
int | wrapColumn () const |
Static Public Attributes |
static const WhitespaceType | e_PRESERVE_WHITESPACE |
static const WhitespaceType | e_WORDWRAP |
static const WhitespaceType | e_WORDWRAP_INDENT |
static const WhitespaceType | e_NEWLINE_INDENT |
static const WhitespaceType | BAEXML_NEWLINE_INDENT |
Detailed Description
This class provides a set of XML-style formatting utilities that enable transparent indentation and wrapping for users attempting to format data with XML tags and attributes. A formatter object is instantiated with a pointer to an output stream or streambuf. Users can then use the provided utilities to write element tags, attributes, data in a valid XML sequence into the underlying stream.
This class has no features that would impair thread safety. However, it does not mediate between two threads attempting to access the same stream.
See Component balxml_formatter
Member Typedef Documentation
Constructor & Destructor Documentation
balxml::Formatter::Formatter |
( |
bsl::streambuf * |
output, |
|
|
int |
indentLevel = 0 , |
|
|
int |
spacesPerLevel = 4 , |
|
|
int |
wrapColumn = 80 , |
|
|
bslma::Allocator * |
basicAllocator = 0 | |
|
) |
| | |
balxml::Formatter::Formatter |
( |
bsl::ostream & |
output, |
|
|
int |
indentLevel = 0 , |
|
|
int |
spacesPerLevel = 4 , |
|
|
int |
wrapColumn = 80 , |
|
|
bslma::Allocator * |
basicAllocator = 0 | |
|
) |
| | |
balxml::Formatter::Formatter |
( |
bsl::streambuf * |
output, |
|
|
const EncoderOptions & |
encoderOptions, |
|
|
int |
indentLevel = 0 , |
|
|
int |
spacesPerLevel = 4 , |
|
|
int |
wrapColumn = 80 , |
|
|
bslma::Allocator * |
basicAllocator = 0 | |
|
) |
| | |
balxml::Formatter::Formatter |
( |
bsl::ostream & |
output, |
|
|
const EncoderOptions & |
encoderOptions, |
|
|
int |
indentLevel = 0 , |
|
|
int |
spacesPerLevel = 4 , |
|
|
int |
wrapColumn = 80 , |
|
|
bslma::Allocator * |
basicAllocator = 0 | |
|
) |
| | |
Construct an object to format XML data into the specified output
stream or streambuf. Optionally specify encoderOptions
, initial indentLevel
, spacesPerLevel
, and wrapColumn
for formatting. An indentLevel
of 0 (the default) indicates the root element will have no indentation. A wrapColumn
of 0 will cause the formatter to behave as though the line length were infinite, but will still insert newlines and indent when starting a new element. A wrapColumn
of -1 will cause output to be formatted in "compact" mode -- with no added newlines or indentation. Optionally specify a basicAllocator
used to supply memory. If basicAllocator
is 0, the currently install default allocator is used. The behavior is undefined if the output
stream or streambuf is destroyed before
Member Function Documentation
template<class TYPE >
void balxml::Formatter::addAttribute |
( |
const bsl::string_view & |
name, |
|
|
const TYPE & |
value, |
|
|
int |
formattingMode = 0 | |
|
) |
| | |
Add an attribute of the specified name
and specified value
to the currently open element. value
can be of the following types: char
, short
, int
, bsls::Types::Int64
, float
, double
, bsl::string
, bdlt::Datetime
, bdlt::Date
, and bdlt::Time
. Precede this name="value" pair with a single space. Wrap line (write the attribute on next line with proper indentation), if the length of name="value" is too long. Optionally specify a formattingMode
used to control the formatting of the value
. If value
is of type bsl::string
, it is truncated at any invalid UTF-8 byte-sequence or any control character. The list of invalid control characters includes characters in the range [0x00, 0x20)
and 0x7F
(DEL) but does not include 0x9
, 0xA
, and 0x0D
. The five special characters: apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML. If value
is of type char
, it is cast to a signed byte value with a range '[ -128 .. 127 ]'. The behavior is undefined unless the last manipulator was openElement
or addAttribute
.
void balxml::Formatter::addBlankLine |
( |
|
) |
|
Insert one or two newline characters into the output stream such that a blank line results. If the last output was a newline, then only one newline is added, otherwise two newlines are added. If following a call to openElement
, or addAttribute
, add a closing >
to the opened tag.
void balxml::Formatter::addComment |
( |
const bsl::string_view & |
comment, |
|
|
bool |
forceNewline = true | |
|
) |
| | |
[!DEPRECATED!] Use addValidComment
instead.
Write the specified comment
into the stream. The optionally specified forceNewline
, if true, forces to start a new line solely for the comment if it's not on a new line already. Otherwise, comments continue on current line. If an element-opening tag is not completed with a >
, addComment
will add >
.
template<class TYPE >
void balxml::Formatter::addData |
( |
const TYPE & |
value, |
|
|
int |
formattingMode = 0 | |
|
) |
| | |
Add the specified value
as the data content, where value
can be of the following types: char
, short
, int
, bsls::Types::Int64
, float
, double
, bsl::string
, bdlt::Datetime
, bdlt::Date
, and bdlt::Time
. Perform no line-wrapping or indentation as if the whitespace constraint were always BAEXML_PRESERVE_WHITESPACE
in openElement
, with the only exception that an initial newline and an initial indent is added when openElement
specifies BAEXML_NEWLINE_INDENT
option. If value
is of type bsl::string
, it is truncated at any invalid UTF-8 byte-sequence or any control character. The list of invalid control characters includes characters in the range [0x00, 0x20)
and 0x7F
(DEL) but does not include 0x9
, 0xA
, and 0x0D
. The five special characters: apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML. If value
is of type char
, it is cast to a signed byte value with a range of '[ -128 .. 127 ]'. Optionally specify the formattingMode
to specify the format used to encode value
. The behavior is undefined if the call is made when there are no opened elements.
template<class TYPE >
void balxml::Formatter::addElementAndData |
( |
const bsl::string_view & |
name, |
|
|
const TYPE & |
value, |
|
|
int |
formattingMode = 0 | |
|
) |
| | |
Add element of the specified name
and the specified value
as the data content. This has the same effect as calling the following sequence: openElement(name); addData(value), closeElement(name);
. Optionally specify the formattingMode
.
void balxml::Formatter::addHeader |
( |
const bsl::string_view & |
encoding = "UTF-8" |
) |
|
Add XML header with optionally specified encoding
. Version is always "1.0". The behavior is undefined unless addHeader
is the first manipulator (with the exception of rawOutputStream
) after construction or reset
.
template<class TYPE >
void balxml::Formatter::addListData |
( |
const TYPE & |
value, |
|
|
int |
formattingMode = 0 | |
|
) |
| | |
Add the specified value
as the data content, where value
can be of the following types: char
, short
, int
, bsls::Types::Int64
, float
, double
, bsl::string
, bdlt::Datetime
, bdlt::Date
, and bdlt::Time
. Prefix the value
with a space(0x20
) unless the data being added is the first data on a line. When adding the data makes the line too long, perform line-wrapping and indentation as determined by the whitespace constraint used when the current element is opened with openElement
. If value
is of type bsl::string
, it is truncated at any invalid UTF-8 byte-sequence or any control character. The list of invalid control characters includes characters in the range [0x00, 0x20)
and 0x7F
(DEL) but does not include 0x9
, 0xA
, and 0x0D
. The five special characters: apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML. If value
is of type char
, it is cast to a signed byte value with a range of [ -128 .. 127 ]
. Optionally specify the formattingMode
to specify the format used to encode value
. The behavior is undefined if the call is made when there are no opened elements.
void balxml::Formatter::addNewline |
( |
|
) |
|
Insert a literal newline into the XML output. If following a call to openElement
, or addAttribute
, add a closing >
to the opened tag.
int balxml::Formatter::addValidComment |
( |
const bsl::string_view & |
comment, |
|
|
bool |
forceNewline = true , |
|
|
bool |
omitEnclosingWhitespace = false | |
|
) |
| | |
Write the specified comment
into the stream. Optionally specify forceNewline
that specifies if a new line should be added before the comment if it is not already on a new line. If forceNewline
is not specified then a new line is inserted for comments not already on a new line. Also optionally specify an omitEnclosingWhitespace
that specifies if a space character should be omitted before and after comment
. If omitEnclosingWhitespace
is not specified then a space character is inserted before and after comment
. Return 0 on success, and non-zero value otherwise. Note that a non-zero return value is returned if either comment
contains --
or if omitEnclosingWhitespace
is true
and comment
ends with -
. Also note that if an element-opening tag is not completed with a >
, addValidComment
will add >
.
void balxml::Formatter::closeElement |
( |
const bsl::string_view & |
name |
) |
|
Decrement the indent level and add the closing tag for the element of the specified name
. If the element does not have content, write />
and a newline into stream. Otherwise, write </name>
and a newline. If this </name>
does not share the same line with data, or it follows another element's closing tag, indent properly before writing </name>
and the newline. If name
is root element, flush the output stream. The behavior is undefined if name
is not the most recently opened element that's yet to be closed.
void balxml::Formatter::flush |
( |
|
) |
|
Insert the closing >
if there is an incomplete tag, and flush the output stream.
Open an element of the specified name
at current indent level with the optionally specified whitespace constraint whitespaceMode
for its textual data and increment indent level. whitespaceMode
constrains how textual data is written with addListData
for the current element, but not its nested elements. The behavior is undefined if openElement
is called after the root element is closed and there is no subsequent call to reset
.
bsl::ostream& balxml::Formatter::rawOutputStream |
( |
|
) |
|
Return a reference to the underlining output stream. This method is provided in order to enable user to temporarily jump out of the formatter and write user's own free-lance content directly to the stream.
void balxml::Formatter::reset |
( |
|
) |
|
Reset the formatter such that it can be used to format a new XML document as if the formatter were just constructed
Return the encoder options being used.
int balxml::Formatter::indentLevel |
( |
|
) |
const |
Return the current level of indentation.
int balxml::Formatter::outputColumn |
( |
|
) |
const |
Return the current column position at a line where next output starts. This is unreliable if called after free-lance information is written onto the stream returned by rawOutputStream
int balxml::Formatter::spacesPerLevel |
( |
|
) |
const |
Return the number of spaces per indentation level.
int balxml::Formatter::status |
( |
|
) |
const |
Return 0 if no errors have been detected since construction or since the last call to reset
, otherwise return a negative value.
int balxml::Formatter::wrapColumn |
( |
|
) |
const |
Return the line width where line-wrapping takes place.
Member Data Documentation
The documentation for this class was generated from the following file: