src/gromacs/onlinehelp/helpformat.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \libinternal \file
  32  * \brief
  33  * Declares common string formatting routines for online help.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inlibraryapi
  37  * \ingroup module_utility
  38  */
  39 #ifndef GMX_ONLINEHELP_HELPFORMAT_H
  40 #define GMX_ONLINEHELP_HELPFORMAT_H
  41
  42 #include <string>
  43
  44 #include "../utility/common.h"
  45
  46 namespace gmx
  47 {
  48
  49 class File;
  50
  51 /*! \cond libapi */
  52 /*! \libinternal \brief
  53  * Substitute markup used in help text for console output.
  54  *
  55  * \param[in] text  Text to substitute.
  56  * \returns   \p text with markup substituted.
  57  * \throws    std::bad_alloc if out of memory.
  58  *
  59  * \inlibraryapi
  60  */
  61 std::string substituteMarkupForConsole(const std::string &text);
  62 /*! \libinternal \brief
  63  * Format a help text block for console output.
  64  *
  65  * \param     file  File to write the formatted text to.
  66  * \param[in] text  Text to format.
  67  * \throws    std::bad_alloc if out of memory.
  68  * \throws    FileIOError on any I/O error.
  69  *
  70  * Calls substituteMarkupForConsole(), and also wraps the lines to 78
  71  * characters.
  72  *
  73  * \inlibraryapi
  74  */
  75 void writeHelpTextForConsole(File *file, const std::string &text);
  76 //! \endcond
  77
  78 /*! \libinternal \brief
  79  * Formats rows of a table for text output.
  80  *
  81  * This utility class formats tabular data, mainly for console output.
  82  * Each row in the table can take multiple lines, and automatic text wrapping
  83  * is supported.  If text overflows the allocated width, the remaining columns
  84  * on that line become shifted.  To avoid this, it is possible to start the
  85  * output for different columns from different lines (it is the caller's
  86  * responsibility to check that overflows are avoided or are acceptable).
  87  *
  88  * Column definitions are first set with addColumn().
  89  * To format a fow, first call clear().  Then call addColumnLine() to add text
  90  * to each column (can be called multiple times on a single column to add
  91  * multiple lines), and possibly setColumnFirstLineOffset() to adjust the line
  92  * from which the column output should start.  Finally, call formatRow() to
  93  * obtain the formatted row.
  94  *
  95  * A header (column titles and a horizontal line) is printed before the first
  96  * line.
  97  *
  98  * Typical usage:
  99  * \code
 100 gmx::TextTableFormatter formatter;
 101 formatter.addColumn("Name", 10, false);
 102 formatter.addColumn("Type", 10, false);
 103 formatter.addColumn("Description", 50, true);
 104
 105 formatter.clear();
 106 formatter.addColumnLine(0, "name");
 107 formatter.addColumnLine(1, "type");
 108 formatter.addColumnLine(2, "Description for name");
 109 printf("%s", formatter.formatRow().c_str());
 110
 111 formatter.clear();
 112 formatter.addColumnLine(0, "averylongname");
 113 formatter.addColumnLine(1, "type");
 114 formatter.setColumnFirstLineOffset(1, 1);
 115 formatter.addColumnLine(2, "Description for name");
 116 printf("%s", formatter.formatRow().c_str());
 117
 118 // format other rows by repeating the above code
 119  * \endcode
 120  *
 121  * Methods in this class may throw std::bad_alloc if out of memory.
 122  * Other exceptions are not thrown.
 123  *
 124  * \inlibraryapi
 125  * \ingroup module_onlinehelp
 126  */
 127 class TextTableFormatter
 128 {
 129     public:
 130         //! Constructs an empty formatter.
 131         TextTableFormatter();
 132         ~TextTableFormatter();
 133
 134         /*! \brief
 135          * Adds a column to the table.
 136          *
 137          * \param[in]  title  Title string for the column (used for header).
 138          * \param[in]  width  Width of the column (must be > 0).
 139          * \param[in]  bWrap  Whether text that exceeds \p width is
 140          *      automatically wrapped.
 141          *
 142          * The length of \p title must not exceed \p width.
 143          */
 144         void addColumn(const char *title, int width, bool bWrap);
 145
 146         /*! \brief
 147          * Whether formatRow() has been successfully called.
 148          *
 149          * This method can be used to determine after-the-fact whether anything
 150          * was written in the table.
 151          *
 152          * Does not throw.
 153          */
 154         bool didOutput() const;
 155
 156         /*! \brief
 157          * Removes all text from all columns and resets the line offsets.
 158          *
 159          * Removes all text added using addColumnLine() and resets line offsets
 160          * set with setColumnFirstLineOffset() to zero.
 161          * Should be called before starting to add data for a row.
 162          *
 163          * Does not throw.
 164          */
 165         void clear();
 166         /*! \brief
 167          * Adds text to be printed in a column.
 168          *
 169          * \param[in]  index     Zero-based column index.
 170          * \param[in]  text      Text to add.
 171          *
 172          * Can be called multiple times.  Additional calls append \p text as
 173          * additional lines.  Any calls with \p text empty have no effect.
 174          * To add an empty line, use "\n" as \p text.
 175          *
 176          * If \p text contains newlines, the text is automatically splitted to
 177          * multiple lines.  The same happens if automatic wrapping is on for
 178          * the column and the text contains lines that are longer than what
 179          * fits the column.
 180          */
 181         void addColumnLine(int index, const std::string &text);
 182         /*! \brief
 183          * Sets the first line to which text is printed for a column.
 184          *
 185          * \param[in]  index     Zero-based column index.
 186          * \param[in]  firstLine Zero-based line index from which to start the
 187          *      output.
 188          *
 189          * Can be called if there is no text for column \p index.
 190          * Does not affect the output in this case.
 191          *
 192          * Does not throw.
 193          */
 194         void setColumnFirstLineOffset(int index, int firstLine);
 195         /*! \brief
 196          * Formats the lines for the current row.
 197          *
 198          * \returns  Current row formatted as a single string
 199          *      (contains newlines).
 200          *
 201          * Formats the data as set after the previous clear()/formatRow() using
 202          * addColumnLine() and setColumnFirstLineOffset().
 203          *
 204          * If this is the first line to be formatted, a header is also added to
 205          * the beginning of the returned string.
 206          *
 207          * The return value always terminates with a newline.
 208          *
 209          * Calls clear() on successful return.
 210          */
 211         std::string formatRow();
 212
 213         /*! \brief
 214          * Returns the last line on which column \p index has text.
 215          *
 216          * \param[in] index  Zero-based column index.
 217          * \returns   Last line index (zero-based) on which \p index has text.
 218          *
 219          * The return value is the sum of the number of lines added with
 220          * addColumnLine() (taking into account possible wrapping) and the line
 221          * offset set with setColumnFirstLineOffset().
 222          *
 223          * Does not throw.
 224          */
 225         int lastColumnLine(int index) const;
 226
 227     private:
 228         class Impl;
 229
 230         PrivateImplPointer<Impl> impl_;
 231 };
 232
 233 } // namespace gmx
 234
 235 #endif