/src/wrappers/glib/library/utilities/g_option_context.e
Specman e | 393 lines | 117 code | 76 blank | 200 comment | 5 complexity | 2215e0522a396cee54d608aff2e1e541 MD5 | raw file
1indexing 2 description: "." 3 copyright: "[ 4 Copyright (C) 2007 Paolo Redaelli, Glib developers 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Lesser General Public License 8 as published by the Free Software Foundation; either version 2.1 of 9 the License, or (at your option) any later version. 10 11 This library is distributed in the hopeOA that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Lesser General Public License for more details. 15 16 You should have received a copy of the GNU Lesser General Public 17 License along with this library; if not, write to the Free Software 18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA 20 ]" 21 22class G_OPTION_CONTEXT 23 -- A commandline option parser. 24 25 -- The GOption commandline parser is intended to be a simpler 26 -- replacement for the popt library. It supports short and long 27 -- commandline options, as shown in the following example: 28 29 -- testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- 30 -- file1 file2 31 32 -- The example demonstrates a number of features of the GOption 33 -- commandline parser 34 35 -- o Options can be single letters, prefixed by a single 36 -- dash. Multiple short options can be grouped behind a single 37 -- dash. 38 39 -- o Long options are prefixed by two consecutive dashes. 40 41 -- o Options can have an extra argument, which can be a number, a 42 -- string or a filename. For long options, the extra argument can 43 -- be appended with an equals sign after the option name. 44 45 -- o Non-option arguments are returned to the application as rest 46 -- arguments. 47 48 -- o An argument consisting solely of two dashes turns off further 49 -- parsing, any remaining arguments (even those starting with a 50 -- dash) are returned to the application as rest arguments. 51 52 -- Another important feature of GOption is that it can 53 -- automatically generate nicely formatted help output. Unless it 54 -- is explicitly turned off with `set_help_enabled', GOption will 55 -- recognize the "--help", "-?", "--help-all" and 56 -- "--help-groupname" options (where groupname is the name of a 57 -- G_OPTION_GROUP) and write a text similar to the one shown in the 58 -- following example to stdout. 59 60 -- Usage: 61 -- testtreemodel [OPTION...] - test tree model performance 62 63 -- Help Options: 64 -- -?, --help Show help options 65 -- --help-all Show all help options 66 -- --help-gtk Show GTK+ Options 67 68 -- Application Options: 69 -- -r, --repeats=N Average over N repetitions 70 -- -m, --max-size=M Test up to 2^M items 71 -- --display=DISPLAY X display to use 72 -- -v, --verbose Be verbose 73 -- -b, --beep Beep when done 74 -- --rand Randomize the data 75 76 -- GOption groups options in G_OPTION_GROUPs, which makes it easy to 77 -- incorporate options from multiple sources. The intended use for 78 -- this is to let applications collect option groups from the 79 -- libraries it uses, add them to their G_OPTION_CONTEXT, and parse 80 -- all options by a single call to `parse'. GTK provides its own 81 -- group in GTK.option_group. 82 83 -- If an option is declared to be of type string or filename, 84 -- GOption takes care of converting it to the right encoding; 85 -- strings are returned in UTF-8, filenames are returned in the 86 -- GLib filename encoding. 87 88 -- "commandline_parser_example" is a complete example of setting up 89 -- GOption to parse the example commandline above and produce the 90 -- example help output. 91 92inherit 93 C_STRUCT redefine free end 94 EIFFEL_OWNED redefine free end 95 96insert 97 SHARED_G_ERROR 98 ARGUMENTS undefine is_equal, copy end 99 GOPTION_CONTEXT_STRUCT 100 GOPTION_EXTERNALS 101 102creation with,make, from_external_pointer 103 104feature {} -- Creation 105 with, make (a_parameter: ABSTRACT_STRING) is 106 -- Creates a new option context. 107 108 -- The parameter_string can serve multiple purposes. It can be used to 109 -- add descriptions for "rest" arguments, which are not parsed by the 110 -- GOptionContext, typically something like "FILES" or "FILE1 111 -- FILE2...". If you are using G_OPTION_REMAINING for collecting "rest" 112 -- arguments, GLib handles this automatically by using the 113 -- arg_description of the corresponding GOptionEntry in the usage 114 -- summary. 115 116 -- Another usage is to give a short summary of the program 117 -- functionality, like " - frob the strings", which will be displayed 118 -- in the same line as the usage. For a longer description of the 119 -- program functionality that should be displayed as a paragraph below 120 -- the usage line, use g_option_context_set_summary(). 121 122 -- Note that the parameter_string is translated (see 123 -- g_option_context_set_translate_func()). 124 125 -- `a_parameter' : a string which is displayed in the first line of 126 -- --help output, after the usage summary programname [OPTION...] 127 require parameter_not_void: a_parameter/=Void 128 do 129 from_external_pointer(g_option_context_new(a_parameter.to_external)) 130 end 131 132feature 133 set_summary (a_summary: ABSTRACT_STRING) is 134 -- Adds a string to be displayed in --help output before the list of 135 -- options. This is typically a summary of the program functionality. 136 137 -- Note that the summary is translated (see `set_translate_func'). 138 139 -- `a_summary': a string to be shown in --help output before the list 140 -- of options, or Void 141 local sp: POINTER 142 do 143 if a_summary/=Void then sp:=a_summary.to_external end 144 g_option_context_set_summary(handle,sp) 145 end 146 147 summary: FIXED_STRING is 148 local sp: POINTER 149 do 150 sp:=g_option_context_get_summary(handle) 151 if sp.is_not_null then create Result.from_external(sp) end 152 end 153 154 set_description (a_description: ABSTRACT_STRING) is 155 -- Adds `a_description' string to be displayed in --help output after 156 -- the list of options. This text often includes a bug reporting 157 -- address. 158 159 -- Note that the summary is translated (see set_translator). 160 161 -- `a_description' may be Void to unset. 162 do 163 g_option_context_set_description(handle,null_or_string(a_description)) 164 ensure set: description.is_equal(a_description) 165 end 166 167 description: FIXED_STRING is 168 -- The description set with `set_description'. May be Void 169 local p: POINTER 170 do 171 p:=g_option_context_get_description(handle) 172 if p.is_not_null 173 then create Result.from_external(p) 174 end 175 end 176 177 -- GTranslateFunc () 178 179 -- const gchar* (*GTranslateFunc) (const gchar *str, 180 -- gpointer data); 181 182 -- The type of functions which are used to translate user-visible strings, for 183 -- --help output. 184 185 -- str : the untranslated string 186 -- data : user data specified when installing the function, e.g. in 187 -- g_option_group_set_translate_func() 188 -- Returns : a translation of the string for the current locale. The returned string 189 -- is owned by GLib and must not be freed. 190 191 -- --------------------------------------------------------------------------------- 192 193 -- TODO: set_translator wrapping 194 -- g_option_context_set_translate_func () 195 196 -- void g_option_context_set_translate_func 197 -- (GOptionContext *context, 198 -- GTranslateFunc func, 199 -- gpointer data, 200 -- GDestroyNotify destroy_notify); 201 202 -- Sets the function which is used to translate the contexts user-visible strings, 203 -- for --help output. If func is NULL, strings are not translated. 204 205 -- Note that option groups have their own translation functions, this function only 206 -- affects the parameter_string (see g_option_context_nex()), the summary (see 207 -- g_option_context_set_summary()) and the description (see 208 -- g_option_context_set_description()). 209 210 -- If you are using gettext(), you only need to set the translation domain, see 211 -- g_context_group_set_translation_domain(). 212 213 -- context : a GOptionContext 214 -- func : the GTranslateFunc, or NULL 215 -- data : user data to pass to func, or NULL 216 -- destroy_notify : a function which gets called to free data, or NULL 217 218 -- Since 2.12 219 220 -- --------------------------------------------------------------------------------- 221 222 -- g_option_context_set_translation_domain () 223 224 -- void g_option_context_set_translation_domain 225 -- (GOptionContext *context, 226 -- const gchar *domain); 227 228 -- A convenience function to use gettext() for translating user-visible strings. 229 230 -- context : a GOptionContext 231 -- domain : the domain to use 232 233 -- Since 2.12 234 235 parse is 236 -- Parses the command line arguments, recognizing options 237 -- which have been added to context. This feature also invoke 238 -- `g_set_prgname'. 239 240 -- If the parsing is successful, any parsed arguments are 241 -- removed from the array and argc and argv are updated 242 -- accordingly. A '--' option is stripped from argv unless 243 -- there are unparsed options before and after it, or some of 244 -- the options after it start with '-'. In case of an error, 245 -- argc and argv are left unmodified. 246 247 -- If automatic --help support is enabled (see 248 -- `set_help_enabled'), and the argv array contains one of 249 -- the recognized help options, this function will produce 250 -- help output to stdout and call exit (0). 251 252 -- `is_successful' is set to True if the parsing was successful, FALSE 253 -- if an error occurred 254 local i, argc: INTEGER; -- arguments: FAST_ARRAY[STRING]; 255 argv: POINTER 256 do 257 -- context : a GOptionContext 258 -- argc : a pointer to the number of command line arguments. 259 -- argv : a pointer to the array of command line arguments. 260 -- error : a return location for errors 261 262 -- Note: the next two assignments are necessary to generate 263 -- correct C code because command_arguments.to_external is 264 -- actually implemented as a function therefore it cannot be 265 -- used as an argument of address_of. AFAIK there is no way 266 -- to add a precondition to address_or requiring that its 267 -- argument is not the result of a function. Paolo 2007-04-23 268 269 argc := se_argc 270 argv := command_arguments.to_external 271 is_successful := (g_option_context_parse 272 (handle, $argc, -- i.e.: gint *argc, 273 $argv, -- i.e.: -- gchar ***argv 274 error.handle)).to_boolean 275 -- Commandline arguments have been changed. We must 276 -- rebuild `command_arguments' array. 277 278 -- from i:=argc; command_arguments.clear_count; until i = 0 279 -- loop i := i - 1 command_arguments.force(arguments.item(i), 280 -- i) end 281 ensure arguments_can_be_decreased: command_arguments.count <= old command_arguments.count 282 end 283 284 set_help_enabled (a_setting: BOOLEAN) is 285 -- Enables or disables automatic generation of --help output. By 286 -- default, `parse' recognizes "--help", "-?", "--help-all" and 287 -- "--help-groupname" and creates suitable output to stdout. 288 do 289 g_option_context_set_help_enabled(handle,a_setting.to_integer) 290 ensure set: a_setting = is_help_enabled 291 end 292 293 is_help_enabled: BOOLEAN is 294 -- Is automatic "--help" generation turned on? 295 do 296 Result:=g_option_context_get_help_enabled(handle).to_boolean 297 end 298 299 300 set_ignore_unknown_options (a_setting: BOOLEAN) is 301 -- Sets whether to ignore unknown options or not. If an 302 -- argument is ignored, it is left in the `command_arguments' 303 -- array after parsing. By default, `parse' treats unknown 304 -- options as error. 305 306 -- This setting does not affect non-option arguments 307 -- (i.e. arguments which don't start with a dash). But note 308 -- that GOption cannot reliably determine whether a 309 -- non-option belongs to a preceding unknown option. 310 311 -- `a_setting' : TRUE to ignore unknown options, FALSE to 312 -- produce an error when unknown options are met 313 do 314 g_option_context_set_ignore_unknown_options(handle, a_setting.to_integer) 315 end 316 317 are_unknown_options_ignored: BOOLEAN is 318 -- Are unknown options ignored? 319 do 320 Result:=g_option_context_get_ignore_unknown_options(handle).to_boolean 321 end 322 323feature -- group options 324 add_main_entries (some_entries: COLLECTION[G_OPTION_ENTRY]; 325 a_translaction_domain: STRING) is 326 -- A convenience feature which creates a main group if it doesn't 327 -- exist, adds the entries to it and sets the translation domain. 328 329 -- `a_translation_domain': a translation domain to use for translating 330 -- the --help output for the options in entries with gettext(), or 331 -- Void. 332 333 -- Performance: the wrapper is O(1) if some_entries is a 334 -- NULL_TERMINATED_C_ARRAY, otherwise it has an 335 -- O(some_entries.count) overhead, since it converts the 336 -- collection into a NULL_TERMINATED_C_ARRAY 337 require entries_not_void: some_entries /= Void 338 local entries_array: NULL_TERMINATED_C_ARRAY[G_OPTION_ENTRY] 339 do 340 not_yet_implemented 341 -- debug print ("G_OPTION_CONTEXT.add_main_entries%N") end 342 -- if entries_array ?:= some_entries then 343 -- entries_array ::= some_entries 344 -- else create entries_array.from_collection(some_entries) 345 -- end 346 -- debug print (" entries array created:%N") end 347 --debug entries_array.print_on(std_output) std_output.put_new_line end 348 --g_option_context_add_main_entries 349 --(handle, entries_array.storage.to_external, 350 -- null_or_string(a_translaction_domain)) 351 end 352 353 main_group: G_OPTION_GROUP is 354 -- the main group of context, or Void if context doesn't have a main 355 -- group. 356 local p: POINTER 357 do 358 create Result.from_external_pointer(g_option_context_get_main_group(handle)) 359 -- Note that group belongs to context and should not be modified 360 -- or freed. 361 end 362 363 add_group (a_group: G_OPTION_GROUP) is 364 -- Adds a GOptionGroup to the context, so that parsing with context 365 -- will recognize the options in the group. 366 require group_not_void: a_group /= Void 367 do 368 g_option_context_add_group (handle,a_group.handle) 369 -- Note that the added group will be freed together with the context 370 -- when g_option_context_free() is called, so you must not free the 371 -- group yourself after adding it to a context. 372 373 --a_group.set_shared -- avoid freeing the underlying C structure. 374 end 375 376 set_main_group (a_group: G_OPTION_GROUP) is 377 -- Sets a GOptionGroup as main group of the context. This has the same 378 -- effect as calling `add_group', the only difference is that the 379 -- options in the main group are treated differently when generating 380 -- "--help" output. 381 require group_not_void: a_group /= Void 382 do 383 g_option_context_set_main_group (handle, a_group.handle) 384 -- a_group.set_shared -- avoid freeing the underlying C structure. 385 end 386 387feature {} 388 free (a_ptr: POINTER) is 389 do 390 g_option_context_free(a_ptr) 391 end 392 393end -- class G_OPTION_CONTEXT