src/gromacs/options/filenameoption.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014,2015,2017,2018,2019, 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 "gromacs/options/abstractoption.h"
  50 #include "gromacs/options/optionfiletype.h"
  51
  52 namespace gmx
  53 {
  54
  55 template<typename T>
  56 class ArrayRef;
  57 class FileNameOptionInfo;
  58 class FileNameOptionManager;
  59 class FileNameOptionStorage;
  60
  61 /*! \brief
  62  * Specifies an option that provides file names.
  63  *
  64  * Public methods in this class do not throw.
  65  *
  66  * \inpublicapi
  67  * \ingroup module_options
  68  */
  69 class FileNameOption : public OptionTemplate<std::string, FileNameOption>
  70 {
  71 public:
  72     //! OptionInfo subclass corresponding to this option type.
  73     typedef FileNameOptionInfo InfoType;
  74
  75     //! Initializes an option with the given name.
  76     explicit FileNameOption(const char* name) :
  77         MyBase(name),
  78         optionType_(eftUnknown),
  79         legacyType_(-1),
  80         defaultBasename_(nullptr),
  81         defaultType_(-1),
  82         bLegacyOptionalBehavior_(false),
  83         bRead_(false),
  84         bWrite_(false),
  85         bLibrary_(false),
  86         bAllowMissing_(false)
  87     {
  88     }
  89
  90     /*! \brief
  91      * Sets the type of the file this option accepts.
  92      *
  93      * Either this attribute or legacyType() must be provided.
  94      */
  95     MyClass& filetype(OptionFileType type)
  96     {
  97         optionType_ = type;
  98         return me();
  99     }
 100     /*! \brief
 101      * Sets the type of the file from an enum in filetypes.h.
 102      *
 103      * New code should prefer filetype(), extending the enumeration if
 104      * necessary.
 105      */
 106     MyClass& legacyType(int type)
 107     {
 108         legacyType_ = type;
 109         return me();
 110     }
 111     /*! \brief
 112      * Changes the behavior of optional options to match old t_filenm.
 113      *
 114      * If this is not set, optional options return an empty string if not
 115      * set.  If this is set, a non-empty value is always returned.
 116      * In the latter case, whether the option is set only affects the
 117      * return value of OptionInfo::isSet() and Options::isSet().
 118      */
 119     MyClass& legacyOptionalBehavior()
 120     {
 121         bLegacyOptionalBehavior_ = true;
 122         return me();
 123     }
 124     //! Tells that the file provided by this option is used for input only.
 125     MyClass& inputFile()
 126     {
 127         bRead_  = true;
 128         bWrite_ = false;
 129         return me();
 130     }
 131     //! Tells that the file provided by this option is used for output only.
 132     MyClass& outputFile()
 133     {
 134         bRead_  = false;
 135         bWrite_ = true;
 136         return me();
 137     }
 138     /*! \brief
 139      * Tells that the file provided by this option is used for input and
 140      * output both.
 141      */
 142     MyClass& inputOutputFile()
 143     {
 144         bRead_ = bWrite_ = true;
 145         return me();
 146     }
 147     /*! \brief
 148      * Sets the read/write usage for this file from boolean flags.
 149      */
 150     MyClass& readWriteFlags(bool bRead, bool bWrite)
 151     {
 152         bRead_  = bRead;
 153         bWrite_ = bWrite;
 154         return me();
 155     }
 156     /*! \brief
 157      * Tells that the file will be looked up in library directories in
 158      * addition to working directory.
 159      *
 160      * \todo
 161      * Currently, this flag only affects the help output.  Callers must
 162      * take care themselves to actually search the file in the library
 163      * directories.  It would be nicer to do this searching within the
 164      * file name option implementation.
 165      */
 166     MyClass& libraryFile(bool bLibrary = true)
 167     {
 168         bLibrary_ = bLibrary;
 169         return me();
 170     }
 171     /*! \brief
 172      * Tells that missing file names explicitly provided by the user are
 173      * valid for this input option.
 174      *
 175      * If this method is not called, an error will be raised if the user
 176      * explicitly provides a file name that does not name an existing file,
 177      * or if the default value does not resolve to a valid file name for a
 178      * required option that the user has not set.
 179      *
 180      * This method only has effect with input files, and only if a
 181      * FileNameOptionManager is being used.
 182      */
 183     MyClass& allowMissing(bool bAllow = true)
 184     {
 185         bAllowMissing_ = bAllow;
 186         return me();
 187     }
 188     /*! \brief
 189      * Sets a default basename for the file option.
 190      *
 191      * Use this method instead of defaultValue() or defaultValueIfSet() to
 192      * set a default value for a file name option.  No extension needs to
 193      * be provided; it is automatically added based on filetype() or
 194      * defaultType().
 195      * The behavior is also adjusted based on required(): if the option is
 196      * required, the value given to defaultBasename() is treated as for
 197      * both defaultValue() and defaultValueIfSet(), otherwise it is treated
 198      * as for defaultValueIfSet().
 199      *
 200      * For input files that accept multiple extensions, the extension is
 201      * completed to the default extension on creation of the option or at
 202      * time of parsing an option without a value.
 203      *
 204      * If FileNameOptionManager is used, the extension may change during
 205      * Options::finish(), as this is the time when the default names are
 206      * checked against the file system to provide an extension that matches
 207      * an existing file if that is possible.
 208      *
 209      * If FileNameOptionManager is used, and
 210      * FileNameOptionManager::addDefaultFileNameOption() is used, and the
 211      * user provides a global default file name using that option, then the
 212      * global default takes precedence over defaultBasename().
 213      */
 214     MyClass& defaultBasename(const char* basename)
 215     {
 216         defaultBasename_ = basename;
 217         return me();
 218     }
 219     /*! \brief
 220      * Sets a default type/extension for the file option.
 221      *
 222      * For options that accept multiple types of files (e.g.,
 223      * eftTrajectory), this method sets the default extension used
 224      * for completing defaultBasename(), as well as the default extension
 225      * used by FileNameOptionManager to complete various file names.
 226      *
 227      * The value should be one of the enumerated `ef*` values from
 228      * filetypes.h, and be a valid type for the type specified with
 229      * filetype().
 230      */
 231     MyClass& defaultType(int filetype)
 232     {
 233         defaultType_ = filetype;
 234         return me();
 235     }
 236
 237 private:
 238     // Use defaultBasename() instead.
 239     using MyBase::defaultValue;
 240     using MyBase::defaultValueIfSet;
 241
 242     //! Creates a FileNameOptionStorage object.
 243     AbstractOptionStorage* createStorage(const OptionManagerContainer& managers) const override;
 244
 245     OptionFileType optionType_;
 246     int            legacyType_;
 247     const char*    defaultBasename_;
 248     int            defaultType_;
 249     bool           bLegacyOptionalBehavior_;
 250     bool           bRead_;
 251     bool           bWrite_;
 252     bool           bLibrary_;
 253     bool           bAllowMissing_;
 254
 255     /*! \brief
 256      * Needed to initialize FileNameOptionStorage from this class without
 257      * otherwise unnecessary accessors.
 258      */
 259     friend class FileNameOptionStorage;
 260 };
 261
 262 /*! \brief
 263  * Wrapper class for accessing file name option information.
 264  *
 265  * \inpublicapi
 266  * \ingroup module_options
 267  */
 268 class FileNameOptionInfo : public OptionInfo
 269 {
 270 public:
 271     //! Shorthand for a list of extensions.
 272     typedef std::vector<const char*> ExtensionList;
 273
 274     //! Creates an option info object for the given option.
 275     explicit FileNameOptionInfo(FileNameOptionStorage* option);
 276
 277     //! Whether the option specifies an input file.
 278     bool isInputFile() const;
 279     //! Whether the option specifies an output file.
 280     bool isOutputFile() const;
 281     //! Whether the option specifies a file used for both input and output.
 282     bool isInputOutputFile() const;
 283     /*! \brief
 284      * Whether the option specifies a library file.
 285      *
 286      * \see FileNameOption::libraryFile()
 287      */
 288     bool isLibraryFile() const;
 289     //! Whether the (input) option allows missing files to be provided.
 290     bool allowMissing() const;
 291
 292     //! Whether the option specifies directories.
 293     bool isDirectoryOption() const;
 294     //! Whether the option specifies a generic trajectory file.
 295     bool isTrajectoryOption() const;
 296     //! Returns the default extension for this option.
 297     const char* defaultExtension() const;
 298     //! Returns the list of extensions this option accepts.
 299     ExtensionList extensions() const;
 300     //! Returns whether \p fileType (from filetypes.h) is accepted for this option.
 301     bool isValidType(int fileType) const;
 302     //! Returns the list of file types this option accepts.
 303     ArrayRef<const int> fileTypes() const;
 304
 305 private:
 306     const FileNameOptionStorage& option() const;
 307 };
 308
 309 } // namespace gmx
 310
 311 #endif