IMP logo
IMP Reference Guide  develop.63b38c487d,2024/12/21
The Integrative Modeling Platform
version 20241221.develop.63b38c487d
flags.h
Go to the documentation of this file.
1 /**
2  * \file IMP/flags.h
3  * \brief Support for shared command line flags.
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPKERNEL_FLAGS_H
10 #define IMPKERNEL_FLAGS_H
11 
12 #include <IMP/kernel_config.h>
13 #include <boost/cstdint.hpp>
14 #include "types.h"
15 #include <string>
16 
17 IMPKERNEL_BEGIN_NAMESPACE
18 /** \name Flags
19 
20  These methods add support for shared command
21  line flags to \imp. Programs that use this have access to flags
22  declared in modules which allow users to do things like control
23  log level and turn on and off profiling to see what is going on.
24  These functions are Python accessible.
25 
26  In C++, you can also use the AddFloatFlag, AddStringFlag,
27  AddBoolFlag and AddIntFlag classes to add flags statically. @{
28 */
29 //! Return the name of the current executable.
30 IMPKERNELEXPORT std::string get_executable_name();
31 
32 #ifndef SWIG
33 //! Parse the command line flags and return the positional arguments.
34 /**
35  \param[in] argc argc
36  \param[in] argv argv
37  \param[in] description A message describing what the program does.
38  \throws UsageException if a problem with the command line was found.
39  */
40 IMPKERNELEXPORT void setup_from_argv(int argc, char **argv,
41  std::string description);
42 
43 /** Parse the command line flags and return the
44  positional arguments returning unknown flags in a list. Use this version
45  if some arguments are to be parsed by a different system.
46 
47  \param[in] argc argc
48  \param[in] argv argv
49  \param[in] description A message describing what the program does.
50  \throws UsageException if a problem with the command line was found.
51  */
52 IMPKERNELEXPORT Strings setup_from_argv_allowing_unknown(int argc, char **argv,
53  std::string description);
54 
55 /** Parse the command line flags and return the
56  positional arguments.
57 
58  \param[in] argc argc
59  \param[in] argv argv
60  \param[in] description A message describing what the program does.
61  \param[in] positional_description A message describing the the
62  positional arguments
63  \param[in] num_positional A positive integer to require that
64  many positional arguments, or a negative integer to require at
65  least that many.
66  \throws UsageException if a problem with the command line was found.
67  */
68 IMPKERNELEXPORT Strings
69  setup_from_argv(int argc, char **argv, std::string description,
70  std::string positional_description, int num_positional);
71 #endif
72 
73 /** Parse the command line flags and return the
74  positional arguments. For Python.
75 
76  \param[in] argv sys.argv
77  \param[in] description A message describing what the program does.
78  \throws UsageException if a problem with the command line was found.
79  */
80 IMPKERNELEXPORT void setup_from_argv(const Strings &argv,
81  std::string description);
82 
83 /** Parse the command line flags and return the
84  positional arguments. For Python.
85 
86  \param[in] argv sys.argv
87  \param[in] description A message describing what the program does.
88  \param[in] positional_description A message describing the positional
89  arguments, eg "input.pdb output.pdb"
90  \param[in] num_positional A positive integer to require that
91  many positional arguments, or a negative integer to require at
92  least that many.
93  \throws UsageException if a problem with the command line was found.
94  */
95 IMPKERNELEXPORT Strings
96  setup_from_argv(const Strings &argv, std::string description,
97  std::string positional_description, int num_positional);
98 
99 #ifndef SWIG
100 /** Define one of these in C++ to add a new int flag storing
101  into the passed variable.
102 
103  \note You should consider using Flag<std::string> instead.
104 */
105 struct IMPKERNELEXPORT AddStringFlag {
106  AddStringFlag(std::string name, std::string description,
107  std::string *storage);
108 };
109 #endif
110 
111 /** For Python use.*/
112 IMPKERNELEXPORT void add_string_flag(std::string name, std::string default_value,
113  std::string description);
114 /** For Python use.*/
115 IMPKERNELEXPORT std::string get_string_flag(std::string name);
116 
117 #ifndef SWIG
118 /** Define one of these in C++ to add a new boost::int64_t flag storing
119  into the passed variable.
120 
121  \note You should consider using Flag<boost::int64_t> instead.
122 */
123 struct IMPKERNELEXPORT AddIntFlag {
124  AddIntFlag(std::string name, std::string description,
125  boost::int64_t *storage);
126 };
127 #endif
128 
129 /** For Python use.*/
130 IMPKERNELEXPORT void add_int_flag(std::string name, size_t default_value,
131  std::string description);
132 /** For Python use.*/
133 IMPKERNELEXPORT size_t get_int_flag(std::string name);
134 
135 #ifndef SWIG
136 /** Define one of these in C++ to add a new bool flag storing
137  into the passed variable.
138 
139  \note You should consider using Flag<bool> instead.
140 */
141 struct IMPKERNELEXPORT AddBoolFlag {
142  AddBoolFlag(std::string name, std::string description, bool *storage);
143 };
144 #endif
145 
146 /** For Python use. Default is always false.*/
147 IMPKERNELEXPORT void add_bool_flag(std::string name, std::string description);
148 /** For Python use.*/
149 IMPKERNELEXPORT bool get_bool_flag(std::string name);
150 
151 #ifndef SWIG
152 /** Define one of these in C++ to add a new float flag storing
153  into the passed variable.
154 
155  \note You should consider using Flag<double> instead.
156 */
157 struct IMPKERNELEXPORT AddFloatFlag {
158  AddFloatFlag(std::string name, std::string description, double *storage);
159 };
160 #endif
161 
162 /** For Python use.*/
163 IMPKERNELEXPORT void add_float_flag(std::string name, double default_value,
164  std::string description);
165 /** For Python use.*/
166 IMPKERNELEXPORT double get_float_flag(std::string name);
167 /** @} */
168 
169 /** Prints out the help message, useful if you have extra error checking
170  and the flags don't pass it.*/
171 IMPKERNELEXPORT void write_help(std::ostream &out = std::cerr);
172 
173 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
174 /* Exposing global variables through swig is kind of broken,
175  see issue #723. */
176 extern IMPKERNELEXPORT AdvancedFlag<bool> run_quick_test;
177 #endif
178 // defined in static.cpp
179 
180 /** Executables can inspect this flag and when it is true, run a shorter,
181  simpler version of their code to just make sure things work.
182 */
183 inline bool get_is_quick_test() { return run_quick_test; }
184 
185 IMPKERNEL_END_NAMESPACE
186 
187 #endif /* IMPKERNEL_FLAGS_H */
IMP::add_int_flag
void add_int_flag(std::string name, size_t default_value, std::string description)
types.h
Basic types used by IMP.
IMP::get_is_quick_test
bool get_is_quick_test()
Definition: flags.h:183
IMP::setup_from_argv
Strings setup_from_argv(const Strings &argv, std::string description, std::string positional_description, int num_positional)
IMP::Strings
IMP::Vector< String > Strings
Standard way to pass a bunch of String values.
Definition: types.h:50
IMP::get_bool_flag
bool get_bool_flag(std::string name)
IMP::setup_from_argv_allowing_unknown
Strings setup_from_argv_allowing_unknown(int argc, char **argv, std::string description)
IMP::add_string_flag
void add_string_flag(std::string name, std::string default_value, std::string description)
IMP::write_help
void write_help(std::ostream &out=std::cerr)
IMP::get_int_flag
size_t get_int_flag(std::string name)
IMP::add_float_flag
void add_float_flag(std::string name, double default_value, std::string description)
IMP::get_executable_name
std::string get_executable_name()
Return the name of the current executable.
IMP::AdvancedFlag
Use this to add an advanced flag to the program.
Definition: Flag.h:53
IMP::get_string_flag
std::string get_string_flag(std::string name)
IMP::add_bool_flag
void add_bool_flag(std::string name, std::string description)
IMP::get_float_flag
double get_float_flag(std::string name)