Description:

This class is used to format textual output, like console output.

One central static method is Format, which format a "paragraph" that starts at a certain index of the managed AString buffer and reaches to its end.

When an instance of the class is created, the members of the class provide the text buffer as well as the other parameters which are needed for the static method. With methods Add, member Formatter is used to append the given parameters and then the new paragraph is formatted using static method Format.
This way, a longer text might be built by repetitive calls.

Definition at line 35 of file paragraphs.hpp.

#include <paragraphs.hpp>

Collaboration diagram for Paragraphs:

[legend]

Public Static Method Index:
static ALIB_API void	Format (AString &text, integer startIdx, integer lineWidth, character justifyChar, integer &maxLineWidth, const String &indentFirstLine=nullptr, const String &indentOtherLines=nullptr)

Public Field Index:
AString &	Buffer

integer	DetectedMaxLineWidth =0

SPFormatter	Formatter

TLocalString	IndentFirstLine

TLocalString	IndentOtherLines

std::stack< integer >	IndentSizesFirstLine

std::stack< integer >	IndentSizesOtherLines

character	JustifyChar = '\0'

integer	LineWidth = 0

std::vector< character >	MarkerBullets = {'', '-', '', '-', '*', '-'}

character	MarkerChar = '@'

Public Method Index:
ALIB_API	Paragraphs ()

ALIB_API	Paragraphs (AString &externalBuffer)

ALIB_API void	Add (Boxes &args)

template<typename... BoxedObjects>
Paragraphs &	Add (const BoxedObjects &... args)

ALIB_API void	AddMarked (Boxes &args)

template<typename... BoxedObjects>
Paragraphs &	AddMarked (const BoxedObjects &... args)

ALIB_API Paragraphs &	Clear ()

ALIB_API Paragraphs &	PopIndent ()

ALIB_API Paragraphs &	PushIndent (const String &indentFirstLine, const String &indentOtherLines=nullptr)

ALIB_API Paragraphs &	PushIndent (uinteger qty, character fillChar=' ')

AString &	RemoveLastNewLine ()

Field Details:

◆ boxes

Boxes boxes

protected

Internally reused list of boxes.

Definition at line 137 of file paragraphs.hpp.

◆ Buffer

AString& Buffer

A reference to the text buffer. Either refers to otherwise protected field text or to what was given in alternative construction.

Definition at line 47 of file paragraphs.hpp.

◆ DetectedMaxLineWidth

integer DetectedMaxLineWidth =0

This field is increased whenever a line of text added is longer than its current value. Might be used by to detect the maximum line width when field LineWidth is set to 0 and hence no auto wrap is done.

Definition at line 132 of file paragraphs.hpp.

◆ Formatter

SPFormatter Formatter

The formatter to use. In the constructor, this shared pointer is initialized with the

ALib Default Formatter , in the case that this object's template character type equals alib::character, or
A shared pointer to a newly created formatter object of corresponding character type otherwise.

Definition at line 57 of file paragraphs.hpp.

◆ IndentFirstLine

TLocalString IndentFirstLine

Used as parameter indent of static method invocations.
The indent string of the first line.

This field can either be manipulated by direct access or preferably with overloaded methods::PushIndent and PopIndent.

Note: For technical reasons the template parameters of this member's type are missing in this documentation. In the source code, the type iss TLocalString<TChar,64>.

Definition at line 93 of file paragraphs.hpp.

◆ IndentOtherLines

TLocalString IndentOtherLines

Used as parameter indent of static method invocations.
The indent string of text lines, excluding the first line.

This field can either be manipulated by direct access or preferably with overloaded methods::PushIndent and PopIndent.

Note: For technical reasons the template parameters of this member's type are missing in this documentation. In the source code, the type iss TLocalString<TChar,64>.

Definition at line 106 of file paragraphs.hpp.

◆ IndentSizesFirstLine

std::stack<integer> IndentSizesFirstLine

The stack of indent sub-string sizes in string IndentFirstLine. Used with PushIndent and PopIndent.

Definition at line 118 of file paragraphs.hpp.

◆ IndentSizesOtherLines

std::stack<integer> IndentSizesOtherLines

The stack of indent sub-string sizes in string IndentOtherLines. Used with PushIndent and PopIndent.

