#include <gromacs/onlinehelp/helpwritercontext.h>

Description

Context information for writing out help.

The purpose of this class is to pass information about the output format to methods that write help, and to abstract away most of the details of different output formats.

The state of a context object (excluding the fact that the output file is written to) does not change after initial construction of the object. Copying creates a context objects that share state with the source.

Public Member Functions
	HelpWriterContext (TextWriter *writer, HelpOutputFormat format)
	Initializes a context with the given output writer and format. More...

	HelpWriterContext (TextWriter writer, HelpOutputFormat format, const HelpLinks links)
	Initializes a context with the given output writer, format and links. More...

	HelpWriterContext (const HelpWriterContext &other)
	Creates a copy of the context.

void	setReplacement (const std::string &search, const std::string &replace)
	Adds a string replacement for markup subsitution. More...

HelpOutputFormat	outputFormat () const
	Returns the active output format. More...

TextWriter &	outputFile () const
	Returns the raw writer for writing the help. More...

void	enterSubSection (const std::string &title)
	Creates a subsection in the output help. More...

std::string	substituteMarkupAndWrapToString (const TextLineWrapperSettings &settings, const std::string &text) const
	Substitutes markup used in help text and wraps lines. More...

std::vector< std::string >	substituteMarkupAndWrapToVector (const TextLineWrapperSettings &settings, const std::string &text) const
	Substitutes markup used in help text and wraps lines. More...

void	writeTitle (const std::string &title) const
	Writes a title for the current help topic. More...

void	writeTextBlock (const std::string &text) const
	Writes a formatted text block into the output. More...

void	paragraphBreak () const
	Ensures a paragraph break (empty line) in the output. More...

void	writeOptionListStart () const
	Starts writing a list of options. More...

void	writeOptionItem (const std::string &name, const std::string &value, const std::string &defaultValue, const std::string &info, const std::string &description) const
	Writes an entry for a single option into the output. More...

void	writeOptionListEnd () const
	Finishes writing a list of options. More...

Constructor & Destructor Documentation

gmx::HelpWriterContext::HelpWriterContext	(	TextWriter *	writer,
		HelpOutputFormat	format
	)

Initializes a context with the given output writer and format.

Exceptions

std::bad_alloc if out of memory.

gmx::HelpWriterContext::HelpWriterContext	(	TextWriter *	writer,
		HelpOutputFormat	format,
		const HelpLinks *	links
	)

Initializes a context with the given output writer, format and links.

Exceptions

std::bad_alloc if out of memory.

A reference to links is stored until the HelpWriterContext is destructed. The caller is responsible for ensuring that the links object remains valid long enough.

Member Function Documentation

void gmx::HelpWriterContext::enterSubSection ( const std::string & title )

Creates a subsection in the output help.

Parameters

[in] title Title for the subsection.

Exceptions

std::bad_alloc	if out of memory.
FileIOError	on any I/O error.

Writes title using writeTitle() and makes any further writeTitle() calls write headings one level deeper.

Typical use for writing a subsection is to create a copy of the context for the parent section, and then call enterSubSection() on the copy. The whole subsection should be written out using the returned context before calling any further methods in the parent context.

This method is only necessary if the subsection will contain further subsections. If there is only one level of subsections, it is possible to use writeTitle() directly.

TextWriter & gmx::HelpWriterContext::outputFile ( ) const

Returns the raw writer for writing the help.

Using this writer directly should be avoided, as it requires one to have different code for each output format. Using other methods in this class should be preferred.

Does not throw.

HelpOutputFormat gmx::HelpWriterContext::outputFormat ( ) const

Returns the active output format.

Does not throw.

void gmx::HelpWriterContext::paragraphBreak ( ) const

Ensures a paragraph break (empty line) in the output.

Calls at the beginning and end of output do not produce extra empty lines, and consencutive calls only result in a single empty line. This allows calling the method before and after all output that needs to appear separated as empty lines.

void gmx::HelpWriterContext::setReplacement	(	const std::string &	search,
		const std::string &	replace
	)

Adds a string replacement for markup subsitution.

Parameters

[in]	search	Text to replace in input.
[in]	replace	Text that each occurrence of `search` is replaced with.

Exceptions

std::bad_alloc if out of memory.

Todo:: Improve semantics if the same search item is set multiple times.

std::string gmx::HelpWriterContext::substituteMarkupAndWrapToString	(	const TextLineWrapperSettings &	settings,
		const std::string &	text
	)		const

Substitutes markup used in help text and wraps lines.

Parameters

[in]	settings	Line wrapper settings.
[in]	text	Text to substitute.

Returns: text with markup substituted and wrapped.

Exceptions

std::bad_alloc if out of memory.

See Also: TextLineWrapper::wrapToString()

std::vector< std::string > gmx::HelpWriterContext::substituteMarkupAndWrapToVector	(	const TextLineWrapperSettings &	settings,
		const std::string &	text
	)		const

Substitutes markup used in help text and wraps lines.

Parameters

[in]	settings	Line wrapper settings.
[in]	text	Text to substitute.

Returns: text with markup substituted and wrapped as a list of lines.

Exceptions

std::bad_alloc if out of memory.

See Also: TextLineWrapper::wrapToVector()

void gmx::HelpWriterContext::writeOptionItem	(	const std::string &	name,
		const std::string &	value,
		const std::string &	defaultValue,
		const std::string &	info,
		const std::string &	description
	)		const

Writes an entry for a single option into the output.

Parameters

[in]	name	Name of the option.
[in]	value	Placeholder for option value.
[in]	defaultValue	Default value for the option.
[in]	info	Additional (brief) info/attributes for the option.
[in]	description	Full description of the option.

void gmx::HelpWriterContext::writeOptionListEnd ( ) const

Finishes writing a list of options.

Prints any necessary footers for a list of options formatted with writeOptionItem().

void gmx::HelpWriterContext::writeOptionListStart ( ) const

Starts writing a list of options.

Prints any necessary headers for a list of options formatted with writeOptionItem().

void gmx::HelpWriterContext::writeTextBlock ( const std::string & text ) const

Writes a formatted text block into the output.

Parameters

[in] text Text to format.

Exceptions

std::bad_alloc	if out of memory.
FileIOError	on any I/O error.

Convenience function that calls substituteMarkupAndWrapToString() and writes the result directly to the output file.

void gmx::HelpWriterContext::writeTitle ( const std::string & title ) const

Writes a title for the current help topic.

Parameters

[in] title Title to write.

Exceptions

std::bad_alloc	if out of memory.
FileIOError	on any I/O error.

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

src/gromacs/onlinehelp/helpwritercontext.h
src/gromacs/onlinehelp/helpwritercontext.cpp

Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation