mcabber-isbear-patches: comparison docs/cmdopts.mdwn

equal deleted inserted replaced

-:93088d0c8140
+:8e1ccd27d60f
 * Integrate and improve completion system.
 * Add common generic stuff, like '--help'.
 * Try to still be lightweight.
 * Try to still be readable.
-It is built around static structure, "command description". User can add or
+It is built around static structure, "command description".  User can add or
-remove these structures to list of commands. FIXME more
+remove these structures to list of commands.  *FIXME* more
 ## Command description struct, 'cmdopts_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 typedef struct cmdopts_struct cmdopts_t;
 typedef enum {
 cmd_default = 0x0000,
 const cmdopts_t     *cmds;
 const gpointer      userdata;
 size_t              valno;
 };
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 This struct describes command as a whole and links to argument descriptions.
 This struct is also used to describe individual subcommands, as they are quite
 similar to normal command, because they can have their own options, arguments
-and subcommands. The fields of this struct:
+and subcommands.  The fields of this struct:
 * 'name' - name of the command or subcommand.
 * 'flags' - currently there's only one flag:
 + 'cmd_safe' -  command is safe to execute in main mcabberrc during
-initialization. Have no meaning for subcommands.
+initialization.  Have no meaning for subcommands.
 + 'cmd_default' - default value of no flags enabled.
-* 'check' - execution environment checker for command. This callback is used to
+* 'check' - execution environment checker for command.  This callback is used
-do general checks before even parsing command line. You can write your own
+to do general checks before even parsing command line.  You can write your
-checker or use standard ones, for example - 'cmd_check_online', that checks,
+own checker or use standard ones, for example - 'cmd_check_online', that
-if you are currently online.
+checks, if you are currently online.
-* 'handle' - command function. It is executed only if command line was
+* 'handle' - command function.  It is executed only if command line was
-successfully parsed and argument values passed the type checking. Unused in
+successfully parsed and argument values passed the type checking.  Unused in
 subcommands.
 * 'opts' - pointer to the array of 'cmdopt_t' structs, describing command-line
-options ("-f bar") and switches ("-x"), that this command accepts.
+options ("-f bar") and switches ("-x"), that this command accepts.  Array
+must end with option, that have 0 as short option character.
 * 'args' - similarly, pointer to the array of 'cmdarg_t' structs, that describe
-command-line positional arguments (in order).
+command-line positional arguments (in order).  Array must end with argument,
+that have NULL name.
 * 'cmds' - pointer to the array of subcommands of this command (or subcommand).
-How parser switches to subcommands we will describe later.
+How parser switches to subcommands we will describe later.  Array must end
+with subcommand, that have NULL name.
 * 'userdata' - arbitrary pointer, where you can put some data, that should
-accompany this command or subcommand. Unused by parser.
+accompany this command or subcommand.  Unused by parser.
 * 'valno' - this is internal value, that is initialized at command definition