Definition at line 124 of file paragraphs.hpp.

◆ JustifyChar

character JustifyChar = '\0'

Used as parameter justifyChar of static method invocations. Usually set to ' ' to enable paragraph width justification.
Defaults to '\0' which disables it.

Definition at line 67 of file paragraphs.hpp.

◆ LineWidth

integer LineWidth = 0

Used as parameter lineWidth of static method invocations.

Definition at line 60 of file paragraphs.hpp.

◆ markedBuffer

AString markedBuffer

protected

Buffer for processing marked text.

Definition at line 140 of file paragraphs.hpp.

◆ markerBulletLevel

size_t markerBulletLevel =0

protected

Buffer for processing marked text.

Definition at line 143 of file paragraphs.hpp.

◆ MarkerBullets

std::vector<character> MarkerBullets = {'*', '-', '*', '-', '*', '-'}

The bullet used with increasing bullet depths.

Definition at line 78 of file paragraphs.hpp.

◆ MarkerChar

character MarkerChar = '@'

Used to detect special commands given with format strings.

See also: Method AddMarked for more information.

Defaults to '@'.

Definition at line 75 of file paragraphs.hpp.

◆ text

AString text

protected

Internal buffer, used for field Paragraphs, if no external string object was given.

Definition at line 42 of file paragraphs.hpp.

Constructor(s) / Destructor Details::

◆ Paragraphs() [1/2]

Paragraphs ( )

Parameterless constructor. Internal buffer text will be used with reference Buffer.

Definition at line 33 of file paragraphs.cpp.

Here is the call graph for this function:

◆ Paragraphs() [2/2]

Paragraphs ( AString & externalBuffer )

Alternative constructor that accepts an external buffer to use.

Parameters

externalBuffer The external buffer to use and fill.

Definition at line 40 of file paragraphs.cpp.

Method Details:

◆ Add() [1/2]

void Add ( Boxes & args )

Appends the given objects args to the internal Buffer with the help of member Formatter. Then, static method Format is invoked, providing our public members as parameters. Finally, a newline sequence is added to Buffer, but only if the buffer is not empty and if it does not already end with a newline sequence.

Exceptions

alib::lang::format::FMTExceptions Rethrows exceptions from the formatter caused by errors in provided args .

Parameters

args	The list of arguments to add.

Definition at line 98 of file paragraphs.cpp.

Here is the call graph for this function:

◆ Add() [2/2]

template<typename... BoxedObjects>

Paragraphs & Add ( const BoxedObjects &... args )

inline

Variadic template argument version of Add.

Parameters

args	The variadic list of arguments to add.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 227 of file paragraphs.hpp.

Here is the call graph for this function:

◆ AddMarked() [1/2]

void AddMarked ( Boxes & args )

This method implements a pre-processing of the text prior to Add paragraphs found in the text.

The pre-processing is quite simple. Its purpose is to allow longer strings (e.g. loaded from a resource pool) with multiple paragraphs to be formatted by embedded escape sequences to include indents and nested bullet schemes.

The escape sequences begin with the character stored in field MarkerChar, which defaults to '@'. The following table documents the sequences:

Sequence	Description
@@	Inserts the marker character itself.
@>>	Indent text by two spaces
@<<	Un-indent text by two spaces
@*>	Increases bullet level.
@<*	Decreases bullet level
@P	Inserts a new line (like ' ') but without ending the current and starting a new bullet point.
@HLc	Inserts a horizontal line of width LineWidth using c as fill character.

The nested bullet point characters are received from vector MarkerBullets.

Exceptions

alib::lang::format::FMTExceptions

UnknownMarker
EndmarkerWithoutStart
Rethrows formatter exceptions occurring due to errors in provided args .

Parameters

args	The list of arguments to add.

Definition at line 162 of file paragraphs.cpp.

Here is the call graph for this function:

◆ AddMarked() [2/2]

template<typename... BoxedObjects>

Paragraphs & AddMarked ( const BoxedObjects &... args )

inline

Variadic template argument version of AddMarked.

Exceptions

alib::lang::format::FMTExceptions

Parameters

args	The variadic list of arguments to add.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 279 of file paragraphs.hpp.

