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  * Make the string uppercase.
  54  *
  55  * \param[in] text  Input text.
  56  * \returns   \p text with all characters transformed to uppercase.
  57  * \throws    std::bad_alloc if out of memory.
  58  *
  59  * \inlibraryapi
  60  */
  61 std::string toUpperCase(const std::string &text);
  62
  63 /*! \libinternal \brief
  64  * Substitute markup used in help text for console output.
  65  *
  66  * \param[in] text  Text to substitute.
  67  * \returns   \p text with markup substituted.
  68  * \throws    std::bad_alloc if out of memory.
  69  *
  70  * \inlibraryapi
  71  */
  72 std::string substituteMarkupForConsole(const std::string &text);
  73 /*! \libinternal \brief
  74  * Format a help text block for console output.
  75  *
  76  * \param     file  File to write the formatted text to.
  77  * \param[in] text  Text to format.
  78  * \throws    std::bad_alloc if out of memory.
  79  * \throws    FileIOError on any I/O error.
  80  *
  81  * Calls substituteMarkupForConsole(), and also wraps the lines to 78
  82  * characters.
  83  *
  84  * \inlibraryapi
  85  */
  86 void writeHelpTextForConsole(File *file, const std::string &text);
  87 //! \endcond
  88
  89 /*! \libinternal \brief
  90  * Formats rows of a table for text output.
  91  *
  92  * This utility class formats tabular data, mainly for console output.
  93  * Each row in the table can take multiple lines, and automatic text wrapping
  94  * is supported.  If text overflows the allocated width, the remaining columns
  95  * on that line become shifted.  To avoid this, it is possible to start the
  96  * output for different columns from different lines (it is the caller's
  97  * responsibility to check that overflows are avoided or are acceptable).
  98  *
  99  * Column definitions are first set with addColumn().
 100  * To format a row, first call clear().  Then call addColumnLine() to add text
 101  * to each column (can be called multiple times on a single column to add
 102  * multiple lines), and possibly setColumnFirstLineOffset() to adjust the line
 103  * from which the column output should start.  Finally, call formatRow() to
 104  * obtain the formatted row.
 105  *
 106  * A header (column titles and a horizontal line) is printed before the first
 107  * line.
 108  *
 109  * Typical usage:
 110  * \code
 111 gmx::TextTableFormatter formatter;
 112 formatter.addColumn("Name", 10, false);
 113 formatter.addColumn("Type", 10, false);
 114 formatter.addColumn("Description", 50, true);
 115
 116 formatter.clear();
 117 formatter.addColumnLine(0, "name");
 118 formatter.addColumnLine(1, "type");
 119 formatter.addColumnLine(2, "Description for name");
 120 printf("%s", formatter.formatRow().c_str());
 121
 122 formatter.clear();
 123 formatter.addColumnLine(0, "averylongname");
 124 formatter.addColumnLine(1, "type");
 125 formatter.setColumnFirstLineOffset(1, 1);
 126 formatter.addColumnLine(2, "Description for name");
 127 printf("%s", formatter.formatRow().c_str());
 128
 129 // format other rows by repeating the above code
 130  * \endcode
 131  *
 132  * Methods in this class may throw std::bad_alloc if out of memory.
 133  * Other exceptions are not thrown.
 134  *
 135  * \inlibraryapi
 136  * \ingroup module_onlinehelp
 137  */
 138 class TextTableFormatter
 139 {
 140     public:
 141         //! Constructs an empty formatter.
 142         TextTableFormatter();
 143         ~TextTableFormatter();
 144
 145         /*! \brief
 146          * Adds a column to the table.
 147          *
 148          * \param[in]  title  Title string for the column (used for header).
 149          * \param[in]  width  Width of the column (must be > 0).
 150          * \param[in]  bWrap  Whether text that exceeds \p width is
 151          *      automatically wrapped.
 152          *
 153          * The length of \p title must not exceed \p width.
 154          */
 155         void addColumn(const char *title, int width, bool bWrap);
 156         /*! \brief
 157          * Sets amount on indentation before the first column.
 158          *
 159          * \param[in]  indent  Number of spaces to use for indenting.
 160          *
 161          * Does not throw.
 162          */
 163         void setFirstColumnIndent(int indent);
 164
 165         /*! \brief
 166          * Whether formatRow() has been successfully called.
 167          *
 168          * This method can be used to determine after-the-fact whether anything
 169          * was written in the table.
 170          *
 171          * Does not throw.
 172          */
 173         bool didOutput() const;
 174
 175         /*! \brief
 176          * Removes all text from all columns and resets the line offsets.
 177          *
 178          * Removes all text added using addColumnLine() and resets line offsets
 179          * set with setColumnFirstLineOffset() to zero.
 180          * Should be called before starting to add data for a row.
 181          *
 182          * Does not throw.
 183          */
 184         void clear();
 185         /*! \brief
 186          * Adds text to be printed in a column.
 187          *
 188          * \param[in]  index     Zero-based column index.
 189          * \param[in]  text      Text to add.
 190          *
 191          * Can be called multiple times.  Additional calls append \p text as
 192          * additional lines.  Any calls with \p text empty have no effect.
 193          * To add an empty line, use "\n" as \p text.
 194          *
 195          * If \p text contains newlines, the text is automatically splitted to
 196          * multiple lines.  The same happens if automatic wrapping is on for
 197          * the column and the text contains lines that are longer than what
 198          * fits the column.
 199          */
 200         void addColumnLine(int index, const std::string &text);
 201         /*! \brief
 202          * Sets the first line to which text is printed for a column.
 203          *
 204          * \param[in]  index     Zero-based column index.
 205          * \param[in]  firstLine Zero-based line index from which to start the
 206          *      output.
 207          *
 208          * Can be called if there is no text for column \p index.
 209          * Does not affect the output in this case.
 210          *
 211          * Does not throw.
 212          */
 213         void setColumnFirstLineOffset(int index, int firstLine);
 214         /*! \brief
 215          * Formats the lines for the current row.
 216          *
 217          * \returns  Current row formatted as a single string
 218          *      (contains newlines).
 219          *
 220          * Formats the data as set after the previous clear()/formatRow() using
 221          * addColumnLine() and setColumnFirstLineOffset().
 222          *
 223          * If this is the first line to be formatted, a header is also added to
 224          * the beginning of the returned string if any column has a title.
 225          *
 226          * The return value always terminates with a newline.
 227          *
 228          * Calls clear() on successful return.
 229          */
 230         std::string formatRow();
 231
 232         /*! \brief
 233          * Returns the last line on which column \p index has text.
 234          *
 235          * \param[in] index  Zero-based column index.
 236          * \returns   Last line index (zero-based) on which \p index has text.
 237          *
 238          * The return value is the sum of the number of lines added with
 239          * addColumnLine() (taking into account possible wrapping) and the line
 240          * offset set with setColumnFirstLineOffset().
 241          *
 242          * Does not throw.
 243          */
 244         int lastColumnLine(int index) const;
 245
 246     private:
 247         class Impl;
 248
 249         PrivateImplPointer<Impl> impl_;
 250 };
 251
 252 } // namespace gmx
 253
 254 #endif