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

  1deferred class GLIB_SHELL_RELATED_UTILITIES
  2--    Shell-related Utilities
  3
  4--    Shell-related Utilities -- shell-like commandline handling.
  5
  6-- Synopsis
  7
  8
  9--  #include <glib.h>
 10
 11
 12--  enum        GShellError;
 13--  #define     G_SHELL_ERROR
 14--  gboolean    g_shell_parse_argv              (const gchar *command_line,
 15--                                               gint *argcp,
 16--                                               gchar ***argvp,
 17--                                               GError **error);
 18--  gchar*      g_shell_quote                   (const gchar *unquoted_string);
 19--  gchar*      g_shell_unquote                 (const gchar *quoted_string,
 20--                                               GError **error);
 21
 22
 23-- Description
 24
 25-- Details
 26
 27--   enum GShellError
 28
 29--  typedef enum
 30--  {
 31--    /* mismatched or otherwise mangled quoting */
 32--    G_SHELL_ERROR_BAD_QUOTING,
 33--    /* string to be parsed was empty */
 34--    G_SHELL_ERROR_EMPTY_STRING,
 35--    G_SHELL_ERROR_FAILED
 36--  } GShellError;
 37
 38--    Error codes returned by shell functions.
 39
 40--    G_SHELL_ERROR_BAD_QUOTING  Mismatched or otherwise mangled quoting.
 41--    G_SHELL_ERROR_EMPTY_STRING String to be parsed was empty.
 42--    G_SHELL_ERROR_FAILED       Some other error.
 43
 44--    ---------------------------------------------------------------------------------
 45
 46--   G_SHELL_ERROR
 47
 48--  #define G_SHELL_ERROR g_shell_error_quark ()
 49
 50--    Error domain for shell functions. Errors in this domain will be from the
 51--    GShellError enumeration. See GError for information on error domains.
 52
 53--    ---------------------------------------------------------------------------------
 54
 55--   g_shell_parse_argv ()
 56
 57--  gboolean    g_shell_parse_argv              (const gchar *command_line,
 58--                                               gint *argcp,
 59--                                               gchar ***argvp,
 60--                                               GError **error);
 61
 62--    Parses a command line into an argument vector, in much the same way the shell
 63--    would, but without many of the expansions the shell would perform (variable
 64--    expansion, globs, operators, filename expansion, etc. are not supported). The
 65--    results are defined to be the same as those you would get from a UNIX98 /bin/sh,
 66--    as long as the input contains none of the unsupported shell expansions. If the
 67--    input does contain such expansions, they are passed through literally. Possible
 68--    errors are those from the G_SHELL_ERROR domain. Free the returned vector with
 69--    g_strfreev().
 70
 71--    command_line : command line to parse
 72--    argcp :        return location for number of args
 73--    argvp :        return location for array of args
 74--    error :        return location for error
 75--    Returns :      TRUE on success, FALSE if error set
 76
 77--    ---------------------------------------------------------------------------------
 78
 79--   g_shell_quote ()
 80
 81--  gchar*      g_shell_quote                   (const gchar *unquoted_string);
 82
 83--    Quotes a string so that the shell (/bin/sh) will interpret the quoted string to
 84--    mean unquoted_string. If you pass a filename to the shell, for example, you
 85--    should first quote it with this function. The return value must be freed with
 86--    g_free(). The quoting style used is undefined (single or double quotes may be
 87--    used).
 88
 89--    unquoted_string : a literal string
 90--    Returns :         quoted string
 91
 92--    ---------------------------------------------------------------------------------
 93
 94--   g_shell_unquote ()
 95
 96--  gchar*      g_shell_unquote                 (const gchar *quoted_string,
 97--                                               GError **error);
 98
 99--    Unquotes a string as the shell (/bin/sh) would. Only handles quotes; if a string
100--    contains file globs, arithmetic operators, variables, backticks, redirections, or
101--    other special-to-the-shell features, the result will be different from the result
102--    a real shell would produce (the variables, backticks, etc. will be passed through
103--    literally instead of being expanded). This function is guaranteed to succeed if
104--    applied to the result of g_shell_quote(). If it fails, it returns NULL and sets
105--    the error. The quoted_string need not actually contain quoted or escaped text;
106--    g_shell_unquote() simply goes through the string and unquotes/unescapes anything
107--    that the shell would. Both single and double quotes are handled, as are escapes
108--    including escaped newlines. The return value must be freed with g_free().
109--    Possible errors are in the G_SHELL_ERROR domain.
110
111--    Shell quoting rules are a bit strange. Single quotes preserve the literal string
112--    exactly. escape sequences are not allowed; not even \' - if you want a ' in the
113--    quoted text, you have to do something like 'foo'\''bar'. Double quotes allow $,
114--    `, ", \, and newline to be escaped with backslash. Otherwise double quotes
115--    preserve things literally.
116
117--    quoted_string : shell-quoted string
118--    error :         error return location or NULL
119--    Returns :       an unquoted string
120end -- class GLIB_SHELL_RELATED_UTILITIES