-time, you should not modify it. Currently unused in subcommands.
+time, you should not modify it.  Currently unused in subcommands.
 ## Command function, 'cmd_handler_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 typedef gchar *(*cmd_handler_t) (cmdopts_t *command, cmdarg_value_t *values);
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 Command function is passed it's command definition struct (mainly to give it
 access to userdata) and dynamically allocated array of parsed argument values.
 It should return NULL in case all went smoothly, or dynamically allocated error
 appear in command line and how to map all these options and arguments to array
 of values.
 ## Option description struct, 'cmdopt_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 typedef struct {
 const char stortopt;
 const char *longopt;
 cmdarg_t   arg;
 } cmdopt_t;
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 This struct just adds short option character and long option name to generic
 argument struct, that we'll look at right now.
 ## Argument description struct, 'cmdarg_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 typedef struct cmdarg_struct cmdarg_t;
 typedef enum {
 cmdarg_default  = 0x0000,
 cmdarg_subcmd   = 0x0010,
 cmdarg_switch   = 0x0020,
 cmdarg_eol      = 0x0003, // catchall + plain
 cmdarg_chreq    = 0x000C, // check + required
 cmdarg_special  = 0x0030, // subcmd + switch
+cmdarg_trigger  = 0x0024, // switch + check
 } cmdarg_flags_t;
 struct cmdarg_struct {
 const char           *name;
 const guint          pos;
 const cmdarg_type    *type;
 gconstpointer        chkdata;
 gconstpointer        userdata;
 };
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 This struct stores information about mapping between command-line entity
-(switch, option, argument, subcommand) and element in 'values' array. First,
+(switch, option, argument, subcommand) and element in 'values' array.  First,
 let's briefly describe fields, and then walk through their use in different
 entities.
 Fields:
 + 'chreq' - shortcut for "argument must have a valid value".
 + 'special' - this is special type of argument - subcommand or switch.
 * 'defval' - default value for argument in "unchecked" form - i.e., in the form
 of string, as it appears on command line (we'll discuss type checkers and
-what can they do to value later). Before parsing command line, parser will
+what can they do to value later).  Before parsing command line, parser will
 assign this value to corresponding value structure.
 * 'type' - pointer to structure, describing argument type.
 * 'chkdata' - if type needs some additional info, it is a place to supply it.
 * 'userdata' - place for arbitrary info, that should accompany this argument or
-option. Unused by parser.
+option.  Unused by parser.
 Now, let's discuss general case - option with argument or positional argument.
 When parser encounters such argument, it checks 'catchall' and 'plain' flags and
 crops argument value from command line accordingly, then it assigns it to the
 'value.arg' field of 'cmdarg_value_t' struct in array 'values' with index, given
-in 'pos'. Also it marks such value as 'visited' and puts a link to argument
+in 'pos'.  Also it marks such value as 'visited' and puts a link to argument
-description into value's 'src' field. More about effect of these actions later,
+description into value's 'src' field.  More about effect of these actions later,
 in 'cmdarg_value_t' section.
 However, if argument struct is a part of option description struct, and have
-flag 'switch' set, parser will not try to parse value. Instead it will increase
+flag 'switch' set, parser will not try to parse value.  Instead it will increase
-the count in 'value.swc' in corresponding 'cmdarg_value_t' struct. Argument name
+the count in 'value.swc' in corresponding 'cmdarg_value_t' struct.  Argument
-for switches is essentially ignored, but for safety sake it is recommended to
+name for switches is essentially ignored, but for safety sake it is recommended
-duplicate switch long option name here. Flags 'catchall' and 'plain' obviously
+to duplicate switch long option name here.  Flags 'catchall' and 'plain'
-have no effect. Flag 'check' makes switch a trigger, that flips between 'on' and
+obviously have no effect.  Flag 'check' makes switch a trigger, that flips
-'off' for every occurence of flag on command line. Flags 'required' and 'subcmd'
+between 'on' and 'off' for every occurence of flag on command line.  Flags
-also have no effect for obvious reasons. Default value is ignored for switches,
+'required' and 'subcmd' also have no effect for obvious reasons.  Default value
-they always start with count 0 (off). Since switch is internal type, argument
+is ignored for switches, they always start with count 0 (off).  Since switch is
-type field is ignored as well. Flags and source fields of value are updated as
+internal type, argument type field is ignored as well.  Flags and source fields
-usual.
+of value are updated as usual.
 If flag 'subcmd' is set for positional argument, parser crops argument value
 according to flags as usual, but instead of assigning it, walks through list of
 subcommands in command description struct and compares obtained value to
-subcommand names. If it finds corresponding subcommand, it assigns pointer to
+subcommand names.  If it finds corresponding subcommand, it assigns pointer to
 subcommand description struct to 'value.cmd' field of corresponding
-'cmdarg_value_t' struct and updates it's source and flags. Then, instead of
+'cmdarg_value_t' struct and updates it's source and flags.  Then, instead of
 proceeding with parsing process, it recursively calls parser on remaining part
