luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-09 12:25:48 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add G_OPTION_FLAG_DEPRECATED

Browse Source 
Generate a deprecation notice in the `--help` output for deprecated
options. This helps with the documentation of command line utilities.

Put the deprecation notice near the argument, to allow application
developers to add a notice on the deprecation on their own, and
explain what to use instead.
This commit is contained in:
Emmanuele Bassi 2025-02-03 15:37:23 +00:00 committed by Philip Withnall
parent cac9100960
commit b145330b75
3 changed files with 84 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
glib/goption.c
View File

@ -541,6 +541,10 @@ calculate_max_length (GOptionGroup *group,
if (!NO_ARG (entry) && entry->arg_description)
len += 1 + _g_utf8_strwidth (TRANSLATE (group, entry->arg_description));
/* " (deprecated)" */
if (entry->flags & G_OPTION_FLAG_DEPRECATED)
len += 3 + _g_utf8_strwidth (_("deprecated"));
max_length = MAX (max_length, len);
}
@ -577,9 +581,16 @@ print_entry (GOptionGroup *group,
if (entry->arg_description)
g_string_append_printf (str, "=%s", TRANSLATE (group, entry->arg_description));
if (entry->flags & G_OPTION_FLAG_DEPRECATED)
{
const char *deprecated = _("deprecated");
g_string_append_printf (str, " (%s)", deprecated);
}
g_string_append_printf (string, "%s%*s %s\n", str->str,
(int) (max_length + 4 - _g_utf8_strwidth (str->str)), "",
entry->description ? TRANSLATE (group, entry->description) : "");
g_string_free (str, TRUE);
}

74
glib/goption.h
View File

