tk::Print class

Contents

Pretty printer base. Contains general purpose printer functions. Using the functions defined here provides formatting, and a consistent look with simple client-side code. For formatting, the Boost Format library is used, see http://www.boost.org/doc/libs/release/libs.

Derived classes

class RNGPrint
RNGPrint : Print.
class unittest::UnitTestPrint
UnitTestPrint : tk::Print.

Public types

struct echoPolicies
Function object for echoing policies to screen.

Constructors, destructors, conversion operators

Print(const std::string& screen = {}, std::ostream& str = std::clog, std::ios_base::openmode mode = std::ios_base::out, std::ostream& qstr = std::cout) explicit

Public functions

template<Style s = VERBOSE>
auto save() const -> std::streambuf*
template<Style s = VERBOSE>
auto reset(std::streambuf* buf) -> std::streambuf*
template<Style s = VERBOSE>
void part(const std::string& t) const
template<Style s = VERBOSE>
void section(const std::string& t) const
template<Style s = VERBOSE>
void section(const std::string& name, const std::string& value) const
template<Style s = VERBOSE>
void subsection(const std::string& t) const
template<Style s = VERBOSE>
void title(const std::string& value) const
template<Style s = VERBOSE>
void item(const std::string& name) const
template<Style s = VERBOSE, typename T>
void item(const std::string& name, const T& value) const
template<Style s = VERBOSE, typename T>
void longitem(const std::string& name, const T& value) const
template<Style s = VERBOSE>
void item(const std::string& name, bool b) const
template<Style s = VERBOSE>
void item(const std::string& name, const tk::Timer::Watch& watch) const
template<Style s = VERBOSE>
void perfitem(const std::string& name, tk::real value) const
template<Style s = VERBOSE, class Container>
void list(const std::string& name, const Container& entries) const
template<class Option, Style s = VERBOSE, class Factory>
void list(const std::string& t, const Factory& factory) const
template<Style s = VERBOSE, class ClockFormat>
void time(const std::string& t, const std::vector<std::pair<std::string, ClockFormat>>& clock) const
template<Style s = VERBOSE>
void perf(const std::string& t, const std::vector<std::pair<std::string, tk::real>>& stat) const
template<Style s = VERBOSE>
void note(const std::string& msg) const
template<Style s = VERBOSE>
void diag(const std::string& msg) const
template<Style s = VERBOSE>
void diag(const std::vector<std::string>& labels, const std::vector<std::string>& values, bool precr = true) const
template<Style s = VERBOSE>
void diagstart(const std::string& msg) const
template<Style s = VERBOSE>
void diagend(const std::string& msg) const
template<Style s = VERBOSE>
void charestate(const std::unordered_map<int, std::vector<ChareState>>& state) const
template<std::size_t N, Style s = VERBOSE>
void progress(const std::array<std::string, N>& prefix, const std::array<int, N>& done, const std::array<int, N>& max, std::size_t& progress_size) const
template<Style s = VERBOSE, class Help>
void help(const std::string& executable, const Help& pool, const std::string& msg, const std::string& pfx = "") const
Formatted print of help of one-liners on all command-line parameters or control file keywords.
template<Style s = VERBOSE>
void version(const std::string& executable, const std::string& ver, const std::string& copyright) const
template<Style s = VERBOSE>
void license(const std::string& executable, const std::string& lic) const
template<Style s = VERBOSE>
void mandatory(const std::string& args) const
template<Style s = VERBOSE>
void usage(const std::string& executable, const std::string& example, const std::string& msg) const
template<Style s = VERBOSE, typename Info>
void bounds(const Info& info) const
Print lower and upper bounds for a keyword if defined.
template<Style s = VERBOSE, class HelpKw>
void helpkw(const std::string& executable, const HelpKw& kw) const
Formatted print of verbose help on a single command-line parameter or control file keyword.
template<Style s = VERBOSE>
void endpart() const
Print end of a part.
template<Style s = VERBOSE>
void endsubsection() const
Print end of subsection.
template<Style s = VERBOSE, typename T>
void raw(const T& r) const
template<Style s = VERBOSE>
auto stream() -> std::ostream& noexcept
template<Style s = VERBOSE>
auto stream() const -> std::ostream& noexcept
template<Style s = VERBOSE>
void headerRNGTest() const
template<Style s = VERBOSE>
void headerUnitTest() const
template<Style s = VERBOSE>
void headerWalker() const

