Command-line parsing

Command-line parsing — parsing command-line parameters

Functions

Types and Values

Description

GXSubCommandOptionContext is a wrapper for GOptionContext to support "sub-commands", that is, command-line tools that offer a number of commands, each with their specific options -- examples include "git", "openssl", "mu".

In the example below, we define a program with two sub-commands, "add" and "remove", each with their specific options.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
static gboolean verbose;
static gboolean beep;
static gint     count;
 
static GOptionEntry main_entries[] =
  {
    { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
    { NULL }
  };
 
static GOptionEntry add_entries[] =
  {
    { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep after adding", NULL },
    { NULL }
  };
 
static GOptionEntry remove_entries[] =
  {
    { "count", 'c', 0, G_OPTION_ARG_INT, &count, "Number of items to remove", "N" },
    { NULL }
  };
 
 
static gboolean
handle_add (gpointer data, GError **err)
{
  // implement the 'add' subcommand
  return TRUE;
}
 
static gboolean
handle_remove (gpointer data, GError **err)
{
  // implement the 'remove' subcommand
  return TRUE;
}
 
 
int
main (int argc, char *argv[])
{
  gboolean                   rv;
  GOptionContext            *o_ctx;
  GXSubCommandOptionContext *sc_ctx;
  GOptionGroup              *og;
  GError                    *err;
 
  o_ctx = g_option_context_new ("- add or remove items");
  g_option_context_add_main_entries (o_ctx, main_entries, "items");
 
  sc_ctx = gx_sub_command_option_context_new (o_ctx);
  
  og = g_option_group_new ("add", "the add subcommand", "add", NULL, NULL);
  g_option_group_add_entries (og, add_entries);
  gx_sub_command_option_context_add_group (sc_ctx, "add", og,
                                           (GXSubCommandFunc)handle_add, NULL);
 
  og = g_option_group_new ("remove", "the remove subcommand", "remove", NULL, NULL);
  g_option_group_add_entries (og, remove_entries);
  gx_sub_command_option_context_add_group (sc_ctx, "remove", og,
                                           (GXSubCommandFunc)handle_remove, NULL);
  err = NULL;
  rv = gx_sub_command_option_context_process (sc_ctx, &argc, &argv, &err);
  if (!rv)
    {
      g_printerr ("error: %s", err ? err->message : "something went wrong");
    }
 
  g_clear_error (&err);
  gx_sub_command_option_context_free (sc_ctx);
 
  return rv ? 0 : 1;
}

Functions

gx_sub_command_option_context_new ()

GXSubCommandOptionContext *
gx_sub_command_option_context_new (GOptionContext *option_context);

Create a new GXSubCommandOptionContext, which takes ownership of context

Parameters

context

a GOptionContext with the main (non-subcommand) options.

[transfer full]

Returns

the new GXSubCommandOptionContext; free with gx_sub_command_context_option_free().

[transfer full]


gx_sub_command_option_context_free ()

void
gx_sub_command_option_context_free (GXSubCommandOptionContext *context);

Free a GXSubCommandOptionContext instance

Parameters

context

a GXSubCommandOptionContext instance

 

GXSubCommandFunc ()

gboolean
(*GXSubCommandFunc) (gpointer user_data,
                     GError **err);

Prototype for a callback function for a GXSubCommandOptionContext group

Parameters

user_data

user-data passed to funciton

 

err

receives error information.

[allow-none]

Returns

TRUE if the function succeeded, FALSE otherwise.


gx_sub_command_option_context_add_group ()

void
gx_sub_command_option_context_add_group
                               (GXSubCommandOptionContext *context,
                                const char *sub_command,
                                GOptionGroup *option_group,
                                GXSubCommandFunc func,
                                gpointer user_data);

Add a sub-command with a set of options, and optionally a function to be called for the subcommand.

Parameters

context

a GXSubCommandOptionContext

 

sub_command

the name of the sub-command. Should be the same as the name of option_group .

 

option_group

the GOptionGroup for this subcommand

 

func

a GXSubCommandFunc function that handles this sub-command.

[allow-none]

user_data

user pointer passed to func

 

gx_sub_command_option_context_process ()

gboolean
gx_sub_command_option_context_process (GXSubCommandOptionContext *context,
                                       gint *argc,
                                       gchar ***argv,
                                       GError **error);

Parses the command-line options, using the main command-line options and the options for appropriate sub-command (if any). If a sub-command function was set with gx_sub_command_option_context_add_group(), that function is invoked for the given group.

See g_option_context_parse for some more details about the parsing.

Parameters

context

a GXSubCommandOptionContext instance

 

argc

a pointer to the number of command-line arguments.

[inout][allow-none]

argv

a pointer to the array of command-line arguments.

[inout][allow-none][array length=argc]

err

receives error information.

[allow-none]

Returns

If a sub-command was recognized and it defined a GSubCommandFunc, returns the result of the invocation. Otherwise, returns TRUE if parsing worked, FALSE otherwise.

Types and Values

GXSubCommandOptionContext

typedef struct _GXSubCommandOptionContext GXSubCommandOptionContext;

A GXSubCommandOptionContext defines which subcommands the command-line parser accepts, and options they takes. It is like a GOptionContext for subcommand parsing.

The struct has only private fields and should not be directly accessed.