--- a/docs/cmdopts.mdwn Fri Mar 22 02:09:13 2013 +0200
+++ b/docs/cmdopts.mdwn Sat Mar 23 03:53:27 2013 +0200
@@ -16,12 +16,12 @@
* Try to still be lightweight.
* Try to still be readable.
-It is built around static structure, "command description". User can add or
-remove these structures to list of commands. FIXME more
+It is built around static structure, "command description". User can add or
+remove these structures to list of commands. *FIXME* more
## Command description struct, 'cmdopts_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
typedef struct cmdopts_struct cmdopts_t;
@@ -42,52 +42,55 @@
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
- do general checks before even parsing command line. You can write your own
- checker or use standard ones, for example - 'cmd_check_online', that checks,
- if you are currently online.
+ * 'check' - execution environment checker for command. This callback is used
+ to do general checks before even parsing command line. You can write your
+ own checker or use standard ones, for example - 'cmd_check_online', that
+ checks, if you are currently online.
- * 'handle' - command function. It is executed only if command line was
- successfully parsed and argument values passed the type checking. Unused in
+ * 'handle' - command function. It is executed only if command line was
+ 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.
@@ -101,7 +104,7 @@
## Option description struct, 'cmdopt_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
typedef struct {
const char stortopt;
@@ -109,14 +112,14 @@
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;
@@ -131,6 +134,7 @@
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 {
@@ -143,10 +147,10 @@
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.
@@ -178,7 +182,7 @@
* '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.
@@ -186,47 +190,47 @@
* '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
-description into value's 'src' field. More about effect of these actions later,
+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,
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
-the count in 'value.swc' in corresponding 'cmdarg_value_t' struct. Argument name
-for switches is essentially ignored, but for safety sake it is recommended to
-duplicate switch long option name here. Flags 'catchall' and 'plain' obviously
-have no effect. Flag 'check' makes switch a trigger, that flips between 'on' and
-'off' for every occurence of flag on command line. Flags 'required' and 'subcmd'
-also have no effect for obvious reasons. Default value is ignored for switches,
-they always start with count 0 (off). Since switch is internal type, argument
-type field is ignored as well. Flags and source fields of value are updated as
-usual.
+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 for switches is essentially ignored, but for safety sake it is recommended
+to duplicate switch long option name here. Flags 'catchall' and 'plain'
+obviously have no effect. Flag 'check' makes switch a trigger, that flips
+between 'on' and 'off' for every occurence of flag on command line. Flags
+'required' and 'subcmd' also have no effect for obvious reasons. Default value
+is ignored for switches, they always start with count 0 (off). Since switch is
+internal type, argument type field is ignored as well. Flags and source fields
+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
-type fields are ignored for subcommands.
+will proceed with parsing arguments for main command. Default value and
+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;
@@ -237,29 +241,29 @@
} cmdval_flags_t;
struct cmdarg_value_struct {
- cmdarg_t *src;
+ const cmdarg_t *src;
cmdval_flags_t flags;
union {
- guint uint;
- gint sint;
- guint swc;
- const gchar *roarg;
- gchar *arg;
- cmdopts_t *cmd;
+ guint uint;
+ gint sint;
+ guint swc;
+ const gchar *roarg;
+ gchar *arg;
+ const cmdopts_t *cmd;
struct {
- gpointer bud;
- gchar *resource;
+ gpointer bud;
+ 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
@@ -291,56 +295,57 @@
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
-to the argument description into value's 'src' field. Thus, all used in command
-description values will have this field initialized, even if they were not
-specified on command line. This comes handly later, when checking for reqired
-value presence. For switches parser just sets the counter to zero. Note, that
-parser does not descend into subcommands at this stage. It does the same
-procedure for subcommand, but later, when it already knows which subcommand is
-selected. Also note, that if several arguments have the same value index, parser
-will use latest encountered one to initialize the value. This is used for
-default value in "argument clustering", that I'll show you later.
+assigning default values to corresponding entries in array. It also puts
+pointer to the argument description into value's 'src' field. Thus, all used in
+command description values will have this field initialized, even if they were
+not specified on command line. This comes handly later, when checking for
+reqired value presence. For switches parser just sets the counter to zero.
+Note, that parser does not descend into subcommands at this stage. It does the
+same procedure for subcommand, but later, when it already knows which subcommand
+is selected. Also note, that if several arguments have the same value index,
+parser will use latest encountered one to initialize the value. This is used
+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
-value, it into 'value.arg' field of corresponding value entry and pointer to
-argument description struct into 'src' field. Also it sets 'visited' flag on
-value. At this stage value is still just unchecked string, except for special
-argument types. For switch occurence count in 'value.swc' gets increased each
-time argument was specified. Note however, that if several switches use the same
-value index ("clustered switches"), counter gets reset, when switches change one
-another in sequence - i.e. "-e -s -s -s" will count as three "-s", but "-s -s -e
--s" will count as only one "-s". For subcommands parser checks for corresponding
-subcommand in 'cmds' list, assigns it to 'value.cmd' and recursively passes the
-end of command line to be parsed with subcommand description. Note, that for
-subcommands parser does "checking on the spot" - if parsed argument value does
-not match any subcommand, and argument have 'required' flag set, it raises error
-immediately (if flag is not set, it merely assigns NULL and proceeds parsing
-according to current command description).
+Next parser does its job of parsing command line. Each time it extracts
+argument value, it into 'value.arg' field of corresponding value entry and
+pointer to argument description struct into 'src' field. Also it sets 'visited'
+flag on value. At this stage value is still just unchecked string, except for
+special argument types. For switch occurence count in 'value.swc' gets
+increased each time argument was specified. Note however, that if several
+switches use the same value index ("clustered switches"), counter gets reset,
+when switches change one another in sequence - i.e. "-e -s -s -s" will count as
+three "-s", but "-s -s -e -s" will count as only one "-s". For subcommands
+parser checks for corresponding subcommand in 'cmds' list, assigns it to
+'value.cmd' and recursively passes the end of command line to be parsed with
+subcommand description. Note, that for subcommands parser does "checking on the
+spot" - if parsed argument value does not match any subcommand, and argument
+have 'required' flag set, it raises error immediately (if flag is not set, it
+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
-string and argument have 'required' flag set, parser raises error. If flag is
+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
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.
@@ -350,7 +355,7 @@
## Argument type, 'cmdarg_type_t'
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
typedef struct cmdarg_type_struct cmdarg_type_t;
@@ -365,7 +370,7 @@
cmdarg_completor_t complete;
};
-// ------------------------------------------------------------- """ ]]
+// -------------------------------------------------------------- """ ]]
As you can see, argument type is nothing more than a set of callbacks:
@@ -377,38 +382,38 @@
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 needs to check. Checker can modify value string (except when it is default
+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
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.
+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
@@ -420,10 +425,10 @@
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 = {
@@ -449,8 +454,8 @@
};
// Command function gets shown above command description (we don't need it) and
-// argument value list. Returns error message or NULL.
-gchar *do_ex1 (cmdopts_t *command, cmdarg_value_t *values)
+// argument value list. Returns error message or NULL.
+gchar *do_ex1 (const cmdopts_t *command, cmdarg_value_t *values)
{
gchar *message = values[0].value.arg;
// now do something with message:
@@ -472,22 +477,22 @@
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 = {
@@ -518,7 +523,7 @@
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);
@@ -526,17 +531,17 @@
}
...
-// ------------------------------------------------------------- """ ]]
+// -------------------------------------------------------------- """ ]]
-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 = {
@@ -570,7 +575,7 @@
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;
@@ -583,21 +588,21 @@
}
...
-// ------------------------------------------------------------- """ ]]
+// -------------------------------------------------------------- """ ]]
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
-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,
+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
+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
-we can use argument names, but 'argument' struct contains userdata field, where
-we can put our LPRINT_* constants and just use it directly. So, with clustered
-switches, we will have:
+definition - we can use that to specify default value. Now, to identify
+switches we can use argument names, but 'argument' struct contains userdata
+field, where we can put our LPRINT_* constants and just use it directly. So,
+with clustered switches, we will have:
-[[!format c """ // -------------------------------------------------------------
+[[!format c """// --------------------------------------------------------------
...
cmdopts_t def_ex1 = {
@@ -607,7 +612,7 @@
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,
@@ -622,7 +627,7 @@
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);
@@ -630,9 +635,9 @@
}
...
-// ------------------------------------------------------------- """ ]]
+// -------------------------------------------------------------- """ ]]
-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.
@@ -642,33 +647,33 @@
'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
-parser will encounter such argument, it will look up command structure with
+So, to indicate, that argument is a subcommand, you just add flag 'subcmd'.
+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.
@@ -751,7 +756,7 @@
},
};
-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);
@@ -784,7 +789,7 @@
return NULL;
}
-// ------------------------------------------------------------- """ ]]
+// -------------------------------------------------------------- """ ]]
Here you also see a lot of new types:
@@ -810,7 +815,7 @@
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.
@@ -859,11 +864,11 @@
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".
@@ -923,13 +928,13 @@
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)
{
@@ -953,15 +958,15 @@
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
-is actually a union of different types of value. If you need something different
-from existing - you can always allocate your own struct and use value.ptr.
-However, if you think, that your case is generic enough - contact mcabber
-developers, we'll consider adding more variants there. Maybe we'll even add your
-argument type to built-in types.
+number to value.uint. Take a look at definition of cmdarg_value_t struct -
+value is actually a union of different types of value. If you need something
+different from existing - you can always allocate your own struct and use
+value.ptr. However, if you think, that your case is generic enough - contact
+mcabber developers, we'll consider adding more variants there. Maybe we'll even
+add your argument type to built-in types.
<!-- vim: se ts=4 sw=4 et filetype=markdown tw=80: -->