1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
7 # http://www.apache.org/licenses/LICENSE-2.0
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 # See the License for the specific language governing permissions and
13 # limitations under the License.
15 # Configuration options for nit tools and apps
17 # This module provides basic services for options handling in your Nit programs.
19 # ## Basic configuration holder
21 # The `Config` class can be used as a simple option holder and processor:
26 # # Create a new config option
27 # var opt_my = new OptionString("My option", "--my")
29 # # Create the config and add the option
30 # var config = new Config
31 # config.add_option(opt_my)
33 # # Parse the program arguments, usually `args`
34 # config.parse_options(["--my", "myOption", "arg1", "arg2"])
36 # # Access the options and args
37 # assert opt_my.value == "myOption"
38 # assert config.args == ["arg1", "arg2"]
41 # ## Custom configuration class
43 # Instead of using basic `Config` instances, it is better to define new sublcasses
44 # to store options and define custom services.
52 # var opt_my = new OptionString("My option", "--my")
56 # tool_description = "Usage: MyExample [OPTION]... [ARGS]..."
60 # fun my: String do return opt_my.value or else "Default value"
63 # var config = new MyConfig
64 # config.parse_options(["--my", "myOption", "arg1", "arg2"])
66 # assert config.my == "myOption"
67 # assert config.args == ["arg1", "arg2"]
70 # We define the `my` method to provide an elegant shortcut to `opt_my.value`
71 # and define the default value if the option was not set by the user.
73 # The `tool_description` attribute is used to set the `usage` header printed when
74 # the user request the `help` message.
77 # config.parse_options(["-h"])
84 # This will display the tool usage like this:
87 # Usage: MyExample [OPTION]... [ARGS]...
88 # -h, --help Show this help message
92 # ## Configuration with `ini` file
94 # The `IniConfig` class extends `Config` to add an easy way to link your
95 # configuration to an ini file.
101 # var opt_my = new OptionString("My option", "--my")
105 # tool_description = "Usage: MyExample [OPTION]... [ARGS]..."
106 # opts.add_option(opt_my)
109 # fun my: String do return opt_my.value or else ini["my"] or else "Default"
113 # This time, we define the `my` method to return the option value or the ini
114 # if no option was passed. Finally, if no ini value can be found, we return the
117 # By default, `IniConfig` looks at a `config.ini` file in the execution directory.
118 # This can be overrided in multiple ways.
120 # First by the app user by setting the `--config` option:
123 # var config = new MyIniConfig
124 # config.parse_options(["--config", "my_config.ini"])
126 # assert config.config_file == "my_config.ini"
129 # Default config file can also be changed by the library client through the
130 # `default_config_file` attribute:
133 # config = new MyIniConfig
134 # config.default_config_file = "my_config.ini"
135 # config.parse_options(["arg"])
137 # assert config.config_file == "my_config.ini"
140 # Or by the library developper in the custom config class:
143 # class MyCustomIniConfig
146 # redef var default_config_file = "my_config.ini"
149 # var config = new MyCustomIniConfig
150 # config.parse_options(["arg"])
152 # assert config.config_file == "my_config.ini"
159 # Basic configuration class
167 # var opt_my = new OptionString("My option", "--my")
171 # tool_description = "Usage: MyExample [OPTION]... [ARGS]..."
172 # opts.add_option(opt_my)
175 # fun my: String do return opt_my.value or else "Default value"
178 # var config = new MyConfig
179 # config.parse_options(["--my", "hello", "arg1", "arg2"])
180 # assert config.my == "hello"
181 # assert config.args == ["arg1", "arg2"]
185 # Context used to store and parse options
186 var opts
= new OptionContext
189 var opt_help
= new OptionBool("Show this help message", "-h", "--help")
191 # Redefine this init to add your options
196 # Add an option to `self`
198 # Shortcut to `opts.add_option`.
199 fun add_option
(opt
: Option...) do opts
.add_option
(opt
...)
201 # Initialize `self` options from `args`
202 fun parse_options
(args
: Collection[String]) do
206 # Return the remaining args once options are parsed by `from_args`
207 fun args
: Array[String] do return opts
.rest
209 # Name, usage and synopsis of the tool.
210 # It is mainly used in `usage`.
211 # Should be correctly set by the client before calling `usage`
212 # A multi-line string is recommended.
214 # eg. `"Usage: tool [OPTION]... [FILE]...\nDo some things."`
215 var tool_description
: String = "Usage: [OPTION]... [ARG]..." is writable
217 # Was the `--help` option requested?
218 fun help
: Bool do return opt_help
.value
220 # Display `tool_description` and options usage in console
222 print tool_description
227 # Configuration class based on a INI file.
233 # var opt_my = new OptionString("My option", "--my")
237 # tool_description = "Usage: MyExample [OPTION]... [ARGS]..."
238 # opts.add_option(opt_my)
241 # fun my: String do return opt_my.value or else ini["my"] or else "Default"
244 # var config = new MyIniConfig
245 # config.default_config_file = "my_config.ini"
246 # config.parse_options(args)
248 # if config.help then
253 # assert config.my == "Default"
258 # Config tree used to store config options
259 var ini
: ConfigTree is noinit
261 # Path to app config file
262 var opt_config
= new OptionString("Path to config file", "--config")
266 opts
.add_option
(opt_config
)
269 redef fun parse_options
(args
) do
271 ini
= new ConfigTree(config_file
)
274 # Default config file path
275 var default_config_file
= "config.ini" is writable
277 # Return the config file path from options or the default
278 fun config_file
: String do return opt_config
.value
or else default_config_file