tk::Print class

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 inciter::InciterPrint
InciterPrint : tk::Print.
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(std::ostream& str = std::clog, 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>
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 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, 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 keywords.
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 headerInciter() const
template<Style s = VERBOSE>
void headerRNGTest() const
template<Style s = VERBOSE>
void headerUnitTest() const
template<Style s = VERBOSE>
void headerFileConv() const
template<Style s = VERBOSE>
void headerMeshConv() 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(std::ostream& str = std::clog, std::ostream& qstr = std::cout) explicit

Parameters
str in/out Verbose stream
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 member function can be called by overriding the default stream via the template argument, Style, a C-style enum. Note: By default, str == std::clog. This is used to initialize str to a local stringstream into which all verbose output goes by default, i.e., it will not be shown. This solution is chosen instead of trickery with null-streams, as boost:formatted output into null-streams caused invalid reads in valgrind. This way quiet output (formatted or not) simply goes into a local stringstream. In other words, the default argument to str, std::clog, is only used to detect whether client code passed a default argument or not: if it did not, the string stream is used for verbose output, if it did, the specified stream is used for the verbose output.

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
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
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
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>
void tk::Print::item(const std::string& name, bool b) const

Parameters
name in Item name to be printed
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
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
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
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::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

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<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, 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 keywords.

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
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::headerInciter() const

Print Inciter header. Text ASCII Art Generator used for executable names: http://patorjk.com/software/taag, Picture ASCII Art Generator used for converting the logo text "Quinoa": http://picascii.com.

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, Picture ASCII Art Generator used for converting the logo text "Quinoa": http://picascii.com.

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, Picture ASCII Art Generator used for converting the logo text "Quinoa": http://picascii.com.

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

Print FileConv header. Text ASCII Art Generator used for executable names: http://patorjk.com/software/taag, Picture ASCII Art Generator used for converting the logo text "Quinoa": http://picascii.com.

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

Print MeshConv header. Text ASCII Art Generator used for executable names: http://patorjk.com/software/taag, Picture ASCII Art Generator used for converting the logo text "Quinoa": http://picascii.com.

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, Picture ASCII Art Generator used for converting the logo text "Quinoa": http://picascii.com.

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

Parameters
os in Reference to pretty printer object
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
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.