Turi Create  4.0
option_manager.hpp
1 /* Copyright © 2017 Apple Inc. All rights reserved.
2  *
3  * Use of this source code is governed by a BSD-3-clause license that can
4  * be found in the LICENSE.txt file or at https://opensource.org/licenses/BSD-3-Clause
5  */
6 #ifndef TURI_OPTION_MANAGER_H_
7 #define TURI_OPTION_MANAGER_H_
8 
9 #include <string>
10 #include <vector>
11 #include <map>
12 
13 #include <model_server/lib/extensions/option_info.hpp>
14 
15 namespace turi {
16 
17 class flexible_type;
18 
19 /**
20  * \ingroup toolkit_util
21  * A general purpose option manager class. Functions like a
22  * std::map<std::string, flexible_type>, but permits type checking,
23  * description querying, bounds checking, checked categorical values,
24  * etc.
25  */
27  public:
28 
29  /// Convenience overload for create_option.
30  void create_real_option(const std::string& name,
31  const std::string& description,
32  flexible_type default_value,
33  double lower_bound,
34  double upper_bound,
35  bool allowed_overwrite = false);
36 
37  /// Convenience overload for create_option.
38  void create_integer_option(const std::string& name,
39  const std::string& description,
40  flexible_type default_value,
41  flex_int lower_bound,
42  flex_int upper_bound,
43  bool allowed_overwrite = false);
44 
45  /// Convenience overload for create_option.
46  void create_categorical_option(const std::string& name,
47  const std::string& description,
48  const flexible_type& default_value,
49  const std::vector<flexible_type>& allowed_possible_values,
50  bool allowed_overwrite = false);
51 
52  /// Convenience overload for create_option.
53  void create_string_option(const std::string& name,
54  const std::string& description,
55  const flexible_type& default_value,
56  bool allowed_overwrite = false);
57 
58  /// Convenience overload for create_option.
59  void create_boolean_option(const std::string& name,
60  const std::string& description,
61  bool default_value,
62  bool allowed_overwrite = false);
63 
64  /// Convenience overload for create_option.
65  // \warning: This is meant as a last resort if you cannot use any of the above
66  // options. It does not do any clever error checking.
67  void create_flexible_type_option(const std::string& name,
68  const std::string& description,
69  const flexible_type& default_value,
70  bool allowed_overwrite = false);
71 
72  /** Create an option as dictated by option_handling::option_info.
73  *
74  * By default, if an option of the same name exists as the one
75  * being created, an error is raised (cause it's probably a
76  * programmer typo). If allowed_overwrite is true, than the
77  * option is overwritten. The use case of this is when one module
78  * wraps another and has to change some of its options / defaults.
79  */
80  void create_option(const option_handling::option_info&, bool allowed_overwrite = false);
81 
82  /** Set one of the options. This values is checked against the
83  * requirements given by the option instance.
84  */
85  void set_option(const std::string& name, const flexible_type& value);
86 
87  /** Sets the options. These values are checked against the values
88  * in the option reference.
89  */
90  void set_options(const std::map<std::string, flexible_type>& options);
91 
92  /** Delete one of the options. This removes the option from
93  * options_reference_lookup_map and _current_option_values,
94  * but does not remove it from the vector options_reference.
95  * Useful for loading from older model versions with obsolete option names.
96  */
97  void delete_option(const std::string& name);
98 
99  /** Delete a set of options. This removes the options from
100  * options_reference_lookup_map and _current_option_values,
101  * but does not remove them from the vector options_reference.
102  * Useful for loading from older model versions with obsolete option names.
103  */
104  void delete_options(const std::vector<std::string>& names);
105 
106  /** Update the name of an option. Useful for loading from older model versions.
107  * If an option exists with old_name, create a new option with new_name,
108  * copy over values from the old_name, then remove the old option.
109  */
110  void update_option_name(const std::string& old_name, const std::string& new_name);
111 
112  /** Update the name of a set of options.
113  * Useful for loading from older model versions.
114  * If an option exists with old_name, create a new option with new_name,
115  * copy over values from the old_name, then remove the old option.
116  */
117  void update_option_names(const std::map<std::string, std::string>& name_map);
118 
119  /// Returns the option information struct for each of the set
120  /// parameters.
121  const std::vector<option_handling::option_info>& get_option_info() const;
122 
123  /// Returns a map of strings to flexible_type that give the values
124  /// of all the current option values.
125  const std::map<std::string, flexible_type>& current_option_values() const;
126 
127  /** Creates and returns a map of the default options, as specified
128  * by the model.
129  */
130  std::map<std::string, flexible_type> get_default_options() const;
131 
132  /// Returns the value of the option
133  const flexible_type& value(const std::string& name) const;
134 
135  /// Returns the description of the option name.
136  const std::string& description(const std::string& name) const;
137 
138  /// Returns true if an option exists and false otherwise
139  bool is_option(const std::string& name) const;
140 
141  /// Serialization -- save
142  void save(turi::oarchive& oarc) const;
143 
144  /// Serialization -- load
145  void load(turi::iarchive& iarc);
146 
147  private:
148 
149  // A stored cache of the algorithm option information
150  std::map<std::string, size_t> options_reference_lookup_map;
151 
152  std::vector<option_handling::option_info> options_reference;
153 
154  std::map<std::string, flexible_type> _current_option_values;
155 
156 };
157 
158 }
159 
160 #endif /* TURI_OPTION_MANAGER_H_ */
std::map< std::string, flexible_type > get_default_options() const
void create_integer_option(const std::string &name, const std::string &description, flexible_type default_value, flex_int lower_bound, flex_int upper_bound, bool allowed_overwrite=false)
Convenience overload for create_option.
bool is_option(const std::string &name) const
Returns true if an option exists and false otherwise.
The serialization input archive object which, provided with a reference to an istream, will read from the istream, providing deserialization capabilities.
Definition: iarchive.hpp:60
void update_option_names(const std::map< std::string, std::string > &name_map)
void create_option(const option_handling::option_info &, bool allowed_overwrite=false)
const std::map< std::string, flexible_type > & current_option_values() const
void save(turi::oarchive &oarc) const
Serialization – save.
void create_boolean_option(const std::string &name, const std::string &description, bool default_value, bool allowed_overwrite=false)
Convenience overload for create_option.
void delete_option(const std::string &name)
const flexible_type & value(const std::string &name) const
Returns the value of the option.
void create_categorical_option(const std::string &name, const std::string &description, const flexible_type &default_value, const std::vector< flexible_type > &allowed_possible_values, bool allowed_overwrite=false)
Convenience overload for create_option.
void load(turi::iarchive &iarc)
Serialization – load.
void delete_options(const std::vector< std::string > &names)
void set_option(const std::string &name, const flexible_type &value)
void set_options(const std::map< std::string, flexible_type > &options)
The serialization output archive object which, provided with a reference to an ostream, will write to the ostream, providing serialization capabilities.
Definition: oarchive.hpp:80
const std::vector< option_handling::option_info > & get_option_info() const
const std::string & description(const std::string &name) const
Returns the description of the option name.
void update_option_name(const std::string &old_name, const std::string &new_name)
void create_string_option(const std::string &name, const std::string &description, const flexible_type &default_value, bool allowed_overwrite=false)
Convenience overload for create_option.
void create_real_option(const std::string &name, const std::string &description, flexible_type default_value, double lower_bound, double upper_bound, bool allowed_overwrite=false)
Convenience overload for create_option.
void create_flexible_type_option(const std::string &name, const std::string &description, const flexible_type &default_value, bool allowed_overwrite=false)
Convenience overload for create_option.