Protected types

using format = boost::format
Format strings. See http://www.boost.org/doc/libs/release/libs/format.

Protected variables

const char m_section_bullet
Bullets.
const std::string m_section_indent
Indents.
std::stringstream m_null
Default verbose stream.
std::ostream& m_stream
Verbose stream.
std::ostream& m_qstream
Quiet stream.

Friends

template<typename T>
auto operator<<(const Print& os, const T& t) -> const Print&
template<typename T>
auto operator%(const Print& os, const T& t) -> const Print&
auto operator%(const Print& os, std::ostream&(*)(std::ostream&) pf) -> const Print&
auto operator<<(const Print& os, std::ostream&(*)(std::ostream&) pf) -> const Print&

Function documentation

tk::Print::Print(const std::string& screen = {}, std::ostream& str = std::clog, std::ios_base::openmode mode = std::ios_base::out, std::ostream& qstr = std::cout) explicit

Parameters
screen in Screen output filename. If an empty string is passed, it is assumed that client code does not want to save the stream into a file.
str in/out Verbose stream
mode in Open mode for screen output file, see http://en.cppreference.com/w/cpp/io/ios_base/openmode
qstr in/out Quiet stream

Constructor: Quiet output by default, only stuff written to qstr shown.

Instantiate with str = std::cout for verbose output. Any

template<Style s = VERBOSE>
std::streambuf* tk::Print::save() const

Returns The internal stream buffer of the stream

Save pointer to stream. This function, used in conjunction with reset(), can be used to pass streams around. This is not possible in general, since streams are not copyable. See this in action in, e.g., Control/Walker/CmdLine/Parser.C.

template<Style s = VERBOSE>
std::streambuf* tk::Print::reset(std::streambuf* buf)

Parameters
buf in Stream buffer of a stream
Returns The internal stream buffer of the stream

Reset stream to streambuf given. This function, used in conjunction with save(), can be used to pass streams around. This is not possible in general, since streams are not copyable. See this in action in, e.g., Control/Walker/CmdLine/Parser.C.

template<Style s = VERBOSE>
void tk::Print::part(const std::string& t) const

Parameters
t in Part title to be printed

Formatted print of part header: title.

template<Style s = VERBOSE>
void tk::Print::section(const std::string& t) const

Parameters
t in Section title to be printed

Formatted print of section header: t.

template<Style s = VERBOSE>
void tk::Print::section(const std::string& name, const std::string& value) const

Parameters
name in Section title to be printed
value in Section value to be printed

Formatted print of section header: title : value.

template<Style s = VERBOSE>
void tk::Print::subsection(const std::string& t) const

Parameters
t in Subsection title to be printed

Formatted print of subsection header: title.

template<Style s = VERBOSE>
void tk::Print::title(const std::string& value) const

Parameters
value in Title string to be printed

Formatted print of title.

template<Style s = VERBOSE>
void tk::Print::item(const std::string& name) const

Parameters
name in Item name to be printed

Formatted print of item: name.

template<Style s = VERBOSE, typename T>
void tk::Print::item(const std::string& name, const T& value) const

Parameters
name in Item name to be printed
value in Item value to be printed

Formatted print of item: name : value

template<Style s = VERBOSE, typename T>
void tk::Print::longitem(const std::string& name, const T& value) const

Parameters
name in Long item name to be printed
value in Item value to be printed

Formatted print of item with wide name: name : value

template<Style s = VERBOSE>
void tk::Print::item(const std::string& name, bool b) const

Parameters
name in Item name to be printed
b in Item value as bool to be printed

Formatted print of item: name : bool boost::format does not directly support std::boolalpha, so it must be done via boost::io::group, hence this overload for when the item value to be printed is of type bool, which will print true/false instead of 1/0.

template<Style s = VERBOSE>
void tk::Print::item(const std::string& name, const tk::Timer::Watch& watch) const

Parameters
name in Item name to be printed
watch in Watch (in hours, minutes, seconds) to be printed as item value

Formatted print of item: h:m:s.

template<Style s = VERBOSE>
void tk::Print::perfitem(const std::string& name, tk::real value) const

Parameters
name in Performance statistic name to be printed
value in Performance statistic value

Formatted print of a performance statistic (an item of a list)

template<Style s = VERBOSE, class Container>
void tk::Print::list(const std::string& name, const Container& entries) const

Parameters
name in Name of a section (consisting of a list) to be printed
entries in Container of type Container whose elements to be printed. Container must be iterable, e.g., possible to be used in a range-based for loop.

Formatted print of a list: name: entries...

template<class Option, Style s = VERBOSE, class Factory>
void tk::Print::list(const std::string& t, const Factory& factory) const

Parameters
t in Title of the section containing a list
factory in Factory (an std::map) whose values are printed interpreted as options (classes deriving from Toggle), defining the name querying member function name().

Formatted print of a list: name: option names...

template<Style s = VERBOSE, class ClockFormat>
void tk::Print::time(const std::string& t, const std::vector<std::pair<std::string, ClockFormat>>& clock) const

Parameters
t in Title of section containing a list of elapsed times
clock in std::vector of strings (clock names) and associated timers which could be in various formats as long as there is a corresponding item() overload that can apply operator << for outputing their value to an output stream. Examples of allowed ClockFormats are: tk::Timer::Watch, which is a struct containing a timestamp in h:m:s format, and the return value of Timer::dsec(), which is a tk::real.

Formatted print of elapsed times

template<Style s = VERBOSE>
void tk::Print::perf(const std::string& t, const std::vector<std::pair<std::string, tk::real>>& stat) const

Parameters
t in Title of section containing a list of performance stats
stat in std::vector of strings (names of a performance statistics) and associated values.

Formatted print of performance statistics

template<Style s = VERBOSE>
void tk::Print::note(const std::string& msg) const

Parameters
msg in Message to print as a note

Formatted print of a note

template<Style s = VERBOSE>
void tk::Print::diag(const std::string& msg) const

Parameters
msg in Message to print as a diagnostics message

Echo formatted print of a diagnostics message

template<Style s = VERBOSE>
void tk::Print::diag(const std::vector<std::string>& labels, const std::vector<std::string>& values, bool precr = true) const

Parameters
labels in Label parts of diagnostics message
values in Value parts of diagnostics message
precr in If true start with a CR/LF, if false end with it

Echo formatted print of a diagnostics message within a progress section

template<Style s = VERBOSE>
void tk::Print::diagstart(const std::string& msg) const

Parameters
msg in First part of message to print as a diagnostics message

Start formatted print of a diagnostics message Start formatted print of a diagnostics message

template<Style s = VERBOSE>
void tk::Print::diagend(const std::string& msg) const

Parameters
msg in Last part of message to print as a diagnostics message

Finish formatted print of a diagnostics message

template<Style s = VERBOSE>
void tk::Print::charestate(const std::unordered_map<int, std::vector<ChareState>>& state) const

Parameters
state in State map to print

Print chare state collected

template<std::size_t N, Style s = VERBOSE>
void tk::Print::progress(const std::array<std::string, N>& prefix, const std::array<int, N>& done, const std::array<int, N>& max, std::size_t& progress_size) const

Parameters
prefix in Strings to output prefixing the progress report
done in Array of integers indicating how many have been done
max in Array of integers indicating how many to be done
progress_size in Size of previous progress report (to overwrite)

Echo formatted print of a progress message All input arrays are the same size. The prefix strings are optional, i.e., they can be empty strings. The function generates an output to the stream configured in the following fashion: pre1[done1/max1], pre2[done2/max2], ..., e.g., r:[1/3], b[2/8]. Whenever this function is called, a number of backspaces are put into the stream so that the new progress report string overwrites the old one. In order to backtrack the correct amount, the length of the old progress report is stored (by whatever object holds us) and passed in by reference in progress_size, which is overwritten here once it has been used for backtracking. Therefore, for restarting a new series of progress reports, this variable must be zeroed. Also, it is best to not to interleave multiple tasks, because even if a different progress_size is kept for each, there is no regard as to which line we output to in the stream. In other words, multiple task outputs will be intermingled, leading to confusing screen output.

