Gromacs  2016.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions
gmx::HelpWriterContext Class Reference

#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...
 
TextWriteroutputFile () 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_allocif 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_allocif 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]titleTitle for the subsection.
Exceptions
std::bad_allocif out of memory.
FileIOErroron 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]searchText to replace in input.
[in]replaceText that each occurrence of search is replaced with.
Exceptions
std::bad_allocif 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]settingsLine wrapper settings.
[in]textText to substitute.
Returns
text with markup substituted and wrapped.
Exceptions
std::bad_allocif 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]settingsLine wrapper settings.
[in]textText to substitute.
Returns
text with markup substituted and wrapped as a list of lines.
Exceptions
std::bad_allocif 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]nameName of the option.
[in]valuePlaceholder for option value.
[in]defaultValueDefault value for the option.
[in]infoAdditional (brief) info/attributes for the option.
[in]descriptionFull 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]textText to format.
Exceptions
std::bad_allocif out of memory.
FileIOErroron 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]titleTitle to write.
Exceptions
std::bad_allocif out of memory.
FileIOErroron any I/O error.

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