-of command line, passing subparser subcommand description. Note, that if
+of command line, passing subparser subcommand description.  Note, that if
 subcommand parser will end parsing before hitting end of command line, parser
-will proceed with parsing arguments for main command. Default value and argument
+will proceed with parsing arguments for main command.  Default value and
-type fields are ignored for subcommands.
+argument type fields are ignored for subcommands.
 Now let's take a look at value structure, that you'll be dealing with the most
 in the actual code.
 ## Argument value structure, 'cmdarg_value_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 typedef struct cmdarg_value_struct cmdarg_value_t;
 typedef enum {
 cmdval_default = 0x0000,
 cmdval_visited = 0x0100,
 cmdval_freeme  = 0x0200,
 } cmdval_flags_t;
 struct cmdarg_value_struct {
-cmdarg_t       *src;
+const cmdarg_t *src;
 cmdval_flags_t flags;
 union {
-guint        uint;
+guint           uint;
-gint         sint;
+gint            sint;
-guint        swc;
+guint           swc;
-const gchar  *roarg;
+const gchar     *roarg;
-gchar        *arg;
+gchar           *arg;
-cmdopts_t    *cmd;
+const cmdopts_t *cmd;
 struct {
-gpointer   bud;
+gpointer    bud;
-gchar      *resource;
+gchar       *resource;
 } rjid;
-gpointer     ptr;
+gpointer        ptr;
 } value;
 };
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 Command may happen to be called recursively - i.e., something in command may
 cause the event, that will cause another call to the same command, thus we
 cannot store actual values in command/argument definition struct, and have to
-allocate dynamic memory for them. This struct is designed exactly for this.
+allocate dynamic memory for them.  This struct is designed exactly for this.
 Let's take a look at it's fields:
 * 'src' - this points to the argument description, from which this struct is
 holding value right now (note, that value can be initialized several times
 during parsing process from different arguments).
 ## Parsing
 Parser starts by allocating memory for values array, and then initializing it by
 walking through command description, looking at options and arguments and
-assigning default values to corresponding entries in array. It also puts pointer
+assigning default values to corresponding entries in array.  It also puts
-to the argument description into value's 'src' field. Thus, all used in command
+pointer to the argument description into value's 'src' field.  Thus, all used in
-description values will have this field initialized, even if they were not
+command description values will have this field initialized, even if they were
-specified on command line. This comes handly later, when checking for reqired
+not specified on command line.  This comes handly later, when checking for
-value presence. For switches parser just sets the counter to zero. Note, that
+reqired value presence.  For switches parser just sets the counter to zero.
-parser does not descend into subcommands at this stage. It does the same
+Note, that parser does not descend into subcommands at this stage.  It does the
-procedure for subcommand, but later, when it already knows which subcommand is
+same procedure for subcommand, but later, when it already knows which subcommand
-selected. Also note, that if several arguments have the same value index, parser
+is selected.  Also note, that if several arguments have the same value index,
-will use latest encountered one to initialize the value. This is used for
+parser will use latest encountered one to initialize the value.  This is used
-default value in "argument clustering", that I'll show you later.
+for default value in "argument clustering", that I'll show you later.
 Then parser calls command environment checker callback (if present), and if it
-returns error - terminates the process right now. Note, that subcommands can
+returns error - terminates the process right now.  Note, that subcommands can
 also have checkers.