Here is the call graph for this function:

◆ Clear()

Paragraphs & Clear ( )

Clears field Buffer.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 84 of file paragraphs.cpp.

Here is the call graph for this function:

◆ Format()

void Format	(	AString &	text,
		integer	startIdx,
		integer	lineWidth,
		character	justifyChar,
		integer &	maxLineWidth,
		const String &	indentFirstLine = nullptr,
		const String &	indentOtherLines = nullptr )

static

Formats one or more paragraphs (separated by NewLine symbols) with three optional features:

Wrapping of lines longer than lineWidth (word wrap)
Justify the text, which here means "full justification", i.e. format the text to have lines of the exact same width.
Adding an indentation to each line with an optionally different indentation for the first line after a NewLine symbol and subsequent ones.

The paragraph starts at startIdx and all of the rest of the string is treated as one paragraph. New-line character sequences found within the paragraph are considered manual line ends. Hence, no block formatting for lines ending with a new line character is performed.

The method is static and hence can be used with arbitrary buffers. Non-static methods Add invoke this methods after adding the given content to the internal buffer. Furthermore, convenience functions and corresponding member variables, simplify the use of this method, when indirectly used through an instance of the class.

Parameters

	text	The text containing the paragraph to format.
	startIdx	The start of the paragraph.
	lineWidth	The width of the line. If `0` or negative, no line wrap is performed.
	justifyChar	If this is unequal to `'\0'` it denotes the fill character used to justify the paragraph. Defaults to `'\0'`, which disables justification.
[out]	maxLineWidth	Provides the maximum width of all text lines written.
	indentFirstLine	The indent string of the first line. Defaults to `nullptr`.
	indentOtherLines	The indent string of subsequent lines. Defaults to `nullptr`.

Definition at line 297 of file paragraphs.cpp.

Here is the call graph for this function:

◆ PopIndent()

Paragraphs & PopIndent ( )

Removes the most recently added indent.

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 71 of file paragraphs.cpp.

Here is the call graph for this function:

◆ PushIndent() [1/2]

Paragraphs & PushIndent	(	const String &	indentFirstLine,
		const String &	indentOtherLines = nullptr )

Add the given strings to members IndentFirstLine and IndentOtherLines.

Parameters

indentFirstLine	The string to add to the current indentation stored in IndentFirstLine.
indentOtherLines	The string to add to the current indentation stored in IndentOtherLines. Defaults to NullString, which sets it to the same value as indentFirstLine .

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 47 of file paragraphs.cpp.

Here is the call graph for this function:

◆ PushIndent() [2/2]

Paragraphs & PushIndent	(	uinteger	qty,
		character	fillChar = ' ' )

Add a given number of characters (default is spaces) to the indentation strings IndentFirstLine and IndentOtherLines.

Use PopIndent to remove the indent.

Parameters

qty	The quantity of characters to add or remove
fillChar	The character (used only if qty is positive).

Returns: A reference to ourselves to allow concatenated calls.

Definition at line 61 of file paragraphs.cpp.

Here is the call graph for this function:

◆ RemoveLastNewLine()

AString & RemoveLastNewLine ( )

inline

Removes the last new line character at the end of the Buffer.

Returns: A reference to the text object.

Definition at line 292 of file paragraphs.hpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files:

Description:

Public Static Method Index:

Public Field Index:

Public Method Index:

Field Details:

◆ boxes

◆ Buffer

◆ DetectedMaxLineWidth

◆ Formatter

◆ IndentFirstLine

◆ IndentOtherLines

◆ IndentSizesFirstLine

◆ IndentSizesOtherLines

◆ JustifyChar

◆ LineWidth

◆ markedBuffer

◆ markerBulletLevel

◆ MarkerBullets

◆ MarkerChar

◆ text

Constructor(s) / Destructor Details::

◆ Paragraphs() [1/2]

◆ Paragraphs() [2/2]

Method Details:

◆ Add() [1/2]

◆ Add() [2/2]

◆ AddMarked() [1/2]

◆ AddMarked() [2/2]

◆ Clear()

◆ Format()

◆ PopIndent()

◆ PushIndent() [1/2]

◆ PushIndent() [2/2]

◆ RemoveLastNewLine()