src/gromacs/onlinehelp/helpwritercontext.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 gmx::HelpWriterContext.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inlibraryapi
  37  * \ingroup module_onlinehelp
  38  */
  39 #ifndef GMX_ONLINEHELP_HELPWRITERCONTEXT_H
  40 #define GMX_ONLINEHELP_HELPWRITERCONTEXT_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 Output format for help writing.
  53 enum HelpOutputFormat
  54 {
  55     eHelpOutputFormat_Console,  //!< Plain text directly on the console.
  56     eHelpOutputFormat_NR        //!< Used for the number of output formats.
  57 };
  58 //! \endcond
  59
  60 /*! \libinternal \brief
  61  * Context information for writing out help.
  62  *
  63  * The purpose of this class is to pass information about the output format to
  64  * methods that write help, and to abstract away most of the details of
  65  * different output formats.
  66  * Additionally, it can keep other context information, although it currently
  67  * does not.  Such additional context information would be useful for
  68  * formatting links/references to other help topics.
  69  *
  70  * TODO: This class will need additional work as part of Redmine issue #969.
  71  *
  72  * \inlibraryapi
  73  * \ingroup module_onlinehelp
  74  */
  75 class HelpWriterContext
  76 {
  77     public:
  78         /*! \brief
  79          * Initializes a context with the given output file and format.
  80          *
  81          * \throws std::bad_alloc if out of memory.
  82          */
  83         HelpWriterContext(File *file, HelpOutputFormat format);
  84         ~HelpWriterContext();
  85
  86         /*! \brief
  87          * Returns the active output format.
  88          *
  89          * Does not throw.
  90          */
  91         HelpOutputFormat outputFormat() const;
  92         /*! \brief
  93          * Returns the raw output file for writing the help.
  94          *
  95          * Using this file directly should be avoided, as it requires one to
  96          * have different code for each output format.
  97          * Using other methods in this class should be preferred.
  98          *
  99          * Does not throw.
 100          */
 101         File &outputFile() const;
 102
 103         /*! \brief
 104          * Substitutes markup used in help text.
 105          *
 106          * \param[in] text  Text to substitute.
 107          * \returns   \p text with markup substituted.
 108          * \throws    std::bad_alloc if out of memory.
 109          */
 110         std::string substituteMarkup(const std::string &text) const;
 111         /*! \brief
 112          * Writes a title for the current help topic.
 113          *
 114          * \param[in] title  Title to write.
 115          * \throws    std::bad_alloc if out of memory.
 116          * \throws    FileIOError on any I/O error.
 117          */
 118         void writeTitle(const std::string &title) const;
 119         /*! \brief
 120          * Writes a formatted text block into the output.
 121          *
 122          * \param[in] text  Text to format.
 123          * \throws    std::bad_alloc if out of memory.
 124          * \throws    FileIOError on any I/O error.
 125          *
 126          * In addition to substituteMarkup(), also does line wrapping for
 127          * console output.
 128          *
 129          * TODO: This function and substituteMarkup() should work more
 130          * similarly.
 131          */
 132         void writeTextBlock(const std::string &text) const;
 133
 134     private:
 135         class Impl;
 136
 137         PrivateImplPointer<Impl> impl_;
 138 };
 139
 140 } // namespace gmx
 141
 142 #endif