1 /* goption.c - Option parser
3 * Copyright (C) 1999, 2003 Red Hat Software
4 * Copyright (C) 2004 Anders Carlsson <andersca@gnome.org>
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
36 #define TRANSLATE(group, str) (((group)->translate_func ? (* (group)->translate_func) ((str), (group)->translate_data) : (str)))
38 #define NO_ARG(entry) ((entry)->arg == G_OPTION_ARG_NONE || \
39 ((entry)->arg == G_OPTION_ARG_CALLBACK && \
40 ((entry)->flags & G_OPTION_FLAG_NO_ARG)))
42 #define OPTIONAL_ARG(entry) ((entry)->arg == G_OPTION_ARG_CALLBACK && \
43 (entry)->flags & G_OPTION_FLAG_OPTIONAL_ARG)
75 struct _GOptionContext
79 gchar
*parameter_string
;
83 GTranslateFunc translate_func
;
84 GDestroyNotify translate_notify
;
85 gpointer translate_data
;
87 guint help_enabled
: 1;
88 guint ignore_unknown
: 1;
90 GOptionGroup
*main_group
;
92 /* We keep a list of change so we can revert them */
95 /* We also keep track of all argv elements
96 * that should be NULLed or modified.
105 gchar
*help_description
;
107 GDestroyNotify destroy_notify
;
110 GTranslateFunc translate_func
;
111 GDestroyNotify translate_notify
;
112 gpointer translate_data
;
114 GOptionEntry
*entries
;
117 GOptionParseFunc pre_parse_func
;
118 GOptionParseFunc post_parse_func
;
119 GOptionErrorFunc error_func
;
122 static void free_changes_list (GOptionContext
*context
,
124 static void free_pending_nulls (GOptionContext
*context
,
125 gboolean perform_nulls
);
129 _g_unichar_get_width (gunichar c
)
131 if (G_UNLIKELY (g_unichar_iszerowidth (c
)))
134 /* we ignore the fact that we should call g_unichar_iswide_cjk() under
135 * some locales (legacy East Asian ones) */
136 if (g_unichar_iswide (c
))
143 _g_utf8_strwidth (const gchar
*p
,
147 const gchar
*start
= p
;
148 g_return_val_if_fail (p
!= NULL
|| max
== 0, 0);
154 len
+= _g_unichar_get_width (g_utf8_get_char (p
));
155 p
= g_utf8_next_char (p
);
163 /* this case may not be quite correct */
165 len
+= _g_unichar_get_width (g_utf8_get_char (p
));
166 p
= g_utf8_next_char (p
);
168 while (p
- start
< max
&& *p
)
170 len
+= _g_unichar_get_width (g_utf8_get_char (p
));
171 p
= g_utf8_next_char (p
);
180 g_option_error_quark (void)
182 return g_quark_from_static_string ("g-option-context-error-quark");
186 * g_option_context_new:
187 * @parameter_string: a string which is displayed in
188 * the first line of <option>--help</option> output, after the
190 * <literal><replaceable>programname</replaceable> [OPTION...]</literal>
192 * Creates a new option context.
194 * The @parameter_string can serve multiple purposes. It can be used
195 * to add descriptions for "rest" arguments, which are not parsed by
196 * the #GOptionContext, typically something like "FILES" or
197 * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for
198 * collecting "rest" arguments, GLib handles this automatically by
199 * using the @arg_description of the corresponding #GOptionEntry in
202 * Another usage is to give a short summary of the program
203 * functionality, like " - frob the strings", which will be displayed
204 * in the same line as the usage. For a longer description of the
205 * program functionality that should be displayed as a paragraph
206 * below the usage line, use g_option_context_set_summary().
208 * Note that the @parameter_string is translated using the
209 * function set with g_option_context_set_translate_func(), so
210 * it should normally be passed untranslated.
212 * Returns: a newly created #GOptionContext, which must be
213 * freed with g_option_context_free() after use.
218 g_option_context_new (const gchar
*parameter_string
)
221 GOptionContext
*context
;
223 context
= g_new0 (GOptionContext
, 1);
225 context
->parameter_string
= g_strdup (parameter_string
);
226 context
->help_enabled
= TRUE
;
227 context
->ignore_unknown
= FALSE
;
233 * g_option_context_free:
234 * @context: a #GOptionContext
236 * Frees context and all the groups which have been
241 void g_option_context_free (GOptionContext
*context
)
243 g_return_if_fail (context
!= NULL
);
245 g_list_foreach (context
->groups
, (GFunc
)g_option_group_free
, NULL
);
246 g_list_free (context
->groups
);
248 if (context
->main_group
)
249 g_option_group_free (context
->main_group
);
251 free_changes_list (context
, FALSE
);
252 free_pending_nulls (context
, FALSE
);
254 g_free (context
->parameter_string
);
255 g_free (context
->summary
);
256 g_free (context
->description
);
258 if (context
->translate_notify
)
259 (* context
->translate_notify
) (context
->translate_data
);
266 * g_option_context_set_help_enabled:
267 * @context: a #GOptionContext
268 * @help_enabled: %TRUE to enable <option>--help</option>, %FALSE to disable it
270 * Enables or disables automatic generation of <option>--help</option>
271 * output. By default, g_option_context_parse() recognizes
272 * <option>--help</option>, <option>-?</option>, <option>--help-all</option>
273 * and <option>--help-</option><replaceable>groupname</replaceable> and creates
274 * suitable output to stdout.
278 void g_option_context_set_help_enabled (GOptionContext
*context
,
279 gboolean help_enabled
)
282 g_return_if_fail (context
!= NULL
);
284 context
->help_enabled
= help_enabled
;
288 * g_option_context_get_help_enabled:
289 * @context: a #GOptionContext
291 * Returns whether automatic <option>--help</option> generation
292 * is turned on for @context. See g_option_context_set_help_enabled().
294 * Returns: %TRUE if automatic help generation is turned on.
299 g_option_context_get_help_enabled (GOptionContext
*context
)
301 g_return_val_if_fail (context
!= NULL
, FALSE
);
303 return context
->help_enabled
;
307 * g_option_context_set_ignore_unknown_options:
308 * @context: a #GOptionContext
309 * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce
310 * an error when unknown options are met
312 * Sets whether to ignore unknown options or not. If an argument is
313 * ignored, it is left in the @argv array after parsing. By default,
314 * g_option_context_parse() treats unknown options as error.
316 * This setting does not affect non-option arguments (i.e. arguments
317 * which don't start with a dash). But note that GOption cannot reliably
318 * determine whether a non-option belongs to a preceding unknown option.
323 g_option_context_set_ignore_unknown_options (GOptionContext
*context
,
324 gboolean ignore_unknown
)
326 g_return_if_fail (context
!= NULL
);
328 context
->ignore_unknown
= ignore_unknown
;
332 * g_option_context_get_ignore_unknown_options:
333 * @context: a #GOptionContext
335 * Returns whether unknown options are ignored or not. See
336 * g_option_context_set_ignore_unknown_options().
338 * Returns: %TRUE if unknown options are ignored.
343 g_option_context_get_ignore_unknown_options (GOptionContext
*context
)
345 g_return_val_if_fail (context
!= NULL
, FALSE
);
347 return context
->ignore_unknown
;
351 * g_option_context_add_group:
352 * @context: a #GOptionContext
353 * @group: the group to add
355 * Adds a #GOptionGroup to the @context, so that parsing with @context
356 * will recognize the options in the group. Note that the group will
357 * be freed together with the context when g_option_context_free() is
358 * called, so you must not free the group yourself after adding it
364 g_option_context_add_group (GOptionContext
*context
,
369 g_return_if_fail (context
!= NULL
);
370 g_return_if_fail (group
!= NULL
);
371 g_return_if_fail (group
->name
!= NULL
);
372 g_return_if_fail (group
->description
!= NULL
);
373 g_return_if_fail (group
->help_description
!= NULL
);
375 for (list
= context
->groups
; list
; list
= list
->next
)
377 GOptionGroup
*g
= (GOptionGroup
*)list
->data
;
379 if ((group
->name
== NULL
&& g
->name
== NULL
) ||
380 (group
->name
&& g
->name
&& strcmp (group
->name
, g
->name
) == 0))
381 g_warning ("A group named \"%s\" is already part of this GOptionContext",
385 context
->groups
= g_list_append (context
->groups
, group
);
389 * g_option_context_set_main_group:
390 * @context: a #GOptionContext
391 * @group: the group to set as main group
393 * Sets a #GOptionGroup as main group of the @context.
394 * This has the same effect as calling g_option_context_add_group(),
395 * the only difference is that the options in the main group are
396 * treated differently when generating <option>--help</option> output.
401 g_option_context_set_main_group (GOptionContext
*context
,
404 g_return_if_fail (context
!= NULL
);
405 g_return_if_fail (group
!= NULL
);
407 if (context
->main_group
)
409 g_warning ("This GOptionContext already has a main group");
414 context
->main_group
= group
;
418 * g_option_context_get_main_group:
419 * @context: a #GOptionContext
421 * Returns a pointer to the main group of @context.
423 * Return value: the main group of @context, or %NULL if @context doesn't
424 * have a main group. Note that group belongs to @context and should
425 * not be modified or freed.
430 g_option_context_get_main_group (GOptionContext
*context
)
432 g_return_val_if_fail (context
!= NULL
, NULL
);
434 return context
->main_group
;
438 * g_option_context_add_main_entries:
439 * @context: a #GOptionContext
440 * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
441 * @translation_domain: a translation domain to use for translating
442 * the <option>--help</option> output for the options in @entries
443 * with gettext(), or %NULL
445 * A convenience function which creates a main group if it doesn't
446 * exist, adds the @entries to it and sets the translation domain.
451 g_option_context_add_main_entries (GOptionContext
*context
,
452 const GOptionEntry
*entries
,
453 const gchar
*translation_domain
)
455 g_return_if_fail (entries
!= NULL
);
457 if (!context
->main_group
)
458 context
->main_group
= g_option_group_new (NULL
, NULL
, NULL
, NULL
, NULL
);
460 g_option_group_add_entries (context
->main_group
, entries
);
461 g_option_group_set_translation_domain (context
->main_group
, translation_domain
);
465 calculate_max_length (GOptionGroup
*group
)
468 gint i
, len
, max_length
;
472 for (i
= 0; i
< group
->n_entries
; i
++)
474 entry
= &group
->entries
[i
];
476 if (entry
->flags
& G_OPTION_FLAG_HIDDEN
)
479 len
= _g_utf8_strwidth (entry
->long_name
, -1);
481 if (entry
->short_name
)
484 if (!NO_ARG (entry
) && entry
->arg_description
)
485 len
+= 1 + _g_utf8_strwidth (TRANSLATE (group
, entry
->arg_description
), -1);
487 max_length
= MAX (max_length
, len
);
494 print_entry (GOptionGroup
*group
,
496 const GOptionEntry
*entry
,
501 if (entry
->flags
& G_OPTION_FLAG_HIDDEN
)
504 if (entry
->long_name
[0] == 0)
507 str
= g_string_new (NULL
);
509 if (entry
->short_name
)
510 g_string_append_printf (str
, " -%c, --%s", entry
->short_name
, entry
->long_name
);
512 g_string_append_printf (str
, " --%s", entry
->long_name
);
514 if (entry
->arg_description
)
515 g_string_append_printf (str
, "=%s", TRANSLATE (group
, entry
->arg_description
));
517 g_string_append_printf (string
, "%s%*s %s\n", str
->str
,
518 (int) (max_length
+ 4 - _g_utf8_strwidth (str
->str
, -1)), "",
519 entry
->description
? TRANSLATE (group
, entry
->description
) : "");
520 g_string_free (str
, TRUE
);
524 group_has_visible_entries (GOptionContext
*context
,
526 gboolean main_entries
)
528 GOptionFlags reject_filter
= G_OPTION_FLAG_HIDDEN
;
531 gboolean main_group
= group
== context
->main_group
;
534 reject_filter
|= G_OPTION_FLAG_IN_MAIN
;
536 for (i
= 0, l
= (group
? group
->n_entries
: 0); i
< l
; i
++)
538 entry
= &group
->entries
[i
];
540 if (main_entries
&& !main_group
&& !(entry
->flags
& G_OPTION_FLAG_IN_MAIN
))
542 if (!(entry
->flags
& reject_filter
))
550 group_list_has_visible_entires (GOptionContext
*context
,
552 gboolean main_entries
)
556 if (group_has_visible_entries (context
, group_list
->data
, main_entries
))
559 group_list
= group_list
->next
;
566 * g_option_context_get_help:
567 * @context: a #GOptionContext
568 * @main_help: if %TRUE, only include the main group
569 * @group: the #GOptionGroup to create help for, or %NULL
571 * Returns a formatted, translated help text for the given context.
572 * To obtain the text produced by <option>--help</option>, call
573 * <literal>g_option_context_get_help (context, TRUE, NULL)</literal>.
574 * To obtain the text produced by <option>--help-all</option>, call
575 * <literal>g_option_context_get_help (context, FALSE, NULL)</literal>.
576 * To obtain the help text for an option group, call
577 * <literal>g_option_context_get_help (context, FALSE, group)</literal>.
579 * Returns: A newly allocated string containing the help text
584 g_option_context_get_help (GOptionContext
*context
,
589 gint max_length
, len
;
592 GHashTable
*shadow_map
;
594 const gchar
*rest_description
;
597 string
= g_string_sized_new (1024);
599 rest_description
= NULL
;
600 if (context
->main_group
)
603 for (i
= 0; i
< context
->main_group
->n_entries
; i
++)
605 entry
= &context
->main_group
->entries
[i
];
606 if (entry
->long_name
[0] == 0)
608 rest_description
= TRANSLATE (context
->main_group
, entry
->arg_description
);
614 g_string_append_printf (string
, "%s\n %s %s",
615 _("Usage:"), g_get_prgname(), _("[OPTION...]"));
617 if (rest_description
)
619 g_string_append (string
, " ");
620 g_string_append (string
, rest_description
);
623 if (context
->parameter_string
)
625 g_string_append (string
, " ");
626 g_string_append (string
, TRANSLATE (context
, context
->parameter_string
));
629 g_string_append (string
, "\n\n");
631 if (context
->summary
)
633 g_string_append (string
, TRANSLATE (context
, context
->summary
));
634 g_string_append (string
, "\n\n");
637 memset (seen
, 0, sizeof (gboolean
) * 256);
638 shadow_map
= g_hash_table_new (g_str_hash
, g_str_equal
);
640 if (context
->main_group
)
642 for (i
= 0; i
< context
->main_group
->n_entries
; i
++)
644 entry
= &context
->main_group
->entries
[i
];
645 g_hash_table_insert (shadow_map
,
646 (gpointer
)entry
->long_name
,
649 if (seen
[(guchar
)entry
->short_name
])
650 entry
->short_name
= 0;
652 seen
[(guchar
)entry
->short_name
] = TRUE
;
656 list
= context
->groups
;
659 GOptionGroup
*group
= list
->data
;
660 for (i
= 0; i
< group
->n_entries
; i
++)
662 entry
= &group
->entries
[i
];
663 if (g_hash_table_lookup (shadow_map
, entry
->long_name
) &&
664 !(entry
->flags
& G_OPTION_FLAG_NOALIAS
))
665 entry
->long_name
= g_strdup_printf ("%s-%s", group
->name
, entry
->long_name
);
667 g_hash_table_insert (shadow_map
, (gpointer
)entry
->long_name
, entry
);
669 if (seen
[(guchar
)entry
->short_name
] &&
670 !(entry
->flags
& G_OPTION_FLAG_NOALIAS
))
671 entry
->short_name
= 0;
673 seen
[(guchar
)entry
->short_name
] = TRUE
;
678 g_hash_table_destroy (shadow_map
);
680 list
= context
->groups
;
682 max_length
= _g_utf8_strwidth ("-?, --help", -1);
686 len
= _g_utf8_strwidth ("--help-all", -1);
687 max_length
= MAX (max_length
, len
);
690 if (context
->main_group
)
692 len
= calculate_max_length (context
->main_group
);
693 max_length
= MAX (max_length
, len
);
698 GOptionGroup
*group
= list
->data
;
700 /* First, we check the --help-<groupname> options */
701 len
= _g_utf8_strwidth ("--help-", -1) + _g_utf8_strwidth (group
->name
, -1);
702 max_length
= MAX (max_length
, len
);
704 /* Then we go through the entries */
705 len
= calculate_max_length (group
);
706 max_length
= MAX (max_length
, len
);
711 /* Add a bit of padding */
716 list
= context
->groups
;
718 g_string_append_printf (string
, "%s\n -%c, --%-*s %s\n",
719 _("Help Options:"), '?', max_length
- 4, "help",
720 _("Show help options"));
722 /* We only want --help-all when there are groups */
724 g_string_append_printf (string
, " --%-*s %s\n",
725 max_length
, "help-all",
726 _("Show all help options"));
730 GOptionGroup
*group
= list
->data
;
732 if (group_has_visible_entries (context
, group
, FALSE
))
733 g_string_append_printf (string
, " --help-%-*s %s\n",
734 max_length
- 5, group
->name
,
735 TRANSLATE (group
, group
->help_description
));
740 g_string_append (string
, "\n");
745 /* Print a certain group */
747 if (group_has_visible_entries (context
, group
, FALSE
))
749 g_string_append (string
, TRANSLATE (group
, group
->description
));
750 g_string_append (string
, "\n");
751 for (i
= 0; i
< group
->n_entries
; i
++)
752 print_entry (group
, max_length
, &group
->entries
[i
], string
);
753 g_string_append (string
, "\n");
758 /* Print all groups */
760 list
= context
->groups
;
764 GOptionGroup
*group
= list
->data
;
766 if (group_has_visible_entries (context
, group
, FALSE
))
768 g_string_append (string
, group
->description
);
769 g_string_append (string
, "\n");
770 for (i
= 0; i
< group
->n_entries
; i
++)
771 if (!(group
->entries
[i
].flags
& G_OPTION_FLAG_IN_MAIN
))
772 print_entry (group
, max_length
, &group
->entries
[i
], string
);
774 g_string_append (string
, "\n");
781 /* Print application options if --help or --help-all has been specified */
782 if ((main_help
|| !group
) &&
783 (group_has_visible_entries (context
, context
->main_group
, TRUE
) ||
784 group_list_has_visible_entires (context
, context
->groups
, TRUE
)))
786 list
= context
->groups
;
788 g_string_append (string
, _("Application Options:"));
789 g_string_append (string
, "\n");
790 if (context
->main_group
)
791 for (i
= 0; i
< context
->main_group
->n_entries
; i
++)
792 print_entry (context
->main_group
, max_length
,
793 &context
->main_group
->entries
[i
], string
);
797 GOptionGroup
*group
= list
->data
;
799 /* Print main entries from other groups */
800 for (i
= 0; i
< group
->n_entries
; i
++)
801 if (group
->entries
[i
].flags
& G_OPTION_FLAG_IN_MAIN
)
802 print_entry (group
, max_length
, &group
->entries
[i
], string
);
807 g_string_append (string
, "\n");
810 if (context
->description
)
812 g_string_append (string
, TRANSLATE (context
, context
->description
));
813 g_string_append (string
, "\n");
816 return g_string_free (string
, FALSE
);
820 print_help (GOptionContext
*context
,
826 help
= g_option_context_get_help (context
, main_help
, group
);
827 g_print ("%s", help
);
834 parse_int (const gchar
*arg_name
,
843 tmp
= strtol (arg
, &end
, 0);
845 if (*arg
== '\0' || *end
!= '\0')
848 G_OPTION_ERROR
, G_OPTION_ERROR_BAD_VALUE
,
849 _("Cannot parse integer value '%s' for %s"),
855 if (*result
!= tmp
|| errno
== ERANGE
)
858 G_OPTION_ERROR
, G_OPTION_ERROR_BAD_VALUE
,
859 _("Integer value '%s' for %s out of range"),
869 parse_double (const gchar
*arg_name
,
878 tmp
= g_strtod (arg
, &end
);
880 if (*arg
== '\0' || *end
!= '\0')
883 G_OPTION_ERROR
, G_OPTION_ERROR_BAD_VALUE
,
884 _("Cannot parse double value '%s' for %s"),
891 G_OPTION_ERROR
, G_OPTION_ERROR_BAD_VALUE
,
892 _("Double value '%s' for %s out of range"),
904 parse_int64 (const gchar
*arg_name
,
913 tmp
= g_ascii_strtoll (arg
, &end
, 0);
915 if (*arg
== '\0' || *end
!= '\0')
918 G_OPTION_ERROR
, G_OPTION_ERROR_BAD_VALUE
,
919 _("Cannot parse integer value '%s' for %s"),
926 G_OPTION_ERROR
, G_OPTION_ERROR_BAD_VALUE
,
927 _("Integer value '%s' for %s out of range"),
939 get_change (GOptionContext
*context
,
944 Change
*change
= NULL
;
946 for (list
= context
->changes
; list
!= NULL
; list
= list
->next
)
950 if (change
->arg_data
== arg_data
)
954 change
= g_new0 (Change
, 1);
955 change
->arg_type
= arg_type
;
956 change
->arg_data
= arg_data
;
958 context
->changes
= g_list_prepend (context
->changes
, change
);
966 add_pending_null (GOptionContext
*context
,
972 n
= g_new0 (PendingNull
, 1);
976 context
->pending_nulls
= g_list_prepend (context
->pending_nulls
, n
);
980 parse_arg (GOptionContext
*context
,
984 const gchar
*option_name
,
990 g_assert (value
|| OPTIONAL_ARG (entry
) || NO_ARG (entry
));
994 case G_OPTION_ARG_NONE
:
996 change
= get_change (context
, G_OPTION_ARG_NONE
,
999 *(gboolean
*)entry
->arg_data
= !(entry
->flags
& G_OPTION_FLAG_REVERSE
);
1002 case G_OPTION_ARG_STRING
:
1006 data
= g_locale_to_utf8 (value
, -1, NULL
, NULL
, error
);
1011 change
= get_change (context
, G_OPTION_ARG_STRING
,
1013 g_free (change
->allocated
.str
);
1015 change
->prev
.str
= *(gchar
**)entry
->arg_data
;
1016 change
->allocated
.str
= data
;
1018 *(gchar
**)entry
->arg_data
= data
;
1021 case G_OPTION_ARG_STRING_ARRAY
:
1025 data
= g_locale_to_utf8 (value
, -1, NULL
, NULL
, error
);
1030 change
= get_change (context
, G_OPTION_ARG_STRING_ARRAY
,
1033 if (change
->allocated
.array
.len
== 0)
1035 change
->prev
.array
= *(gchar
***)entry
->arg_data
;
1036 change
->allocated
.array
.data
= g_new (gchar
*, 2);
1039 change
->allocated
.array
.data
=
1040 g_renew (gchar
*, change
->allocated
.array
.data
,
1041 change
->allocated
.array
.len
+ 2);
1043 change
->allocated
.array
.data
[change
->allocated
.array
.len
] = data
;
1044 change
->allocated
.array
.data
[change
->allocated
.array
.len
+ 1] = NULL
;
1046 change
->allocated
.array
.len
++;
1048 *(gchar
***)entry
->arg_data
= change
->allocated
.array
.data
;
1053 case G_OPTION_ARG_FILENAME
:
1058 data
= g_locale_to_utf8 (value
, -1, NULL
, NULL
, error
);
1063 data
= g_strdup (value
);
1065 change
= get_change (context
, G_OPTION_ARG_FILENAME
,
1067 g_free (change
->allocated
.str
);
1069 change
->prev
.str
= *(gchar
**)entry
->arg_data
;
1070 change
->allocated
.str
= data
;
1072 *(gchar
**)entry
->arg_data
= data
;
1076 case G_OPTION_ARG_FILENAME_ARRAY
:
1081 data
= g_locale_to_utf8 (value
, -1, NULL
, NULL
, error
);
1086 data
= g_strdup (value
);
1088 change
= get_change (context
, G_OPTION_ARG_STRING_ARRAY
,
1091 if (change
->allocated
.array
.len
== 0)
1093 change
->prev
.array
= *(gchar
***)entry
->arg_data
;
1094 change
->allocated
.array
.data
= g_new (gchar
*, 2);
1097 change
->allocated
.array
.data
=
1098 g_renew (gchar
*, change
->allocated
.array
.data
,
1099 change
->allocated
.array
.len
+ 2);
1101 change
->allocated
.array
.data
[change
->allocated
.array
.len
] = data
;
1102 change
->allocated
.array
.data
[change
->allocated
.array
.len
+ 1] = NULL
;
1104 change
->allocated
.array
.len
++;
1106 *(gchar
***)entry
->arg_data
= change
->allocated
.array
.data
;
1111 case G_OPTION_ARG_INT
:
1115 if (!parse_int (option_name
, value
,
1120 change
= get_change (context
, G_OPTION_ARG_INT
,
1122 change
->prev
.integer
= *(gint
*)entry
->arg_data
;
1123 *(gint
*)entry
->arg_data
= data
;
1126 case G_OPTION_ARG_CALLBACK
:
1131 if (!value
&& entry
->flags
& G_OPTION_FLAG_OPTIONAL_ARG
)
1133 else if (entry
->flags
& G_OPTION_FLAG_NO_ARG
)
1135 else if (entry
->flags
& G_OPTION_FLAG_FILENAME
)
1138 data
= g_locale_to_utf8 (value
, -1, NULL
, NULL
, error
);
1140 data
= g_strdup (value
);
1144 data
= g_locale_to_utf8 (value
, -1, NULL
, NULL
, error
);
1146 if (!(entry
->flags
& (G_OPTION_FLAG_NO_ARG
|G_OPTION_FLAG_OPTIONAL_ARG
)) &&
1150 retval
= (* (GOptionArgFunc
) entry
->arg_data
) (option_name
, data
, group
->user_data
, error
);
1158 case G_OPTION_ARG_DOUBLE
:
1162 if (!parse_double (option_name
, value
,
1169 change
= get_change (context
, G_OPTION_ARG_DOUBLE
,
1171 change
->prev
.dbl
= *(gdouble
*)entry
->arg_data
;
1172 *(gdouble
*)entry
->arg_data
= data
;
1175 case G_OPTION_ARG_INT64
:
1179 if (!parse_int64 (option_name
, value
,
1186 change
= get_change (context
, G_OPTION_ARG_INT64
,
1188 change
->prev
.int64
= *(gint64
*)entry
->arg_data
;
1189 *(gint64
*)entry
->arg_data
= data
;
1193 g_assert_not_reached ();
1200 parse_short_option (GOptionContext
*context
,
1201 GOptionGroup
*group
,
1212 for (j
= 0; j
< group
->n_entries
; j
++)
1214 if (arg
== group
->entries
[j
].short_name
)
1217 gchar
*value
= NULL
;
1219 option_name
= g_strdup_printf ("-%c", group
->entries
[j
].short_name
);
1221 if (NO_ARG (&group
->entries
[j
]))
1225 if (*new_index
> index
)
1228 G_OPTION_ERROR
, G_OPTION_ERROR_FAILED
,
1229 _("Error parsing option %s"), option_name
);
1230 g_free (option_name
);
1234 if (index
< *argc
- 1)
1236 if (!OPTIONAL_ARG (&group
->entries
[j
]))
1238 value
= (*argv
)[index
+ 1];
1239 add_pending_null (context
, &((*argv
)[index
+ 1]), NULL
);
1240 *new_index
= index
+1;
1244 if ((*argv
)[index
+ 1][0] == '-')
1248 value
= (*argv
)[index
+ 1];
1249 add_pending_null (context
, &((*argv
)[index
+ 1]), NULL
);
1250 *new_index
= index
+ 1;
1254 else if (index
>= *argc
- 1 && OPTIONAL_ARG (&group
->entries
[j
]))
1259 G_OPTION_ERROR
, G_OPTION_ERROR_BAD_VALUE
,
1260 _("Missing argument for %s"), option_name
);
1261 g_free (option_name
);
1266 if (!parse_arg (context
, group
, &group
->entries
[j
],
1267 value
, option_name
, error
))
1269 g_free (option_name
);
1273 g_free (option_name
);
1282 parse_long_option (GOptionContext
*context
,
1283 GOptionGroup
*group
,
1294 for (j
= 0; j
< group
->n_entries
; j
++)
1296 if (*index
>= *argc
)
1299 if (aliased
&& (group
->entries
[j
].flags
& G_OPTION_FLAG_NOALIAS
))
1302 if (NO_ARG (&group
->entries
[j
]) &&
1303 strcmp (arg
, group
->entries
[j
].long_name
) == 0)
1307 option_name
= g_strconcat ("--", group
->entries
[j
].long_name
, NULL
);
1308 parse_arg (context
, group
, &group
->entries
[j
],
1309 NULL
, option_name
, error
);
1310 g_free(option_name
);
1312 add_pending_null (context
, &((*argv
)[*index
]), NULL
);
1317 gint len
= strlen (group
->entries
[j
].long_name
);
1319 if (strncmp (arg
, group
->entries
[j
].long_name
, len
) == 0 &&
1320 (arg
[len
] == '=' || arg
[len
] == 0))
1322 gchar
*value
= NULL
;
1325 add_pending_null (context
, &((*argv
)[*index
]), NULL
);
1326 option_name
= g_strconcat ("--", group
->entries
[j
].long_name
, NULL
);
1328 if (arg
[len
] == '=')
1329 value
= arg
+ len
+ 1;
1330 else if (*index
< *argc
- 1)
1332 if (!(group
->entries
[j
].flags
& G_OPTION_FLAG_OPTIONAL_ARG
))
1334 value
= (*argv
)[*index
+ 1];
1335 add_pending_null (context
, &((*argv
)[*index
+ 1]), NULL
);
1340 if ((*argv
)[*index
+ 1][0] == '-')
1343 retval
= parse_arg (context
, group
, &group
->entries
[j
],
1344 NULL
, option_name
, error
);
1346 g_free (option_name
);
1351 value
= (*argv
)[*index
+ 1];
1352 add_pending_null (context
, &((*argv
)[*index
+ 1]), NULL
);
1357 else if (*index
>= *argc
- 1 &&
1358 group
->entries
[j
].flags
& G_OPTION_FLAG_OPTIONAL_ARG
)
1361 retval
= parse_arg (context
, group
, &group
->entries
[j
],
1362 NULL
, option_name
, error
);
1364 g_free (option_name
);
1370 G_OPTION_ERROR
, G_OPTION_ERROR_BAD_VALUE
,
1371 _("Missing argument for %s"), option_name
);
1372 g_free (option_name
);
1376 if (!parse_arg (context
, group
, &group
->entries
[j
],
1377 value
, option_name
, error
))
1379 g_free (option_name
);
1383 g_free (option_name
);
1393 parse_remaining_arg (GOptionContext
*context
,
1394 GOptionGroup
*group
,
1403 for (j
= 0; j
< group
->n_entries
; j
++)
1405 if (*index
>= *argc
)
1408 if (group
->entries
[j
].long_name
[0])
1411 g_return_val_if_fail (group
->entries
[j
].arg
== G_OPTION_ARG_CALLBACK
||
1412 group
->entries
[j
].arg
== G_OPTION_ARG_STRING_ARRAY
||
1413 group
->entries
[j
].arg
== G_OPTION_ARG_FILENAME_ARRAY
, FALSE
);
1415 add_pending_null (context
, &((*argv
)[*index
]), NULL
);
1417 if (!parse_arg (context
, group
, &group
->entries
[j
], (*argv
)[*index
], "", error
))
1428 free_changes_list (GOptionContext
*context
,
1433 for (list
= context
->changes
; list
!= NULL
; list
= list
->next
)
1435 Change
*change
= list
->data
;
1439 switch (change
->arg_type
)
1441 case G_OPTION_ARG_NONE
:
1442 *(gboolean
*)change
->arg_data
= change
->prev
.bool;
1444 case G_OPTION_ARG_INT
:
1445 *(gint
*)change
->arg_data
= change
->prev
.integer
;
1447 case G_OPTION_ARG_STRING
:
1448 case G_OPTION_ARG_FILENAME
:
1449 g_free (change
->allocated
.str
);
1450 *(gchar
**)change
->arg_data
= change
->prev
.str
;
1452 case G_OPTION_ARG_STRING_ARRAY
:
1453 case G_OPTION_ARG_FILENAME_ARRAY
:
1454 g_strfreev (change
->allocated
.array
.data
);
1455 *(gchar
***)change
->arg_data
= change
->prev
.array
;
1457 case G_OPTION_ARG_DOUBLE
:
1458 *(gdouble
*)change
->arg_data
= change
->prev
.dbl
;
1460 case G_OPTION_ARG_INT64
:
1461 *(gint64
*)change
->arg_data
= change
->prev
.int64
;
1464 g_assert_not_reached ();
1471 g_list_free (context
->changes
);
1472 context
->changes
= NULL
;
1476 free_pending_nulls (GOptionContext
*context
,
1477 gboolean perform_nulls
)
1481 for (list
= context
->pending_nulls
; list
!= NULL
; list
= list
->next
)
1483 PendingNull
*n
= list
->data
;
1489 /* Copy back the short options */
1491 strcpy (*n
->ptr
+ 1, n
->value
);
1501 g_list_free (context
->pending_nulls
);
1502 context
->pending_nulls
= NULL
;
1506 * g_option_context_parse:
1507 * @context: a #GOptionContext
1508 * @argc: a pointer to the number of command line arguments
1509 * @argv: a pointer to the array of command line arguments
1510 * @error: a return location for errors
1512 * Parses the command line arguments, recognizing options
1513 * which have been added to @context. A side-effect of
1514 * calling this function is that g_set_prgname() will be
1517 * If the parsing is successful, any parsed arguments are
1518 * removed from the array and @argc and @argv are updated
1519 * accordingly. A '--' option is stripped from @argv
1520 * unless there are unparsed options before and after it,
1521 * or some of the options after it start with '-'. In case
1522 * of an error, @argc and @argv are left unmodified.
1524 * If automatic <option>--help</option> support is enabled
1525 * (see g_option_context_set_help_enabled()), and the
1526 * @argv array contains one of the recognized help options,
1527 * this function will produce help output to stdout and
1528 * call <literal>exit (0)</literal>.
1530 * Note that function depends on the
1531 * <link linkend="setlocale">current locale</link> for
1532 * automatic character set conversion of string and filename
1535 * Return value: %TRUE if the parsing was successful,
1536 * %FALSE if an error occurred
1541 g_option_context_parse (GOptionContext
*context
,
1549 /* Set program name */
1550 if (!g_get_prgname())
1552 if (argc
&& argv
&& *argc
)
1556 prgname
= g_path_get_basename ((*argv
)[0]);
1557 g_set_prgname (prgname
);
1561 g_set_prgname ("<unknown>");
1564 /* Call pre-parse hooks */
1565 list
= context
->groups
;
1568 GOptionGroup
*group
= list
->data
;
1570 if (group
->pre_parse_func
)
1572 if (!(* group
->pre_parse_func
) (context
, group
,
1573 group
->user_data
, error
))
1580 if (context
->main_group
&& context
->main_group
->pre_parse_func
)
1582 if (!(* context
->main_group
->pre_parse_func
) (context
, context
->main_group
,
1583 context
->main_group
->user_data
, error
))
1589 gboolean stop_parsing
= FALSE
;
1590 gboolean has_unknown
= FALSE
;
1591 gint separator_pos
= 0;
1593 for (i
= 1; i
< *argc
; i
++)
1596 gboolean parsed
= FALSE
;
1598 if ((*argv
)[i
][0] == '-' && (*argv
)[i
][1] != '\0' && !stop_parsing
)
1600 if ((*argv
)[i
][1] == '-')
1604 arg
= (*argv
)[i
] + 2;
1606 /* '--' terminates list of arguments */
1610 stop_parsing
= TRUE
;
1614 /* Handle help options */
1615 if (context
->help_enabled
)
1617 if (strcmp (arg
, "help") == 0)
1618 print_help (context
, TRUE
, NULL
);
1619 else if (strcmp (arg
, "help-all") == 0)
1620 print_help (context
, FALSE
, NULL
);
1621 else if (strncmp (arg
, "help-", 5) == 0)
1625 list
= context
->groups
;
1629 GOptionGroup
*group
= list
->data
;
1631 if (strcmp (arg
+ 5, group
->name
) == 0)
1632 print_help (context
, FALSE
, group
);
1639 if (context
->main_group
&&
1640 !parse_long_option (context
, context
->main_group
, &i
, arg
,
1641 FALSE
, argc
, argv
, error
, &parsed
))
1647 /* Try the groups */
1648 list
= context
->groups
;
1651 GOptionGroup
*group
= list
->data
;
1653 if (!parse_long_option (context
, group
, &i
, arg
,
1654 FALSE
, argc
, argv
, error
, &parsed
))
1666 /* Now look for --<group>-<option> */
1667 dash
= strchr (arg
, '-');
1670 /* Try the groups */
1671 list
= context
->groups
;
1674 GOptionGroup
*group
= list
->data
;
1676 if (strncmp (group
->name
, arg
, dash
- arg
) == 0)
1678 if (!parse_long_option (context
, group
, &i
, dash
+ 1,
1679 TRUE
, argc
, argv
, error
, &parsed
))
1690 if (context
->ignore_unknown
)
1694 { /* short option */
1695 gint j
, new_i
= i
, arg_length
;
1696 gboolean
*nulled_out
= NULL
;
1697 arg
= (*argv
)[i
] + 1;
1698 arg_length
= strlen (arg
);
1699 nulled_out
= g_newa (gboolean
, arg_length
);
1700 memset (nulled_out
, 0, arg_length
* sizeof (gboolean
));
1701 for (j
= 0; j
< arg_length
; j
++)
1703 if (context
->help_enabled
&& arg
[j
] == '?')
1704 print_help (context
, TRUE
, NULL
);
1706 if (context
->main_group
&&
1707 !parse_short_option (context
, context
->main_group
,
1709 argc
, argv
, error
, &parsed
))
1713 /* Try the groups */
1714 list
= context
->groups
;
1717 GOptionGroup
*group
= list
->data
;
1718 if (!parse_short_option (context
, group
, i
, &new_i
, arg
[j
],
1719 argc
, argv
, error
, &parsed
))
1727 if (context
->ignore_unknown
&& parsed
)
1728 nulled_out
[j
] = TRUE
;
1729 else if (context
->ignore_unknown
)
1733 /* !context->ignore_unknown && parsed */
1735 if (context
->ignore_unknown
)
1737 gchar
*new_arg
= NULL
;
1739 for (j
= 0; j
< arg_length
; j
++)
1744 new_arg
= g_malloc (arg_length
+ 1);
1745 new_arg
[arg_index
++] = arg
[j
];
1749 new_arg
[arg_index
] = '\0';
1750 add_pending_null (context
, &((*argv
)[i
]), new_arg
);
1754 add_pending_null (context
, &((*argv
)[i
]), NULL
);
1762 if (!parsed
&& !context
->ignore_unknown
)
1765 G_OPTION_ERROR
, G_OPTION_ERROR_UNKNOWN_OPTION
,
1766 _("Unknown option %s"), (*argv
)[i
]);
1772 /* Collect remaining args */
1773 if (context
->main_group
&&
1774 !parse_remaining_arg (context
, context
->main_group
, &i
,
1775 argc
, argv
, error
, &parsed
))
1778 if (!parsed
&& (has_unknown
|| (*argv
)[i
][0] == '-'))
1783 if (separator_pos
> 0)
1784 add_pending_null (context
, &((*argv
)[separator_pos
]), NULL
);
1788 /* Call post-parse hooks */
1789 list
= context
->groups
;
1792 GOptionGroup
*group
= list
->data
;
1794 if (group
->post_parse_func
)
1796 if (!(* group
->post_parse_func
) (context
, group
,
1797 group
->user_data
, error
))
1804 if (context
->main_group
&& context
->main_group
->post_parse_func
)
1806 if (!(* context
->main_group
->post_parse_func
) (context
, context
->main_group
,
1807 context
->main_group
->user_data
, error
))
1813 free_pending_nulls (context
, TRUE
);
1815 for (i
= 1; i
< *argc
; i
++)
1817 for (k
= i
; k
< *argc
; k
++)
1818 if ((*argv
)[k
] != NULL
)
1824 for (j
= i
+ k
; j
< *argc
; j
++)
1826 (*argv
)[j
-k
] = (*argv
)[j
];
1838 /* Call error hooks */
1839 list
= context
->groups
;
1842 GOptionGroup
*group
= list
->data
;
1844 if (group
->error_func
)
1845 (* group
->error_func
) (context
, group
,
1846 group
->user_data
, error
);
1851 if (context
->main_group
&& context
->main_group
->error_func
)
1852 (* context
->main_group
->error_func
) (context
, context
->main_group
,
1853 context
->main_group
->user_data
, error
);
1855 free_changes_list (context
, TRUE
);
1856 free_pending_nulls (context
, FALSE
);
1862 * g_option_group_new:
1863 * @name: the name for the option group, this is used to provide
1864 * help for the options in this group with <option>--help-</option>@name
1865 * @description: a description for this group to be shown in
1866 * <option>--help</option>. This string is translated using the translation
1867 * domain or translation function of the group
1868 * @help_description: a description for the <option>--help-</option>@name option.
1869 * This string is translated using the translation domain or translation function
1871 * @user_data: user data that will be passed to the pre- and post-parse hooks,
1872 * the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL
1873 * @destroy: a function that will be called to free @user_data, or %NULL
1875 * Creates a new #GOptionGroup.
1877 * Return value: a newly created option group. It should be added
1878 * to a #GOptionContext or freed with g_option_group_free().
1883 g_option_group_new (const gchar
*name
,
1884 const gchar
*description
,
1885 const gchar
*help_description
,
1887 GDestroyNotify destroy
)
1890 GOptionGroup
*group
;
1892 group
= g_new0 (GOptionGroup
, 1);
1893 group
->name
= g_strdup (name
);
1894 group
->description
= g_strdup (description
);
1895 group
->help_description
= g_strdup (help_description
);
1896 group
->user_data
= user_data
;
1897 group
->destroy_notify
= destroy
;
1904 * g_option_group_free:
1905 * @group: a #GOptionGroup
1907 * Frees a #GOptionGroup. Note that you must <emphasis>not</emphasis>
1908 * free groups which have been added to a #GOptionContext.
1913 g_option_group_free (GOptionGroup
*group
)
1915 g_return_if_fail (group
!= NULL
);
1917 g_free (group
->name
);
1918 g_free (group
->description
);
1919 g_free (group
->help_description
);
1921 g_free (group
->entries
);
1923 if (group
->destroy_notify
)
1924 (* group
->destroy_notify
) (group
->user_data
);
1926 if (group
->translate_notify
)
1927 (* group
->translate_notify
) (group
->translate_data
);
1934 * g_option_group_add_entries:
1935 * @group: a #GOptionGroup
1936 * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
1938 * Adds the options specified in @entries to @group.
1943 g_option_group_add_entries (GOptionGroup
*group
,
1944 const GOptionEntry
*entries
)
1948 g_return_if_fail (entries
!= NULL
);
1950 for (n_entries
= 0; entries
[n_entries
].long_name
!= NULL
; n_entries
++) ;
1952 group
->entries
= g_renew (GOptionEntry
, group
->entries
, group
->n_entries
+ n_entries
);
1954 memcpy (group
->entries
+ group
->n_entries
, entries
, sizeof (GOptionEntry
) * n_entries
);
1956 for (i
= group
->n_entries
; i
< group
->n_entries
+ n_entries
; i
++)
1958 gchar c
= group
->entries
[i
].short_name
;
1962 if (c
== '-' || !g_ascii_isprint (c
))
1964 g_warning (G_STRLOC
": ignoring invalid short option '%c' (%d)", c
, c
);
1965 group
->entries
[i
].short_name
= 0;
1970 group
->n_entries
+= n_entries
;
1974 * g_option_group_set_parse_hooks:
1975 * @group: a #GOptionGroup
1976 * @pre_parse_func: a function to call before parsing, or %NULL
1977 * @post_parse_func: a function to call after parsing, or %NULL
1979 * Associates two functions with @group which will be called
1980 * from g_option_context_parse() before the first option is parsed
1981 * and after the last option has been parsed, respectively.
1983 * Note that the user data to be passed to @pre_parse_func and
1984 * @post_parse_func can be specified when constructing the group
1985 * with g_option_group_new().
1990 g_option_group_set_parse_hooks (GOptionGroup
*group
,
1991 GOptionParseFunc pre_parse_func
,
1992 GOptionParseFunc post_parse_func
)
1994 g_return_if_fail (group
!= NULL
);
1996 group
->pre_parse_func
= pre_parse_func
;
1997 group
->post_parse_func
= post_parse_func
;
2001 * g_option_group_set_error_hook:
2002 * @group: a #GOptionGroup
2003 * @error_func: a function to call when an error occurs
2005 * Associates a function with @group which will be called
2006 * from g_option_context_parse() when an error occurs.
2008 * Note that the user data to be passed to @pre_parse_func and
2009 * @post_parse_func can be specified when constructing the group
2010 * with g_option_group_new().
2015 g_option_group_set_error_hook (GOptionGroup
*group
,
2016 GOptionErrorFunc error_func
)
2018 g_return_if_fail (group
!= NULL
);
2020 group
->error_func
= error_func
;
2025 * g_option_group_set_translate_func:
2026 * @group: a #GOptionGroup
2027 * @func: the #GTranslateFunc, or %NULL
2028 * @data: user data to pass to @func, or %NULL
2029 * @destroy_notify: a function which gets called to free @data, or %NULL
2031 * Sets the function which is used to translate user-visible
2032 * strings, for <option>--help</option> output. Different
2033 * groups can use different #GTranslateFunc<!-- -->s. If @func
2034 * is %NULL, strings are not translated.
2036 * If you are using gettext(), you only need to set the translation
2037 * domain, see g_option_group_set_translation_domain().
2042 g_option_group_set_translate_func (GOptionGroup
*group
,
2043 GTranslateFunc func
,
2045 GDestroyNotify destroy_notify
)
2047 g_return_if_fail (group
!= NULL
);
2049 if (group
->translate_notify
)
2050 group
->translate_notify (group
->translate_data
);
2052 group
->translate_func
= func
;
2053 group
->translate_data
= data
;
2054 group
->translate_notify
= destroy_notify
;
2058 dgettext_swapped (const gchar
*msgid
,
2059 const gchar
*domainname
)
2061 return dgettext (domainname
, msgid
);
2065 * g_option_group_set_translation_domain:
2066 * @group: a #GOptionGroup
2067 * @domain: the domain to use
2069 * A convenience function to use gettext() for translating
2070 * user-visible strings.
2075 g_option_group_set_translation_domain (GOptionGroup
*group
,
2076 const gchar
*domain
)
2078 g_return_if_fail (group
!= NULL
);
2080 g_option_group_set_translate_func (group
,
2081 (GTranslateFunc
)dgettext_swapped
,
2087 * g_option_context_set_translate_func:
2088 * @context: a #GOptionContext
2089 * @func: the #GTranslateFunc, or %NULL
2090 * @data: user data to pass to @func, or %NULL
2091 * @destroy_notify: a function which gets called to free @data, or %NULL
2093 * Sets the function which is used to translate the contexts
2094 * user-visible strings, for <option>--help</option> output.
2095 * If @func is %NULL, strings are not translated.
2097 * Note that option groups have their own translation functions,
2098 * this function only affects the @parameter_string (see g_option_context_new()),
2099 * the summary (see g_option_context_set_summary()) and the description
2100 * (see g_option_context_set_description()).
2102 * If you are using gettext(), you only need to set the translation
2103 * domain, see g_context_group_set_translation_domain().
2108 g_option_context_set_translate_func (GOptionContext
*context
,
2109 GTranslateFunc func
,
2111 GDestroyNotify destroy_notify
)
2113 g_return_if_fail (context
!= NULL
);
2115 if (context
->translate_notify
)
2116 context
->translate_notify (context
->translate_data
);
2118 context
->translate_func
= func
;
2119 context
->translate_data
= data
;
2120 context
->translate_notify
= destroy_notify
;
2124 * g_option_context_set_translation_domain:
2125 * @context: a #GOptionContext
2126 * @domain: the domain to use
2128 * A convenience function to use gettext() for translating
2129 * user-visible strings.
2134 g_option_context_set_translation_domain (GOptionContext
*context
,
2135 const gchar
*domain
)
2137 g_return_if_fail (context
!= NULL
);
2139 g_option_context_set_translate_func (context
,
2140 (GTranslateFunc
)dgettext_swapped
,
2146 * g_option_context_set_summary:
2147 * @context: a #GOptionContext
2148 * @summary: a string to be shown in <option>--help</option> output
2149 * before the list of options, or %NULL
2151 * Adds a string to be displayed in <option>--help</option> output
2152 * before the list of options. This is typically a summary of the
2153 * program functionality.
2155 * Note that the summary is translated (see
2156 * g_option_context_set_translate_func(), g_option_context_set_translation_domain()).
2161 g_option_context_set_summary (GOptionContext
*context
,
2162 const gchar
*summary
)
2164 g_return_if_fail (context
!= NULL
);
2166 g_free (context
->summary
);
2167 context
->summary
= g_strdup (summary
);
2172 * g_option_context_get_summary:
2173 * @context: a #GOptionContext
2175 * Returns the summary. See g_option_context_set_summary().
2177 * Returns: the summary
2181 G_CONST_RETURN gchar
*
2182 g_option_context_get_summary (GOptionContext
*context
)
2184 g_return_val_if_fail (context
!= NULL
, NULL
);
2186 return context
->summary
;
2190 * g_option_context_set_description:
2191 * @context: a #GOptionContext
2192 * @description: a string to be shown in <option>--help</option> output
2193 * after the list of options, or %NULL
2195 * Adds a string to be displayed in <option>--help</option> output
2196 * after the list of options. This text often includes a bug reporting
2199 * Note that the summary is translated (see
2200 * g_option_context_set_translate_func()).
2205 g_option_context_set_description (GOptionContext
*context
,
2206 const gchar
*description
)
2208 g_return_if_fail (context
!= NULL
);
2210 g_free (context
->description
);
2211 context
->description
= g_strdup (description
);
2216 * g_option_context_get_description:
2217 * @context: a #GOptionContext
2219 * Returns the description. See g_option_context_set_description().
2221 * Returns: the description
2225 G_CONST_RETURN gchar
*
2226 g_option_context_get_description (GOptionContext
*context
)
2228 g_return_val_if_fail (context
!= NULL
, NULL
);
2230 return context
->description
;
2234 #define __G_OPTION_C__
2235 #include "galiasdef.c"