-Next parser does its job of parsing command line. Each time it extracts argument
+Next parser does its job of parsing command line.  Each time it extracts
-value, it into 'value.arg' field of corresponding value entry and pointer to
+argument value, it into 'value.arg' field of corresponding value entry and
-argument description struct into 'src' field. Also it sets 'visited' flag on
+pointer to argument description struct into 'src' field.  Also it sets 'visited'
-value. At this stage value is still just unchecked string, except for special
+flag on value.  At this stage value is still just unchecked string, except for
-argument types. For switch occurence count in 'value.swc' gets increased each
+special argument types.  For switch occurence count in 'value.swc' gets
-time argument was specified. Note however, that if several switches use the same
+increased each time argument was specified.  Note however, that if several
-value index ("clustered switches"), counter gets reset, when switches change one
+switches use the same value index ("clustered switches"), counter gets reset,
-another in sequence - i.e. "-e -s -s -s" will count as three "-s", but "-s -s -e
+when switches change one another in sequence - i.e. "-e -s -s -s" will count as
--s" will count as only one "-s". For subcommands parser checks for corresponding
+three "-s", but "-s -s -e -s" will count as only one "-s".  For subcommands
-subcommand in 'cmds' list, assigns it to 'value.cmd' and recursively passes the
+parser checks for corresponding subcommand in 'cmds' list, assigns it to
-end of command line to be parsed with subcommand description. Note, that for
+'value.cmd' and recursively passes the end of command line to be parsed with
-subcommands parser does "checking on the spot" - if parsed argument value does
+subcommand description.  Note, that for subcommands parser does "checking on the
-not match any subcommand, and argument have 'required' flag set, it raises error
+spot" - if parsed argument value does not match any subcommand, and argument
-immediately (if flag is not set, it merely assigns NULL and proceeds parsing
+have 'required' flag set, it raises error immediately (if flag is not set, it
-according to current command description).
+merely assigns NULL and proceeds parsing according to current command
+description).
-Then parser walks through array of values and performs value checking. Note,
+Then parser walks through array of values and performs value checking.  Note,
 that all values, that need checking at this point should have 'src' field
 initialized - either set at default value assignment step, or during parsing,
-so, parser knows properties of value's argument. Parser only pays attention to
+so, parser knows properties of value's argument.  Parser only pays attention to
 the values, that either have 'visited' flag set (i.e. provided by user) or that
 have 'check' flag in argument description (useful for mandatory arguments or
-default values, that need convesion). If value corresponds to a switch, and
+default values, that need convesion).  If value corresponds to a switch, and
 argument have 'check' flag set, switch occurence count is replaced by remainder
-of division it by 2 (this way switch behaves like trigger). If it is a
+of division it by 2 (this way switch behaves like trigger).  If it is a
 subcommand, and it have 'required' flag set, parser checks, if it have non-NULL
-value. If it is usual argument (option or positional), and it does have 'type',
+value.  If it is usual argument (option or positional), and it does have 'type',
 that have 'check' callback set, parser calls this checker, passing it value
 structure (again, value structure contains pointer to argument description, so,
-checker can access 'chkdata' field, supplied by user). If checker returns error
+checker can access 'chkdata' field, supplied by user).  If checker returns error
-string and argument have 'required' flag set, parser raises error. If flag is
+string and argument have 'required' flag set, parser raises error.  If flag is
 not set, parser just prints warning and proceeds with checking.
 If checking was successful, parser calls command function, providing it with
-command description and values array. This function can also return error, but
+command description and values array.  This function can also return error, but
 at this stage it does not change process, only causes error message to be
 printed.
 And finally parser frees allocated resources - walks through values array,
 calling argument type 'free' callback on values, that have 'freeme' flag set and
 then frees the array itself.
 ## Argument type, 'cmdarg_type_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 typedef struct cmdarg_type_struct cmdarg_type_t;
 typedef gchar *(*cmdarg_checker_t) (cmdarg_value_t *value);
 typedef void (*cmdarg_destructor_t) (cmdarg_value_t *value);
 cmdarg_checker_t    check;
 cmdarg_destructor_t free;
 cmdarg_completor_t  complete;
 };
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 As you can see, argument type is nothing more than a set of callbacks:
 * 'check' - check parsed argument value for conformance to type rules, possibly
 replace with something different, like corresponding integer value or roster
 * 'free' - if type checker may need to free some data afterwards, this callback
 should be set to corresponding function, and each time checker really needs
 value to be freed, it should set flag 'freeme' on value.
-* 'complete' - FIXME not yet designed callback, that will return list of
+* 'complete' - *FIXME* not yet designed callback, that will return list of
 possible completions according to given prefix.
 After parsing command line parser performs argument value checking, that's where
