2 * This file is part of the GROMACS molecular simulation package.
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.
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.
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.
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.
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.
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.
37 * Declares gmx::FileNameOption and gmx::FileNameOptionInfo.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_options
43 #ifndef GMX_OPTIONS_FILENAMEOPTION_H
44 #define GMX_OPTIONS_FILENAMEOPTION_H
49 #include "abstractoption.h"
50 #include "optionfiletype.h"
55 template <typename T> class ConstArrayRef;
56 class FileNameOptionInfo;
57 class FileNameOptionManager;
58 class FileNameOptionStorage;
61 * Specifies an option that provides file names.
63 * Public methods in this class do not throw.
66 * \ingroup module_options
68 class FileNameOption : public OptionTemplate<std::string, FileNameOption>
71 //! OptionInfo subclass corresponding to this option type.
72 typedef FileNameOptionInfo InfoType;
74 //! Initializes an option with the given name.
75 explicit FileNameOption(const char *name)
76 : MyBase(name), optionType_(eftUnknown), legacyType_(-1),
77 defaultBasename_(NULL), defaultType_(-1),
78 bLegacyOptionalBehavior_(false),
79 bRead_(false), bWrite_(false), bLibrary_(false)
84 * Sets the type of the file this option accepts.
86 * Either this attribute or legacyType() must be provided.
88 MyClass &filetype(OptionFileType type)
89 { optionType_ = type; return me(); }
91 * Sets the type of the file from an enum in filenm.h.
93 * New code should prefer filetype(), extending the enumeration if
96 MyClass &legacyType(int type)
97 { legacyType_ = type; return me(); }
99 * Changes the behavior of optional options to match old t_filenm.
101 * If this is not set, optional options return an empty string if not
102 * set. If this is set, a non-empty value is always returned.
103 * In the latter case, whether the option is set only affects the
104 * return value of OptionInfo::isSet() and Options::isSet().
106 MyClass &legacyOptionalBehavior()
107 { bLegacyOptionalBehavior_ = true; return me(); }
108 //! Tells that the file provided by this option is used for input only.
110 { bRead_ = true; bWrite_ = false; return me(); }
111 //! Tells that the file provided by this option is used for output only.
112 MyClass &outputFile()
113 { bRead_ = false; bWrite_ = true; return me(); }
115 * Tells that the file provided by this option is used for input and
118 MyClass &inputOutputFile()
119 { bRead_ = bWrite_ = true; return me(); }
121 * Sets the read/write usage for this file from boolean flags.
123 MyClass &readWriteFlags(bool bRead, bool bWrite)
124 { bRead_ = bRead; bWrite_ = bWrite; return me(); }
126 * Tells that the file will be looked up in library directories in
127 * addition to working directory.
130 * Currently, this flag only affects the help output. Callers must
131 * take care themselves to actually search the file in the library
132 * directories. It would be nicer to do this searching within the
133 * file name option implementation.
135 MyClass &libraryFile(bool bLibrary = true)
136 { bLibrary_ = bLibrary; return me(); }
138 * Sets a default basename for the file option.
140 * Use this method instead of defaultValue() or defaultValueIfSet() to
141 * set a default value for a file name option. No extension needs to
142 * be provided; it is automatically added based on filetype() or
144 * The behavior is also adjusted based on required(): if the option is
145 * required, the value given to defaultBasename() is treated as for
146 * both defaultValue() and defaultValueIfSet(), otherwise it is treated
147 * as for defaultValueIfSet().
149 * For input files that accept multiple extensions, the extension is
150 * completed to the default extension on creation of the option or at
151 * time of parsing an option without a value.
153 * If FileNameOptionManager is used, the extension may change during
154 * Options::finish(), as this is the time when the default names are
155 * checked against the file system to provide an extension that matches
156 * an existing file if that is possible.
158 * If FileNameOptionManager is used, and
159 * FileNameOptionManager::addDefaultFileNameOption() is used, and the
160 * user provides a global default file name using that option, then the
161 * global default takes precedence over defaultBasename().
163 MyClass &defaultBasename(const char *basename)
164 { defaultBasename_ = basename; return me(); }
166 * Sets a default type/extension for the file option.
168 * For options that accept multiple types of files (e.g.,
169 * eftTrajectory), this method sets the default extension used
170 * for completing defaultBasename(), as well as the default extension
171 * used by FileNameOptionManager to complete various file names.
173 * The value should be one of the enumerated `ef*` values from
174 * filenm.h, and be a valid type for the type specified with
177 MyClass &defaultType(int filetype)
178 { defaultType_ = filetype; return me(); }
181 // Use defaultBasename() instead.
182 using MyBase::defaultValue;
183 using MyBase::defaultValueIfSet;
185 //! Creates a FileNameOptionStorage object.
186 virtual AbstractOptionStorage *createStorage(
187 const OptionManagerContainer &managers) const;
189 OptionFileType optionType_;
191 const char *defaultBasename_;
193 bool bLegacyOptionalBehavior_;
199 * Needed to initialize FileNameOptionStorage from this class without
200 * otherwise unnecessary accessors.
202 friend class FileNameOptionStorage;
206 * Wrapper class for accessing file name option information.
209 * \ingroup module_options
211 class FileNameOptionInfo : public OptionInfo
214 //! Shorthand for a list of extensions.
215 typedef std::vector<const char *> ExtensionList;
217 //! Creates an option info object for the given option.
218 explicit FileNameOptionInfo(FileNameOptionStorage *option);
220 //! Whether the option specifies an input file.
221 bool isInputFile() const;
222 //! Whether the option specifies an output file.
223 bool isOutputFile() const;
224 //! Whether the option specifies a file used for both input and output.
225 bool isInputOutputFile() const;
227 * Whether the option specifies a library file.
229 * \see FileNameOption::libraryFile()
231 bool isLibraryFile() const;
233 //! Whether the option specifies directories.
234 bool isDirectoryOption() const;
235 //! Whether the option specifies a generic trajectory file.
236 bool isTrajectoryOption() const;
237 //! Returns the default extension for this option.
238 const char *defaultExtension() const;
239 //! Returns the list of extensions this option accepts.
240 ExtensionList extensions() const;
241 //! Returns whether \p fileType (from filenm.h) is accepted for this option.
242 bool isValidType(int fileType) const;
243 //! Returns the list of file types this option accepts.
244 ConstArrayRef<int> fileTypes() const;
247 const FileNameOptionStorage &option() const;