#include <gromacs/onlinehelp/helpformat.h>

Description

Formats rows of a table for text output.

This utility class formats tabular data, mainly for console output. Each row in the table can take multiple lines, and automatic text wrapping is supported. If text overflows the allocated width, the remaining columns on that line become shifted. To avoid this, it is possible to start the output for different columns from different lines (it is the caller's responsibility to check that overflows are avoided or are acceptable).

Column definitions are first set with addColumn(). To format a row, first call clear(). Then call addColumnLine() to add text to each column (can be called multiple times on a single column to add multiple lines), and possibly setColumnFirstLineOffset() to adjust the line from which the column output should start. Finally, call formatRow() to obtain the formatted row.

A header (column titles and a horizontal line) is printed before the first line.

Typical usage:

  gmx::TextTableFormatter formatter;
  formatter.addColumn("Name", 10, false);
  formatter.addColumn("Type", 10, false);
  formatter.addColumn("Description", 50, true);
  formatter.clear();
  formatter.addColumnLine(0, "name");
  formatter.addColumnLine(1, "type");
  formatter.addColumnLine(2, "Description for name");
  printf("%s", formatter.formatRow().c_str());
  formatter.clear();
  formatter.addColumnLine(0, "averylongname");
  formatter.addColumnLine(1, "type");
  formatter.setColumnFirstLineOffset(1, 1);
  formatter.addColumnLine(2, "Description for name");
  printf("%s", formatter.formatRow().c_str());
  // format other rows by repeating the above code
* 

Methods in this class may throw std::bad_alloc if out of memory. Other exceptions are not thrown.

Classes
class	Impl
	Private implementation class for TextTableFormatter. More...

Public Member Functions
	TextTableFormatter ()
	Constructs an empty formatter.

void	addColumn (const char *title, int width, bool bWrap)
	Adds a column to the table. More...

void	setFirstColumnIndent (int indent)
	Sets amount on indentation before the first column. More...

void	setFoldLastColumnToNextLine (int indent)
	Enables folding the last column to separate lines if it overflows. More...

bool	didOutput () const
	Whether formatRow() has been successfully called. More...

void	clear ()
	Removes all text from all columns and resets the line offsets. More...

void	addColumnLine (int index, const std::string &text)
	Adds text to be printed in a column. More...

void	addColumnHelpTextBlock (int index, const HelpWriterContext &context, const std::string &text)
	Adds text containing help markup to be printed in a column. More...

void	setColumnFirstLineOffset (int index, int firstLine)
	Sets the first line to which text is printed for a column. More...

std::string	formatRow ()
	Formats the lines for the current row. More...

Member Function Documentation

void gmx::TextTableFormatter::addColumn	(	const char *	title,
		int	width,
		bool	bWrap
	)

Adds a column to the table.

Parameters

[in]	title	Title string for the column (used for header).
[in]	width	Width of the column (must be > 0).
[in]	bWrap	Whether text that exceeds `width` is automatically wrapped.

The length of title must not exceed width.

void gmx::TextTableFormatter::addColumnHelpTextBlock	(	int	index,
		const HelpWriterContext &	context,
		const std::string &	text
	)

Adds text containing help markup to be printed in a column.

Parameters

[in]	index	Zero-based column index.
[in]	context	Context to use for markup processing.
[in]	text	Text to add.

Works as addColumnLine(), except that it uses HelpWriterContext::substituteMarkupAndWrapToVector() to process markup in the input text instead of just wrapping it as plain text.

void gmx::TextTableFormatter::addColumnLine	(	int	index,
		const std::string &	text
	)

Adds text to be printed in a column.

Parameters

[in]	index	Zero-based column index.
[in]	text	Text to add.

Can be called multiple times. Additional calls append text as additional lines. Any calls with text empty have no effect. To add an empty line, use "\n" as text.

If text contains newlines, the text is automatically splitted to multiple lines. The same happens if automatic wrapping is on for the column and the text contains lines that are longer than what fits the column.

void gmx::TextTableFormatter::clear ( )

Removes all text from all columns and resets the line offsets.

Removes all text added using addColumnLine() and resets line offsets set with setColumnFirstLineOffset() to zero. Should be called before starting to add data for a row.

Does not throw.

bool gmx::TextTableFormatter::didOutput ( ) const

Whether formatRow() has been successfully called.

This method can be used to determine after-the-fact whether anything was written in the table.

Does not throw.

std::string gmx::TextTableFormatter::formatRow ( )

Formats the lines for the current row.

Returns: Current row formatted as a single string (contains newlines).

Formats the data as set after the previous clear()/formatRow() using addColumnLine() and setColumnFirstLineOffset().

If this is the first line to be formatted, a header is also added to the beginning of the returned string if any column has a title.

The return value always terminates with a newline.

Calls clear() on successful return.

void gmx::TextTableFormatter::setColumnFirstLineOffset	(	int	index,
		int	firstLine
	)

Sets the first line to which text is printed for a column.

Parameters

[in]	index	Zero-based column index.
[in]	firstLine	Zero-based line index from which to start the output.

Can be called if there is no text for column index. Does not affect the output in this case.

Does not throw.

void gmx::TextTableFormatter::setFirstColumnIndent ( int indent )

Sets amount on indentation before the first column.

Parameters

[in] indent Number of spaces to use for indenting.

Does not throw.

void gmx::TextTableFormatter::setFoldLastColumnToNextLine ( int indent )

Enables folding the last column to separate lines if it overflows.

Parameters

[in] indent Number of spaces to use for indenting the lines.

If called with indent >= 0, the last column for each row is treated specially: if it contains more lines than the other columns, and if the text would fit more compactly as separate lines after the row, then the whole last column is written after the row with the given indent. The column text then spans the whole space reserved for the table, making long text fit into a smaller amount of vertical space. If not called, the last column is not treates specially.

Does not throw.

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

src/gromacs/onlinehelp/helpformat.h
src/gromacs/onlinehelp/helpformat.cpp

Description

Classes

Public Member Functions

Member Function Documentation