-it calls 'check' callbacks.  Checker is given pointer to value structure, that
+it calls 'check' callbacks.   Checker is given pointer to value structure, that
-it needs to check. Checker can modify value string (except when it is default
+it needs to check.  Checker can modify value string (except when it is default
 value, but you have to supply your default values so, that they do not need
 modifying) or completely replace it with another string or even non-string
-object. If checker uses some resources (eg. allocates memory for replacement
+object.  If checker uses some resources (eg.  allocates memory for replacement
 value), it can set the flag 'freeme' on value to request call to value
-destructor, when values array will be freed. If checker needs some additional
+destructor, when values array will be freed.  If checker needs some additional
 data (eg. it is some generic checker, that needs list of valid values or other
-parameters), these data can be supplied in 'chkdata' field. Checker function
+parameters), these data can be supplied in 'chkdata' field.  Checker function
 should return NULL on success or error string, that will be g_free()'d by
-parser. Take note, that if argument does not have 'reqired' flag set, parser
+parser.  Take note, that if argument does not have 'reqired' flag set, parser
 will ignore checker error, so, it is recommended to nullify invalid value before
 returning error (but it is not required).
 # Examples
 When writing description for a command, first thing, you have to do - is to
-determine, which values your command can get from user. You don't have to be
+determine, which values your command can get from user.  You don't have to be
 shy - new interface is designed to encourage commands to be as flexible and
 option-rich as possible.
 Second - consider, which ones are to be specified as positional arguments, and
 which should become options or switches.
 Next you will want to decide, which checks and restrictions should you put on
-values. Essentially, determine value type.
+values.  Essentially, determine value type.
-And then you can begin writing command definition. So, let's start with
+And then you can begin writing command definition.  So, let's start with
 something simple.
 ## Single-argument no-checks command
 Let's look at command like /say, that have only one argument, that should be
 /ex1 message...
 Definition for such command will look like:
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 // command function predeclaration
-gchar *do_ex1 (cmdopts_t *command, cmdarg_value_t *values);
+gchar *do_ex1 (const cmdopts_t *command, cmdarg_value_t *values);
 // command arguments definition
 cmdopts_t def_ex1 = {
 "ex1",              // command name
 cmd_default,        // flags
 },
 NULL,               // list of subcommands - none
 };
 // Command function gets shown above command description (we don't need it) and
-// argument value list. Returns error message or NULL.
+// argument value list.  Returns error message or NULL.
-gchar *do_ex1 (cmdopts_t *command, cmdarg_value_t *values)
+gchar *do_ex1 (const cmdopts_t *command, cmdarg_value_t *values)
 {
 gchar *message = values[0].value.arg;
 // now do something with message:
 // - check, if message was given at all
 if (!message || !*message)
 ...
 // remove command
 cmd_undef (&def_ex1);
 ...
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 A lot of things to do to achieve a simple goal - does not look quite appealing
-so far. Still, let's tweak our example a bit.
+so far.  Still, let's tweak our example a bit.
 Remember the third step - decide, which checks should apply to our argument.
 Now, look at our command - we check, if message is NULL or if message is empty.
 But imagine, that user has given us a message " " - it's of no big use to us,
 so, probably, we should also strip leading/trailing spaces before doing the
-check. That's where argument types come into play. We can write argument
+check.  That's where argument types come into play.  We can write argument
 checker for that! But luckily, we already have built-in standard checker, that
-does exactly what we need - checks if string contains non-space characters. All
+does exactly what we need - checks if string contains non-space characters.  All
 we need to do - to specify '&cmdarg_type_nonspace' as argument type and remove
 our check inside of the command:
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 ...
 cmdopts_t def_ex1 = {
 "ex1",
 cmd_default,
 {NULL}
 },
 NULL,
 };
