src/gromacs/options/filenameoption.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \file
  36  * \brief
  37  * Declares gmx::FileNameOption and gmx::FileNameOptionInfo.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inpublicapi
  41  * \ingroup module_options
  42  */
  43 #ifndef GMX_OPTIONS_FILENAMEOPTION_H
  44 #define GMX_OPTIONS_FILENAMEOPTION_H
  45
  46 #include <string>
  47 #include <vector>
  48
  49 #include "abstractoption.h"
  50 #include "optionfiletype.h"
  51
  52 namespace gmx
  53 {
  54
  55 template <typename T> class ConstArrayRef;
  56 class FileNameOptionInfo;
  57 class FileNameOptionManager;
  58 class FileNameOptionStorage;
  59
  60 /*! \brief
  61  * Specifies an option that provides file names.
  62  *
  63  * Public methods in this class do not throw.
  64  *
  65  * \inpublicapi
  66  * \ingroup module_options
  67  */
  68 class FileNameOption : public OptionTemplate<std::string, FileNameOption>
  69 {
  70     public:
  71         //! OptionInfo subclass corresponding to this option type.
  72         typedef FileNameOptionInfo InfoType;
  73
  74         //! Initializes an option with the given name.
  75         explicit FileNameOption(const char *name)
  76             : MyBase(name), optionType_(eftUnknown), legacyType_(-1),
  77               defaultBasename_(NULL), bLegacyOptionalBehavior_(false),
  78               bRead_(false), bWrite_(false), bLibrary_(false)
  79         {
  80         }
  81
  82         /*! \brief
  83          * Sets the type of the file this option accepts.
  84          *
  85          * Either this attribute or legacyType() must be provided.
  86          */
  87         MyClass &filetype(OptionFileType type)
  88         { optionType_ = type; return me(); }
  89         /*! \brief
  90          * Sets the type of the file from an enum in filenm.h.
  91          *
  92          * New code should prefer filetype(), extending the enumeration if
  93          * necessary.
  94          */
  95         MyClass &legacyType(int type)
  96         { legacyType_ = type; return me(); }
  97         /*! \brief
  98          * Changes the behavior of optional options to match old t_filenm.
  99          *
 100          * If this is not set, optional options return an empty string if not
 101          * set.  If this is set, a non-empty value is always returned.
 102          * In the latter case, whether the option is set only affects the
 103          * return value of OptionInfo::isSet() and Options::isSet().
 104          */
 105         MyClass &legacyOptionalBehavior()
 106         { bLegacyOptionalBehavior_ = true; return me(); }
 107         //! Tells that the file provided by this option is used for input only.
 108         MyClass &inputFile()
 109         { bRead_ = true; bWrite_ = false; return me(); }
 110         //! Tells that the file provided by this option is used for output only.
 111         MyClass &outputFile()
 112         { bRead_ = false; bWrite_ = true; return me(); }
 113         /*! \brief
 114          * Tells that the file provided by this option is used for input and
 115          * output both.
 116          */
 117         MyClass &inputOutputFile()
 118         { bRead_ = bWrite_ = true; return me(); }
 119         /*! \brief
 120          * Sets the read/write usage for this file from boolean flags.
 121          */
 122         MyClass &readWriteFlags(bool bRead, bool bWrite)
 123         { bRead_ = bRead; bWrite_ = bWrite; return me(); }
 124         /*! \brief
 125          * Tells that the file will be looked up in library directories in
 126          * addition to working directory.
 127          *
 128          * \todo
 129          * Currently, this flag only affects the help output.  Callers must
 130          * take care themselves to actually search the file in the library
 131          * directories.  It would be nicer to do this searching within the
 132          * file name option implementation.
 133          */
 134         MyClass &libraryFile(bool bLibrary = true)
 135         { bLibrary_ = bLibrary; return me(); }
 136         /*! \brief
 137          * Sets a default basename for the file option.
 138          *
 139          * Use this method instead of defaultValue() or defaultValueIfSet() to
 140          * set a default value for a file name option.  No extension needs to
 141          * be provided; it is automatically added based on filetype().
 142          * The behavior is also adjusted based on required(): if the option is
 143          * required, the value given to defaultBasename() is treated as for
 144          * both defaultValue() and defaultValueIfSet(), otherwise it is treated
 145          * as for defaultValueIfSet().
 146          *
 147          * For input files that accept multiple extensions, the extension is
 148          * completed to the default extension on creation of the option or at
 149          * time of parsing an option without a value.
 150          * The extension may change during Options::finish(), as this is the
 151          * time when the default names are checked against the file system to
 152          * provide an extension that matches an existing file if that is
 153          * possible.
 154          *
 155          * If FileNameOptionManager is used, and
 156          * FileNameOptionManager::addDefaultFileNameOption() is used, and the
 157          * user provides a global default file name using that option, then the
 158          * global default takes precedence over defaultBasename().
 159          */
 160         MyClass &defaultBasename(const char *basename)
 161         { defaultBasename_ = basename; return me(); }
 162
 163     private:
 164         // Use defaultBasename() instead.
 165         using MyBase::defaultValue;
 166         using MyBase::defaultValueIfSet;
 167
 168         //! Creates a FileNameOptionStorage object.
 169         virtual AbstractOptionStorage *createStorage(
 170             const OptionManagerContainer &managers) const;
 171
 172         OptionFileType          optionType_;
 173         int                     legacyType_;
 174         const char             *defaultBasename_;
 175         bool                    bLegacyOptionalBehavior_;
 176         bool                    bRead_;
 177         bool                    bWrite_;
 178         bool                    bLibrary_;
 179
 180         /*! \brief
 181          * Needed to initialize FileNameOptionStorage from this class without
 182          * otherwise unnecessary accessors.
 183          */
 184         friend class FileNameOptionStorage;
 185 };
 186
 187 /*! \brief
 188  * Wrapper class for accessing file name option information.
 189  *
 190  * \inpublicapi
 191  * \ingroup module_options
 192  */
 193 class FileNameOptionInfo : public OptionInfo
 194 {
 195     public:
 196         //! Shorthand for a list of extensions.
 197         typedef std::vector<const char *> ExtensionList;
 198
 199         //! Creates an option info object for the given option.
 200         explicit FileNameOptionInfo(FileNameOptionStorage *option);
 201
 202         //! Whether the option specifies an input file.
 203         bool isInputFile() const;
 204         //! Whether the option specifies an output file.
 205         bool isOutputFile() const;
 206         //! Whether the option specifies a file used for both input and output.
 207         bool isInputOutputFile() const;
 208         /*! \brief
 209          * Whether the option specifies a library file.
 210          *
 211          * \see FileNameOption::libraryFile()
 212          */
 213         bool isLibraryFile() const;
 214
 215         //! Whether the option specifies directories.
 216         bool isDirectoryOption() const;
 217         //! Whether the option specifies a generic trajectory file.
 218         bool isTrajectoryOption() const;
 219         //! Returns the default extension for this option.
 220         const char *defaultExtension() const;
 221         //! Returns the list of extensions this option accepts.
 222         ExtensionList extensions() const;
 223         //! Returns whether \p fileType (from filenm.h) is accepted for this option.
 224         bool isValidType(int fileType) const;
 225         //! Returns the list of file types this option accepts.
 226         ConstArrayRef<int> fileTypes() const;
 227
 228     private:
 229         const FileNameOptionStorage &option() const;
 230 };
 231
 232 } // namespace gmx
 233
 234 #endif