PageRenderTime 12ms CodeModel.GetById 2ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/glib/library/utilities/g_option_context.e

http://github.com/tybor/Liberty
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