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