template<Style s = VERBOSE, class Help>
void tk::Print::help(const std::string& executable, const Help& pool, const std::string& msg, const std::string& pfx = "") const

Formatted print of help of one-liners on all command-line parameters or control file keywords.

Parameters
executable in Name of executable to output help for
pool in std::map of keywords and their associated information
msg in Message to print after exectuable in the title
pfx in Prefix in front of alias, double prefix in front of keyword

template<Style s = VERBOSE>
void tk::Print::version(const std::string& executable, const std::string& ver, const std::string& copyright) const

Parameters
executable in Name of executable to output license for
ver in Version to output
copyright in Copyright info to output

Print version information

template<Style s = VERBOSE>
void tk::Print::license(const std::string& executable, const std::string& lic) const

Parameters
executable in Name of executable to output license for
lic in License info to output

Print license information

template<Style s = VERBOSE>
void tk::Print::mandatory(const std::string& args) const

Parameters
args in Mandaatory-arguments infor to output

Print mandatory arguments information

template<Style s = VERBOSE>
void tk::Print::usage(const std::string& executable, const std::string& example, const std::string& msg) const

Parameters
executable in Name of executable to output usage info for
example in Example command line to output
msg in Message to output after example

Print example usage information

template<Style s = VERBOSE, class HelpKw>
void tk::Print::helpkw(const std::string& executable, const HelpKw& kw) const

Formatted print of verbose help on a single command-line parameter or control file keyword.

Parameters
executable in Name of executable to output help for
kw in Keyword help struct on which help is to be printed

template<Style s = VERBOSE, typename T>
void tk::Print::raw(const T& r) const

Parameters
r in Arbitrary data of arbitrary type as long as it defines operator << for std::ostream.

Print raw data to stream.

template<Style s = VERBOSE>
std::ostream& tk::Print::stream() noexcept

Returns Reference to underlying std::ostream.

Return verbose or quiet stream depending on style template argument. Non-const version.

template<Style s = VERBOSE>
std::ostream& tk::Print::stream() const noexcept

Returns Reference to underlying std::ostream.

Return verbose or quiet stream depending on style template argument. Const version.

template<Style s = VERBOSE>
void tk::Print::headerRNGTest() const

Print RNGTest header. Text ASCII Art Generator used for executable names: http://patorjk.com/software/taag.

template<Style s = VERBOSE>
void tk::Print::headerUnitTest() const

Print UnitTest header. Text ASCII Art Generator used for executable names: http://patorjk.com/software/taag.

template<Style s = VERBOSE>
void tk::Print::headerWalker() const

Print Walker header. Text ASCII Art Generator used for executable names: http://patorjk.com/software/taag.

template<typename T>
const Print& operator<<(const Print& os, const T& t)

Parameters
os in Reference to pretty printer object
t in Reference to an arbitrary object of type T. T must define operator<< for std::ostream-compatible streams.
Returns The internal stream buffer of the stream

Operator << for printing any type to the verbose stream.

template<typename T>
const Print& operator%(const Print& os, const T& t)

Parameters
os in Reference to pretty printer object
t in Reference to an arbitrary object of type T. T must define operator<< for std::ostream-compatible streams.
Returns The internal stream buffer of the stream

Operator % for printing any type to the quiet stream.

const Print& operator%(const Print& os, std::ostream&(*)(std::ostream&) pf)

Parameters
os in Reference to pretty printer object
pf in Function pointer taking a reference to std::ostream and returning a reference to std::ostream
Returns Reference to pretty printer object

Operator % for a function pointer taking ostream returning ostream. This is so that several of operators of % can be chained together.

const Print& operator<<(const Print& os, std::ostream&(*)(std::ostream&) pf)

Parameters
os in Reference to pretty printer object
pf in Function pointer taking a reference to std::ostream and returning a reference to std::ostream
Returns Reference to pretty printer object

Operator << for a function pointer taking ostream returning ostream. This is so that several of operators of << can be chained together.