Option parser


I've been working on GOption, an option parser to be put in glib. In
GNOME we currently use popt which has problems that GOption tries to

* popt does not support utf-8 which results in things like the help
output not having the correct encoding under some circumstances.

* the popt API doesn't match the glib/gtk+ API very well.

* No good way to group options coming from different sources, for
example gtk options vs application options.

Option groups

In order to support options from different sources, GOption has
something called option groups. An option context has a main group, but
can also have a number of auxiliary groups for options coming from other
places. Options from other groups can also be merged into the main

Here's the --help output from a simple app:

  nautilus [OPTION...] [URI...]

Help Options:
  --help                    Show help options
  --help-all                Show all help options
  --help-gtk                Show Gtk+ help options

Application Options
  -b, --browser             Open a browser window
  -q, --quit                Quit Nautilus
  --no-desktop              Do not manage the desktop
  -d, --display=DISPLAY     X display to use

This app has a gtk group which has the --display option merged into the
main group. The --help-gtk output looks like this:

  nautilus [OPTION...] [URI...]

Help Options:
  --help                    Show help options
  --help-all                Show all help options
  --help-gtk                Show Gtk+ help options

GTK+ Options
  -d, --display=DISPLAY     X display to use
  --g-fatal-warnings        Make all warnings fatal

This makes --help rather clean while still allowing the user to get
information about more rarely used options. (Try running nautilus --help
to see how it looks now, it's not pretty!)

I've modified gtk+ to use GOption for parsing and it seems to work, but
there's no new gtk+ API designed yet. (Perhaps a function like
gtk_init_with_goption_context would suffice, I'm not sure).

The API is attached, I welcome any comments or suggestions.

/* goption.h - Option parser
 *  Copyright (C) 2004  Anders Carlsson <andersca gnome org>
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * Library General Public License for more details.
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.

#ifndef __G_OPTION_H__
#define __G_OPTION_H__

#include <glib/gerror.h>
#include <glib/gquark.h>


/* Should go into gtypes.h */
typedef const gchar * (*GTranslateFunc) (const gchar *str,
					 gpointer     data);

typedef struct _GOptionContext GOptionContext;
typedef struct _GOptionGroup   GOptionGroup;
typedef struct _GOptionEntry   GOptionEntry;

typedef enum
  G_OPTION_FLAG_HIDDEN       = 1 << 0,
  G_OPTION_FLAG_IN_MAIN      = 1 << 1,
} GOptionFlags;

typedef enum
} GOptionArg;

typedef gboolean (*GOptionArgFunc) (const gchar    *option_name,
				    const gchar    *value,
				    gpointer        data,
				    GError        **error);

typedef gboolean (*GOptionParseFunc) (GOptionContext *context,
				      GOptionGroup   *group,
				      gpointer	      data,
				      GError        **error);

typedef void (*GOptionErrorFunc) (GOptionContext *context,
				  GOptionGroup   *group,
				  gpointer        data,
				  GError        **error);

#define G_OPTION_ERROR (g_option_context_error_quark ())

typedef enum
} GOptionError;

GQuark g_option_context_error_quark (void) G_GNUC_CONST;

struct _GOptionEntry
  const char *long_name;
  char        short_name;
  int         flags;

  GOptionArg  arg;
  gpointer    arg_data;
  const char *description;
  const char *arg_description;

GOptionContext *g_option_context_new              (const gchar         *parameter_string);
void            g_option_context_free             (GOptionContext      *context);
void		g_option_context_set_help_enabled (GOptionContext      *context,
						   gboolean		help_enabled);
gboolean	g_option_context_get_help_enabled (GOptionContext      *context);
void		g_option_context_set_ignore_unknown_options (GOptionContext *context,
							     gboolean	     ignore_unknown);
gboolean        g_option_context_get_ignore_unknown_options (GOptionContext *context);

void            g_option_context_add_main_entries (GOptionContext      *context,
						   const GOptionEntry  *entries,
						   const gchar         *translation_domain);
gboolean        g_option_context_parse            (GOptionContext      *context,
						   gint                *argc,
						   gchar             ***argv,
						   GError             **error);

void          g_option_context_add_group      (GOptionContext *context,
					       GOptionGroup   *group);
void          g_option_context_set_main_group (GOptionContext *context,
					       GOptionGroup   *group);
GOptionGroup *g_option_context_get_main_group (GOptionContext *context);

GOptionGroup *g_option_group_new                    (const gchar        *name,
						     const gchar        *description,
						     const char         *help_description,
						     gpointer            user_data,
						     GDestroyNotify      destroy);
void	      g_option_group_set_parse_hooks	    (GOptionGroup       *group,
						     GOptionParseFunc    pre_parse_func,
						     GOptionParseFunc	 post_parse_func,
						     gpointer		 data,
						     GDestroyNotify	 destroy_notify);
void	      g_option_group_set_error_hook	    (GOptionGroup       *group,
						     GOptionErrorFunc	 error_func,
						     gpointer		 data,
						     GDestroyNotify	 destroy_notify);
void          g_option_group_free                   (GOptionGroup       *group);
void          g_option_group_add_entries            (GOptionGroup       *group,
						     const GOptionEntry *entries);
void          g_option_group_set_translate_func     (GOptionGroup       *group,
						     GTranslateFunc      func,
						     gpointer            data,
						     GDestroyNotify      destroy_notify);
void          g_option_group_set_translation_domain (GOptionGroup       *group,
						     const gchar        *domain);


#endif /* __G_OPTION_H__ */

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]