-gchar *do_ex1 (cmdopts_t *command, cmdarg_value_t *values)
+gchar *do_ex1 (const cmdopts_t *command, cmdarg_value_t *values)
 {
 scr_log_print (LPRINT_NORMAL, "Got the message: \"%s\".",
 values[0].value.arg);
 return NULL;
 }
 ...
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
-Ok, that's a little bit better. Now let's move on to something more complex.
+Ok, that's a little bit better.  Now let's move on to something more complex.
 ## Switches
 Let's add switches '-s' and '-l', that will define, where to print the message
-to - to log or to screen. For that we will need another two value indices - one
+to - to log or to screen.  For that we will need another two value indices - one
 for each switch.
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 ...
 cmdopts_t def_ex1 = {
 "ex1",
 cmd_default,
 {NULL}
 },
 NULL,
 };
-gchar *do_ex1 (cmdopts_t *command, cmdarg_value_t *values)
+gchar *do_ex1 (const cmdopts_t *command, cmdarg_value_t *values)
 {
 // default value
 guint whereto = LPRINT_NORMAL;
 // -s is default, so, check, that it is not set before checking for -l
 if (!values[1].value.swc)
 scr_log_print (whereto, "Got the message: \"%s\".", values[0].value.arg);
 return NULL;
 }
 ...
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 Ok, that works, but what if user have aliases, and wants last specified option
 to override the value? Currently, if -s was once specified, -l will not have any
-effect, regardless of count or position in command line. Not that good. Let's
+effect, regardless of count or position in command line.  Not that good.  Let's
-use the trick, that I call "argument clustering". We'll specify the same value
+use the trick, that I call "argument clustering".  We'll specify the same value
-index for both switches. Since 'value' struct have the pointer to the argument,
+index for both switches.  Since 'value' struct have the pointer to the argument,
 it was initialized from last time, we can recognize, which switch was used last.
 By default this pointer points to the last argument with this index in command
-definition - we can use that to specify default value. Now, to identify switches
+definition - we can use that to specify default value.  Now, to identify
-we can use argument names, but 'argument' struct contains userdata field, where
+switches we can use argument names, but 'argument' struct contains userdata
-we can put our LPRINT_* constants and just use it directly. So, with clustered
+field, where we can put our LPRINT_* constants and just use it directly.  So,
-switches, we will have:
+with clustered switches, we will have:
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 ...
 cmdopts_t def_ex1 = {
 "ex1",
 cmd_default,
 NULL,
 do_ex1,
 (cmdopt_t[3]){
 // Set both argument indices to 1, specify our constants in userdata
-// field. Screen is default value, thus, it goes last.
+// field.  Screen is default value, thus, it goes last.
 { 'l', "log",    { "log",    1, cmdarg_switch, NULL, NULL, NULL,
 (gpointer)LPRINT_LOG    } },
 { 's', "screen", { "screen", 1, cmdarg_switch, NULL, NULL, NULL,
 (gpointer)LPRINT_NORMAL } },
 {0}
 {NULL}
 },
 NULL,
 };
-gchar *do_ex1 (cmdopts_t *command, cmdarg_value_t *values)
+gchar *do_ex1 (const cmdopts_t *command, cmdarg_value_t *values)
 {
 scr_log_print ((guint)values[1].src -> userdata,
 "Got the message: \"%s\".", values[0].value.arg);
 return NULL;
 }
 ...
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
-That's much better. This trick may be quite useful not only with switches, but
+That's much better.  This trick may be quite useful not only with switches, but
 also with options, sometimes even clustering options with arguments can be
 handy.
 ## Options
 Options are not much different from normal arguments, except there you'll see
 'check' and 'required' mostly only in combination with default value - otherwise
 it defeats the purpose - to be optional.
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 // TODO:
 //   example (not really used as of now - were too complex to deal using old
 //   interface).
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 ## Subcommands
-Now, let's discuss another internal argument type - subcommand. Since
+Now, let's discuss another internal argument type - subcommand.  Since
 subcommands are quite common in mcabber, and since they have quite big impact on
 parsing process, they were made a part of parser.