@ -55,32 +55,51 @@ typedef struct _GOptionEntry GOptionEntry;
/**
* GOptionFlags:
* @G_OPTION_FLAG_NONE: No flags. Since: 2.42.
* @G_OPTION_FLAG_HIDDEN: The option doesn't appear in `--help` output.
* @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
* `--help` output, even if it is defined in a group.
* `--help` output, even if it is defined in a group.
* @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this
* flag indicates that the sense of the option is reversed. i.e. %FALSE will
* be stored into the argument rather than %TRUE.
* flag indicates that the sense of the option is reversed. i.e. %FALSE will
* be stored into the argument rather than %TRUE.
* @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind,
* this flag indicates that the callback does not take any argument
* (like a %G_OPTION_ARG_NONE option). Since 2.8
* this flag indicates that the callback does not take any argument
* (like a %G_OPTION_ARG_NONE option). Since 2.8
* @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK
* kind, this flag indicates that the argument should be passed to the
* callback in the GLib filename encoding rather than UTF-8. Since 2.8
* kind, this flag indicates that the argument should be passed to the
* callback in the GLib filename encoding rather than UTF-8. Since 2.8
* @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK
* kind, this flag indicates that the argument supply is optional.
* If no argument is given then data of %GOptionParseFunc will be
* set to NULL. Since 2.8
* kind, this flag indicates that the argument supply is optional.
* If no argument is given then data of %GOptionParseFunc will be
* set to NULL. Since 2.8
* @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict
* resolution which prefixes long option names with `groupname-` if
* there is a conflict. This option should only be used in situations
* where aliasing is necessary to model some legacy commandline interface.
* It is not safe to use this option, unless all option groups are under
* your direct control. Since 2.8.
* resolution which prefixes long option names with `groupname-` if
* there is a conflict. This option should only be used in situations
* where aliasing is necessary to model some legacy commandline interface.
* It is not safe to use this option, unless all option groups are under
* your direct control. Since 2.8.
*
* Flags which modify individual options.
*/
/**
* G_OPTION_FLAG_NONE:
*
* No flags.
*
* Since: 2.42
*/
/**
* G_OPTION_FLAG_DEPRECATED:
*
* This flag marks the option as deprecated in the `--help`.
*
* You should update the description of the option to describe what
* the user should do in response to the deprecation, for instance:
* remove the option, or replace it with another one.
*
* Since: 2.84
*/
typedef enum
{
G_OPTION_FLAG_NONE = 0,
@ -90,7 +109,8 @@ typedef enum
G_OPTION_FLAG_NO_ARG = 1 << 3,
G_OPTION_FLAG_FILENAME = 1 << 4,
G_OPTION_FLAG_OPTIONAL_ARG = 1 << 5,
G_OPTION_FLAG_NOALIAS = 1 << 6
G_OPTION_FLAG_NOALIAS = 1 << 6,
G_OPTION_FLAG_DEPRECATED GLIB_AVAILABLE_ENUMERATOR_IN_2_84 = 1 << 7
} GOptionFlags;
/**
@ -98,21 +118,21 @@ typedef enum
* @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags or booleans.
* @G_OPTION_ARG_STRING: The option takes a UTF-8 string argument.
* @G_OPTION_ARG_INT: The option takes an integer argument.
* @G_OPTION_ARG_CALLBACK: The option provides a callback (of type
* #GOptionArgFunc) to parse the extra argument.
* @G_OPTION_ARG_CALLBACK: The option provides a callback (of type #GOptionArgFunc)
* to parse the extra argument.
* @G_OPTION_ARG_FILENAME: The option takes a filename as argument, which will
be in the GLib filename encoding rather than UTF-8.
be in the GLib filename encoding rather than UTF-8.
* @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
* uses of the option are collected into an array of strings.
* uses of the option are collected into an array of strings.
* @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument,
* multiple uses of the option are collected into an array of strings.
* multiple uses of the option are collected into an array of strings.
* @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument
* can be formatted either for the user's locale or for the "C" locale.
* Since 2.12
* can be formatted either for the user's locale or for the "C" locale.
* Since 2.12
* @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like
* %G_OPTION_ARG_INT but for larger numbers. The number can be in
* decimal base, or in hexadecimal (when prefixed with `0x`, for
* example, `0xffffffff`). Since 2.12
* %G_OPTION_ARG_INT but for larger numbers. The number can be in
* decimal base, or in hexadecimal (when prefixed with `0x`, for
* example, `0xffffffff`). Since 2.12
*
* The #GOptionArg enum values determine which type of extra argument the
* options expect to find. If an option expects an extra argument, it can

26
glib/tests/option-context.c
View File

@ -2211,6 +2211,31 @@ test_help_no_help_options (void)
g_option_context_free (context);
}
static void
test_help_deprecated (void)
{
GOptionContext *context;
gchar *str;
gchar *arg = NULL;
GOptionEntry entries[] = {
{ "test", 't', G_OPTION_FLAG_DEPRECATED, G_OPTION_ARG_STRING, &arg, "Test tests", "Argument to use in test" },
{ "test2", 0, 0, G_OPTION_ARG_NONE, NULL, "Tests also", NULL },
G_OPTION_ENTRY_NULL
};
context = g_option_context_new ("blabla");
g_option_context_add_main_entries (context, entries, NULL);
g_option_context_set_summary (context, "Summary");
g_option_context_set_description (context, "Description");
str = g_option_context_get_help (context, FALSE, NULL);
g_test_message ("%s", str);
g_assert (strstr (str, "(deprecated)") != NULL);
g_free (str);
g_option_context_free (context);
}
static void
set_bool (gpointer data)
{
@ -2608,6 +2633,7 @@ main (int argc,
g_test_add_func ("/option/help/options", test_help);
g_test_add_func ("/option/help/no-options", test_help_no_options);
g_test_add_func ("/option/help/no-help-options", test_help_no_help_options);
g_test_add_func ("/option/help/deprecated", test_help_deprecated);
g_test_add_func ("/option/basic", test_basic);
g_test_add_func ("/option/translate", test_translate);