-Currently, only positional arguments can be subcommands. You can have options or
+Currently, only positional arguments can be subcommands.  You can have options or
 other arguments precede them, though in practice there's no examples of that so
 far.
-So, to indicate, that argument is a subcommand, you just add flag 'subcmd'. When
+So, to indicate, that argument is a subcommand, you just add flag 'subcmd'.
-parser will encounter such argument, it will look up command structure with
+When parser will encounter such argument, it will look up command structure with
 specified name in the list 'cmds' of command definition and proceed parsing,
-using that command definition instead of main one. A good example of command
+using that command definition instead of main one.  A good example of command
 with several completely different subcommands would be '/color', so, let's look:
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
-static gchar *do_color (cmdopts_t *command, cmdarg_value_t *values);
+static gchar *do_color (const cmdopts_t *command, cmdarg_value_t *values);
 // We will put these values in subcommand definition 'userdata' fields
 // to simplify the task of determining, which subcommand was actually selected.
 typedef enum {
 scmd_color_roster,
 }, NULL, (gpointer)scmd_color_mucnick},
 {NULL}
 },
 };
-static gchar *do_color (cmdopts_t *options, cmdarg_value_t *values)
+static gchar *do_color (const cmdopts_t *options, cmdarg_value_t *values)
 {
 scmd_color_t subcmd =
 (scmd_color_t) (values[pos_color_scmd].value.cmd -> userdata);
 if (subcmd == scmd_color_roster) {
 }
 return NULL;
 }
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 Here you also see a lot of new types:
 * 'color_statusmask' - specific to "/color" command wrapper over generic type
 'charset'.  This type allows only word "clear" or string, composed of
 ## Argument types
 Let's take a look at simple checker, that we've encountered first - 'nonspace':
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 // Checker gets parsed value string in 'value.arg', argument description in
 // 'src' and returns error string or NULL.
 gchar *cmdarg_check_nonspace (cmdarg_value_t *arg)
 {
 NULL,
 // completion callabck - none, we can't know, what string may contain
 NULL,
 };
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
-Quite simple, I hope. Now, let's look at more complex type - 'fjid':
+Quite simple, I hope.  Now, let's look at more complex type - 'fjid':
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 // This checker checks syntax of fjid and expands "current-buddy" expressions
 // "." and "./resource".
 gchar *cmdarg_check_fjid (cmdarg_value_t *arg)
 {
 // completor, while possible, is not implemented, as whole completion system is
 // not yet designed.
 NULL,
 };
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
 If possible, you are encouraged to re-use existing checkers - for example, bjid
 checker uses fjid checker to expand "current-buddy" expressions and check
 syntax, and only strips resource afterwards:
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
 gchar *cmdarg_check_bjid (cmdarg_value_t *arg)
 {
 gchar *error = NULL;
 // may need to free value - we're using fjid checker internally
 cmdarg_free_gfree,
 NULL,
 };
-// -------------------------------------------------------------      """     ]]
+// --------------------------------------------------------------     """     ]]
-So far we've only modified string in value. But checkers are not limited to
+So far we've only modified string in value.  But checkers are not limited to
 this, for example, uint checker performs atoi() on value and assigns resulting
-number to value.uint. Take a look at definition of cmdarg_value_t struct - value
+number to value.uint.  Take a look at definition of cmdarg_value_t struct -
-is actually a union of different types of value. If you need something different
+value is actually a union of different types of value.  If you need something
-from existing - you can always allocate your own struct and use value.ptr.
+different from existing - you can always allocate your own struct and use
-However, if you think, that your case is generic enough - contact mcabber
+value.ptr.  However, if you think, that your case is generic enough - contact
-developers, we'll consider adding more variants there. Maybe we'll even add your
+mcabber developers, we'll consider adding more variants there.  Maybe we'll even
-argument type to built-in types.
+add your argument type to built-in types.
 <!-- vim: se ts=4 sw=4 et filetype=markdown tw=80: -->

changeset 81	8e1ccd27d60f
parent 80	93088d0c8140
child 82	06d4a9185902