The long option parser for subcommands (lopsub).
[lopsub.git] / lopsub.h.m4
1 VERBATIM_C(«
2 /*
3 * Copyright (C) 2016 Andre Noll <maan@tuebingen.mpg.de>
4 *
5 * Licensed under the LGPL v3, see http://www.gnu.org/licenses/lgpl-3.0.html
6 */
7
8 #include <string.h>
9 #include <inttypes.h>
10 #include <stdbool.h>
11
12 #ifndef _LOPSUB_H
13 #define _LOPSUB_H
14 »)
15
16 STATEMENT(
17 «struct lls_suite»,
18 «Opaque structure which describes a lopsub suite.»,
19 «
20 This structure is defined in the .c file which is generated by
21 lopsubgen(1). The corresponding header file exposes a const pointer
22 to a this structure for use in the application.
23
24 Applications can not de-reference this pointer or access its content
25 directly. They must call one of the accessor functions described below.
26 »)
27
28 STATEMENT(
29 «struct lls_command»,
30 «Represents one command of a suite.»,
31 «
32 A command is identified by a suite and a command number. The symbolic
33 names of all commands defined in a suite are exposed in the enumeration
34 defined in the header file which is generated by lopsubgen(1),
35
36 Applications can obtain an opaque pointer to a command by calling
37 lls_cmd(), providing the command number and the suite pointer as
38 arguments.
39 »)
40
41 STATEMENT(
42 «struct lls_option»,
43 «Represents one option of a command.»,
44 «
45 Similar to a command, an option is identified by a command and an
46 option number. The header file created by the lopsubgen(1) utility
47 provides an enumeration for all options of each command.
48
49 The lls_opt() function returns an opaque pointer to an option, given
50 a command pointer and an option number.
51 »)
52
53 STATEMENT(
54 «struct lls_parse_result»,
55 «An argument vector, fully parsed according to a lopsub command.»,
56 «
57 A pointer to an opaque structure of this type is returned by
58 lls_parse() if the argument vector was found valid for the given
59 command.
60
61 Several functions (described below) take a pointer to such a
62 structure. This enables applications to obtain details about the
63 options and arguments that were given in the argument vector, for
64 example whether an option was specified and how many non-options
65 (aka inputs) were given.
66 »)
67
68 STATEMENT(
69 «struct lls_opt_result»,
70 «The part of a parse result related to a specific option»,
71 «
72 Given an option and a parse result, the lls_opt_result() function
73 returns an opaque pointer to a structure of this type which contains
74 information about the option in the argument vector that was used to
75 create the parse result.
76
77 A pointer to a structure of this type can be passed to the various
78 accessor functions described below. These functions return information
79 about the option in the argument vector, for example how many times
80 the option was given.
81 »)
82
83 DECLARE_FUNCTION(
84 «lls_strerror»,
85 «A strerror-like function for lopsub error codes.»,
86 «
87 This works just like strerror(3).
88 », «
89 «int lss_errno», «positive error code returned from a lopsub library function»
90 », «
91 »,
92 «const char *», «points to static memory, must not be freed by the caller»
93 )
94
95 DECLARE_FUNCTION(
96 «lls_parse»,
97 «Parse an argument vector according to a lopsub command.»,
98 «
99 This function turns a broken-up command line into a parse result,
100 completely parsing all arguments according to the options defined
101 in the given a lopsub command. As usual, options may be given in any
102 order and the special argument "--" forces an end of option-scanning.
103
104 For each option defined in the suite, if the multiple flag is set
105 for the option, the parse result contains an array of values, with
106 one value for each time the option was given. Conversely, if the
107 multiple flag is not set, only a single value is stored in the parse
108 result. Those options may still be given multiple times, but only
109 the last given argument is stored while all previous arguments are
110 discarded.
111
112 For options which take an integer value, conversion is performed in
113 a way that recognizes an optional base prefix like "0x". The empty
114 string and strings with trailing non-digit characters result in a
115 parse error. Range violations are detected and also cause the function
116 to fail.
117 », «
118 «int argc», «Usual argument counter.»,
119 «char **argv», «Usual argument vector to parse.»,
120 «const struct lls_command *cmd», «Contains names and characteristics of all allowed options.»,
121 «struct lls_parse_result **lprp», «Result pointer.»,
122 «char **errctx», «Optional error context string, only set on failure»
123 », «
124 The parse_result pointer returned through lprp can be passed to several
125 accessor functions described below in order to obtain information
126 about the options and arguments in argv[].
127 »,
128 «int», «Standard (negative error code on failure, non-negative on success).»,
129 «
130 On success lprp is initialized according to the options that have been
131 parsed successfully. In this case either errctx or *errctx is NULL,
132 so no cleanup needs to be performed in the caller. However, when the
133 caller is no longer interested in the parse result, it should call
134 lls_free_parse_result() to release the memory that was allocated
135 during the call to lls_parse().
136
137 On errors, *lprp is set to NULL and the function returns a negative
138 error code. This can happen for various reasons, for example if an
139 invalid option or argument was given. Another possible reason is worth
140 mentioning: when the non-opts-name directive was not specified in the
141 suite, the subcommand is assumed to take no non-option arguments. In
142 this case, lls_parse() fails if the argument vector does contain any
143 non-option arguments.
144
145 In the error case, if errctx is not NULL, *errctx points to a
146 zero-terminated string which describes the context of the error
147 condition, for example the problematic element of argv[]. The only
148 exception is when an out of memory condition occurs. In this case
149 *errctx may be NULL because the function was unable to allocate
150 the memory needed for the error context. If *errctx is not NULL,
151 the memory it points to should be freed by the caller. However,
152 lls_free_parse_result() need not be called in this case.
153 »)
154
155 DECLARE_FUNCTION(
156 «lls_free_parse_result»,
157 «Deallocate a parse result.»,
158 «
159 This frees the memory space allocated by lls_parse().
160 », «
161 «struct lls_parse_result *lpr», «As returned by lls_parse().»,
162 «const struct lls_command *cmd»,
163 «This must match the pointer passed earlier to lls_parse().»
164 », «
165 The parse result pointer must have been returned by a previous
166 call to lls_parse() or lls_serialize_parse_result(). Otherwise, or
167 if lls_free_parse_result has already been called before, undefined
168 behavior occurs. It's OK to pass a NULL pointer though. In this case
169 no action is performed.
170 »,
171 «void»
172 )
173
174 DECLARE_FUNCTION(
175 «lls_long_help»,
176 «Return the long help text of a command.»,
177 «
178 The long help text contains the synopsis, the purpose and the help
179 text of the command, followed by the option list including descriptions
180 and help for each option.
181 », «
182 «const struct lls_command *cmd», «As returned from lls_cmd().»
183 », «
184 »,
185 «char *», «A dynamically allocated string that must be freed by the caller.»
186 )
187
188 DECLARE_FUNCTION(
189 «lls_short_help»,
190 «Return the short help text of a command.»,
191 «
192 This is similar to lls_long_help() but help texts are omitted from
193 the output.
194 », «
195 «const struct lls_command *cmd», «See lls_long_help().»
196 », «
197 »,
198 «char *», «See lls_long_help().»
199 )
200
201 DECLARE_FUNCTION(
202 «lls_lookup_subcmd»,
203 «Tell whether the given string is the name of a subcommand.»,
204 «
205 This tries to match the given string against the subcommands of the
206 suite. Exact matches and unique partial matches count as success.
207 », «
208 «const char *string», «The name to look up.»,
209 «const struct lls_suite *suite», «Contains the command list.»,
210 «char **errctx», «Contains lookup string and the name of the suite.»
211 », «
212 »,
213 «int», «The command number on success, negative error code on failure.»,
214 «
215 The lookup fails if (a) the given string pointer is NULL, or (b) if
216 the string is no prefix of any subcommand of the suite, or (c) if it
217 is a proper prefix of more than one subcommand.
218
219 On success the error context pointer is set to NULL. In the error case,
220 if errctx is not NULL, *errctx is pointed to a string that must be
221 freed by the caller.
222 »)
223
224 DECLARE_FUNCTION(
225 «lls_cmd»,
226 «Return a pointer to a command structure.»,
227 «
228 Applications usually call this at the beginning of each function that
229 implements a lopsub command (aka command handler). The returned
230 pointer serves as an abstract reference to the command. This
231 reference is needed to call other functions of the lopsub library,
232 notably lls_parse().
233 », «
234 «unsigned cmd_num», «Appropriate enum value from the header file.»,
235 «const struct lls_suite *suite», «Also declared in the header file.»
236 », «
237 The suite pointer and all valid command numbers are defined in the
238 header file which is generated by lopsubgen(1). Hence this header
239 file must be included from the application to get the name of the
240 suite pointer variable and the command numbers.
241 »,
242 «const struct lls_command *», «Never returns NULL.»,
243 «
244 This function always succeeds if both arguments are valid. That is,
245 the command number is a symbolic constant from the LSG_XXX_COMMANDS
246 enumeration of the header file generated by lopsubgen(1), and the suite
247 pointer equals the pointer that is declared in the same header file.
248
249 If at least one of the arguments are invalid, the behavior is
250 undefined.
251 »)
252
253 DECLARE_FUNCTION(
254 «lls_command_name»,
255 «Obtain the name of the command, given a command pointer.»,
256 «
257 Even in situations where the application knows the name of the command,
258 it is less error-prone to call this function rather than to duplicate
259 the command name in the application.
260 », «
261 «const struct lls_command *cmd», «As obtained from lls_cmd().»
262 », «
263 »,
264 «const char *», «Never returns NULL.»,
265 «
266 This function succeeds unless the given command pointer is invalid
267 (was not obtained through an earlier call to lls_cmd() or is NULL),
268 in which case the behavior is undefined. The return pointer refers
269 to static storage that must not be freed by the caller.
270 »)
271
272 DECLARE_FUNCTION(
273 «lls_user_data»,
274 «Obtain the application-specific data pointer.»,
275 «
276 Some applications need to store further information for each subcommand,
277 for example a function pointer which refers to the implementation of
278 the subcommand. The optional user data feature allows to define one
279 application defined pointer that can be retrieved by calling this
280 function.
281
282 Of course storing one function pointer per command could simply be
283 done by defining a suitable array in the application which contains
284 one pointer per (sub)command. However, this approach has the disadvantage
285 that it effectively creates two command lists (one in the suite
286 file and one for the array) that need to be maintained and kept in
287 sync. Moreover, functions can not be declared as static if they are
288 defined in a different source file than the one that defines the array.
289
290 Therefore, lopsub offers an alternative: The .c file generated by
291 lopsubgen(1) declares one const void * pointer per command. These
292 pointers are marked with the "weak" attribute (a gcc extension, but
293 also available for clang). This instructs the compiler to store the
294 declaration as a weak symbol in the object file. Since the linker
295 does not require weak symbols to be defined, linking succeeds even
296 if the application chooses to not employ the user data feature.
297
298 To make use of the user data feature, the application needs to define
299 one pointer for each command called lsg_xxx_com_yyy_user_data, where
300 xxx is the name of the suite and yyy the name of the command. A
301 suitable preprocessor macro can make this as simple as EXPORT_CMD(foo).
302 », «
303 «const struct lls_command *cmd», «As obtained from lls_cmd().»
304 », «
305 »,
306 «const void *», «The user data pointer defined in the application.»,
307 «
308 If the application did not define a user data pointer for the given
309 command, the function returns NULL.
310 »)
311
312 DECLARE_FUNCTION(
313 «lls_opt_result»,
314 «Extract information about one option from a parse result.»,
315 «
316 The returned pointer can be passed to the accessor functions described
317 below. Those functions let the applications tell how many times the
318 option was given and retrieve any argument(s) for the option.
319 », «
320 «unsigned opt_num», «As declared in the header file.»,
321 «const struct lls_parse_result *lpr», «As returned from lls_parse().»
322 », «
323 The header file generated by lopsubgen(1) generates for each command
324 an enumeration which declares one option number per option as a
325 symbolic constant.
326 »,
327 «const struct lls_opt_result *», «Never returns NULL.»,
328 «
329 If the parse result pointer is invalid (was not returned by
330 lls_parse(), or is NULL), or the option number does not correspond to
331 the command that was used to create the parse result, the behaviour
332 is undefined. Otherwise this function succeeds.
333 »)
334
335 DECLARE_FUNCTION(
336 «lls_opt»,
337 «Get a reference to an option, given a command and an option number.»,
338 «
339 While an opt_result pointer described above is used to obtain
340 information in an argument vector, the pointer returned by this
341 function allows to obtain information about the option itself.
342
343 Applications rarely need to care about the option pointer. It
344 is required to get the possible values of an enumeration option
345 though. See lls_enum_string_val().
346 », «
347 «unsigned opt_num», «See lls_opt_result()»,
348 «const struct lls_command *cmd», «Obtained from lls_cmd().»
349 », «
350 »,
351 «const struct lls_option *», «Never returns NULL.»,
352 «
353 This function always succeeds if both arguments are
354 valid. Otherwise the behavior is undefined.
355 »)
356
357 DECLARE_FUNCTION(
358 «lls_opt_given»,
359 «Return how many times an option was given.»,
360 «
361 This is employed as follows. Applications first call lls_parse() to
362 initialize the parse result, followed by lls_opt_result() to obtain a
363 reference to those parts of the parse result that are related to one
364 specific option. The reference can then be passed to this function
365 to find out how many times the option was given.
366 », «
367 «const struct lls_opt_result *r», «As returned from lls_opt_result().»
368 », «
369 »,
370 «unsigned», «Zero means: Not given at all.»,
371 «
372 Even if the multiple flag was not set for the option, the returned
373 value may be greater than one because this flag only affects how many
374 arguments are stored in the parse result.
375
376 This function succeeds unless the opt_result pointer is invalid
377 (was not returned by lls_opt_result(), or is NULL), in which case
378 the behaviour is undefined.
379 »)
380
381 DECLARE_FUNCTION(
382 «lls_string_val»,
383 «Retrieve one argument to a string option.»,
384 «
385 This function may only be called for options which take an optional or
386 required argument of string type. Enum options (which take as their
387 argument one of a fixed, finite set of possible strings), however,
388 are treated as if the option took an argument of uint32 type. Hence
389 this function must not be called for these options.
390 », «
391 «unsigned idx», «The index in the array of values.»,
392 «const struct lls_opt_result *r», «As returned from lls_opt_result.»
393 », «
394 The first argument must be zero if the multiple flag is not set for
395 the option. Otherwise any number between zero and n - 1 (inclusively)
396 may be passed, where n is the number of times the option was given,
397 that is, the return value of lls_opt_given().
398
399 As as special case, if the option was not given at all (i.e., n == 0),
400 it is still OK to call this function with an index value of zero. In
401 this case, the default value for the option will be returned, or NULL
402 if no default value was specified in the suite.
403 »,
404 «const char *», «The argument that corresponds to the given index.»,
405 «
406 The memory referenced by the return pointer is part of the parse
407 result and must not be freed by the caller. It will be freed when
408 lls_free_parse_result() is called.
409
410 Undefined behaviour occurs in all of the following cases: (a) the
411 index is out of range, (b) the opt_result pointer is NULL or was
412 not obtained through a previous call to lls_opt_result(), (c) the
413 opt_result pointer corresponds to an option which takes an argument
414 of different type or no argument at all. If none of these conditions
415 apply, the function is guaranteed to succeed.
416 »)
417
418 DECLARE_FUNCTION(
419 «lls_int32_val»,
420 «Retrieve one argument to an option that takes an int32 argument.»,
421 «
422 This is like lls_string_val(), but for options which take an optional
423 or required argument of type int32.
424 », «
425 «unsigned idx», «See lls_string_val()»,
426 «const struct lls_opt_result *r», «See lls_string_val().»
427 », «
428 As for lls_string_val(), a zero index value is considered a valid
429 input even if the option was not given at all. In this case. the
430 default value is returned, or zero if the option has no default value.
431 »,
432 «int32_t», «The argument, converted to a 32 bit signed integer.»,
433 «
434 Since conversion of the argument to int32_t takes place earlier during
435 lls_parse(), no errors are possible unless the index parameter or the
436 the opt result pointer (or both) are invalid. See above for details.
437 »)
438
439 DECLARE_FUNCTION(
440 «lls_uint32_val»,
441 «Retrieve one argument to an option that takes an uint32 argument.»,
442 «
443 Identical to lls_int32_val(), except the argument type of the option
444 and the return value are different.
445
446 For enum options, this is the correct function to call in order
447 to obtain the index into the array of possible values, see
448 lls_enum_string_val() below.
449 », «
450 «unsigned idx», «See lls_int32_val().»,
451 «const struct lls_opt_result *r», «See lls_int32_val().»
452 », «
453 »,
454 «uint32_t», «See lls_int32_val().»
455 )
456
457 DECLARE_FUNCTION(
458 «lls_int64_val»,
459 «Retrieve one argument to an option that takes an int64 argument.»,
460 «
461 Identical to lls_int32_val(), except that this function must be used
462 for options which take a 64 bit signed integer argument.
463 », «
464 «unsigned idx», «See lls_int32_val().»,
465 «const struct lls_opt_result *r», «See lls_int32_val().»
466 », «
467 »,
468 «int64_t», «See lls_int32_val().»
469 )
470
471 DECLARE_FUNCTION(
472 «lls_uint64_val»,
473 «Retrieve one argument to an option that takes an uint64 argument.»,
474 «
475 Identical to lls_int32_val(), except that this function must be used
476 for options which take a 64 bit unsigned integer argument.
477 », «
478 «unsigned idx», «See lls_int32_val().»,
479 «const struct lls_opt_result *r», «See lls_int32_val().»
480 », «
481 »,
482 «uint64_t», «See lls_int32_val().»
483 )
484
485 DECLARE_FUNCTION(
486 «lls_enum_string_val»,
487 «Get one possible argument value for an option.»,
488 «
489 This function must only be called for enum options. That is, options
490 for which the set of possible arguments was defined through the values
491 directive in the suite.
492 », «
493 «unsigned idx», «Determines which of the possible values to get.»,
494 «const struct lls_option *opt», «As returned by lls_opt().»
495 », «
496 The possible values of an enum option are a property of the option
497 itself and are thus independent of the command line. Therefore this
498 function expects an option pointer rather than a pointer to an opt
499 result.
500
501 The index parameter must be a value between zero and the number of
502 possible values minus one, inclusively. This number is declared as
503 the last member of the enumeration for the option, which is defined
504 of the generated header file.
505 »,
506 «const char *», «Static memory, must not be freed.»,
507 «
508 Behavior is undefined if the given option is not an enum option, a
509 NULL pointer is passed, or if the index value is out of range.
510 »
511 )
512
513 DECLARE_FUNCTION(
514 «lls_num_inputs»,
515 «Get the number of non-option arguments.»,
516 «
517 In addition to options and their arguments, subcommands may accept
518 any number of additional arguments which are not related to any
519 particular option. For example, file names are frequently passed
520 as such non-option arguments (aka inputs).
521 », «
522 «const struct lls_parse_result *lpr», «As returned from lls_parse().»
523 », «
524 Passing a NULL pointer to this function results in undefined behaviour.
525 »,
526 «unsigned», «Number of non-option arguments.»,
527 «
528 This function never fails. See also lls_input(), lls_check_arg_count().
529 »)
530
531 DECLARE_FUNCTION(
532 «lls_input»,
533 «Get a reference to one non-option argument.»,
534 «
535 If the argument vector passed to lls_parse() contained non-option
536 arguments, the value of each of them can be obtained by calling
537 this function.
538 », «
539 «unsigned idx», «The index into the array of non-option arguments.»,
540 «const struct lls_parse_result *lpr», «As returned from lls_parse().»
541 », «
542 The index must be between zero and n-1, inclusively, where n is the
543 number returned by lls_num_inputs(). The parse_result pointer must have
544 been obtained by an earlier call to lls_parse().
545 »,
546 «const char *», «Pointer to the corresponding non-option argument.»,
547 «
548 If the conditions described above are met, the function is guaranteed
549 to succeed. It will never return a NULL pointer in this case.
550 »
551 )
552
553 DECLARE_FUNCTION(
554 «lls_version»,
555 «Get the version string of the lopsub library.»,
556 «
557 The version string is determined at build time from the sha1 of the
558 HEAD git commit or from the name of the top level directory for compiling
559 from a gitweb snapshot.
560 », «
561 «void»,
562 », «
563 »,
564 «const char *», «Static storage, must not be freed by the caller.»,
565 «
566 The returned string is of the form <tag>-<d>-g<sha1>, where <tag>
567 is the name of the last tagged commit contained in the HEAD commit,
568 <d> is the number of commits between <tag> and HEAD, and <sha1> is the
569 first four hex digits of the hash of the HEAD commit. If the working
570 tree was dirty at compile time, the string "-dirty" is appended to
571 the version string.
572
573 This function always succeeds.
574 »
575 )
576
577 DECLARE_FUNCTION(
578 «lls_purpose»,
579 «Get the line which describes the purpose of a command.»,
580 «
581 This function is useful for applications which need to print
582 their own command summary rather than employ lls_short_help() and
583 lls_long_help(). One reason for this could be that the application
584 has additional per-command informations which should be included in
585 the command summary.
586 », «
587 «const struct lls_command *cmd», «Obtained from lls_cmd().»
588 », «
589 »,
590 «const char *», «Static storage, must not be freed.»,
591 «
592 The returned string is the content of the corresponding directive of
593 the suite file, with leading and trailing whitespace removed.
594 »
595 )
596
597 DECLARE_FUNCTION(
598 «lls_convert_config»,
599 «Transform the contents of a config file into an argument vector.»,
600 «
601 This function scans the given input buffer to compute an (argc,
602 argv) pair which is suitable to be fed to lls_parse(). The function
603 is config-agnostic. That is, it does not know anything about option
604 names and their type.
605
606 Arguments are separated from the option by whitespace and an optional
607 '=' character. Arguments to string options should be enclosed in double
608 quotes and must not spawn multiple lines. Newline or tab characters
609 may be embedded into the argument string with '\n' and '\t'. To embed
610 a backslash, double it. To embed a quote, prefix it with a backslash.
611 », «
612 «const char *buf», «Input buffer (content of the config file).»,
613 «size_t nbytes», «The buffer size.»,
614 «const char *subcmd», «NULL means supercommand.»,
615 «char ***result», «Argument vector is returned here.»,
616 «char **errctx», «Error context, see lls_parse().»
617 », «
618 If a subcommand is specified, only the part of the input buffer which
619 is started by a [subcmd] marker is taken into account. Conversely,
620 if a NULL pointer is passed, only the beginning part until the first
621 section marker will be considered. This allows config files to contain
622 options for the supercommand and subcommands.
623 »,
624 «int», «Length of the argument vector.»,
625 «
626 On success, the number of elements in the computed argument vector
627 is returned. Slot zero of the argument vector is initialized to a
628 dummy value while the remaining values correspond to the options and
629 arguments found in the input buffer. The argument vector should be
630 freed with lls_free_argv() when it is no longer needed.
631
632 On failure a negative error code is returned and *result is set to
633 NULL. Several types of failure are possible, including allocation
634 failure, errors from the lexer and various syntax errors.
635 »
636 )
637
638 DECLARE_FUNCTION(
639 «lls_free_argv»,
640 «Deallocate an argument vector.»,
641 «
642 lls_convert_config() dynamically allocates memory for the argument
643 and for each of its elements. This function frees this memory.
644 », «
645 «char **argv», «The argument vector to free.»
646 », «
647 It's OK to pass a NULL pointer, in which case the function does
648 nothing.
649 »,
650 «void»
651 )
652
653 DECLARE_FUNCTION(
654 «lls_check_arg_count»,
655 «Check the number of non-option arguments.»,
656 «
657 This helper verifies that the number of non-option arguments lies
658 within the specified range. Although this function is kind of trivial,
659 it can help applications to provide nice and consistent error messages.
660 », «
661 «const struct lls_parse_result *lpr», «As obtained from lls_parse().»,
662 «int min_argc», «Lower bound on the number of non-option arguments.»,
663 «int max_argc», «Upper bound on the number of non-option arguments.»,
664 «char **errctx», «Describes the range violation, only set on failure.»
665 », «
666 For the function to succeed, the number of non-option arguments (as
667 returned by lls_num_inputs()) must be greater or equal to min_argc
668 and less or equal to max_argc.
669
670 Both min_argc and max_argc may be zero (but not negative), and min_argc
671 must be less or equal to max_argc. The value INT_MAX for max_argc
672 indicates that the number of allowed non-option arguments is unbounded.
673 »,
674 «int», «Standard. The only possible error is -LLS_E_BAD_ARG_COUNT.»,
675 «
676 Examples:
677
678 min_argc = 0, max_argc = 0: no non-option argument may be given.
679
680 min_argc = 0, max_argc = INT_MAX: any number of non-option arguments OK.
681
682 min_argc = 1, max_argc = 2: either one or two non-option arguments OK.
683
684 Behaviour is undefined if min_argc or max_argc is negative, if min_argc
685 is greater than max_argc, or if lpr is invalid.
686 »
687 )
688
689 DECLARE_FUNCTION(
690 «lls_serialize_parse_result»,
691 «Create a buffer from a parse result.»,
692 «
693 This function is handy for passing the result from lls_parse() to a
694 different process.
695 », «
696 «const struct lls_parse_result *lpr», «The parse result to serialize.»,
697 «const struct lls_command *cmd», «Must point to the command used to create the parse result.»,
698 «char **result», «The serialized parse result.»,
699 «size_t *nbytes», «The size of the serialized buffer.»
700 », «
701 Depending on the initial value of the result pointer, the function
702 behaves as follows.
703
704 (a) If result is NULL, the size required to store the serialized
705 buffer is computed and returned through the nbytes argument, but no
706 serialization takes place.
707
708 (b) If result is not NULL, but *result is NULL, a suitable buffer is
709 allocated with malloc() and *result is pointed at this buffer. The
710 caller is responsible for freeing this buffer when it is no longer
711 needed.
712
713 (c) If *result is not NULL, the buffer pointed at by *result is assumed
714 be be large enough for the serialized parse result, and this buffer
715 is used to store the result.
716 »,
717 «int», «Standard.»,
718 «
719 See also: lls_deserialize_parse_result().
720 »
721 )
722
723 DECLARE_FUNCTION(
724 «lls_deserialize_parse_result»,
725 «Initialize a parse result from a buffer.»,
726 «
727 This is the counterpart to lls_serialize_parse_result().
728 », «
729 «const char *buf», «The buffer to de-serialize.»,
730 «const struct lls_command *cmd», «Must match the pointer used for serializing.»,
731 «struct lls_parse_result **lprp», «Result pointer.»
732 », «
733 The input buffer should have been obtained through an earlier call
734 to lls_serialize_parse_result().
735 »,
736 «int», «Standard.»,
737 «
738 On success all fields of lpr match the original values. After the
739 call, no fields of *lprp contain references to buf, so buf may safely
740 be freed.
741 »
742 )
743
744 DECLARE_FUNCTION(
745 «lls_merge»,
746 «Combine two parse results, creating an effective configuration.»,
747 «
748 This is useful for applications which receive options from the command
749 line and the configuration file.
750 », «
751 «const struct lls_parse_result *primary», «From command line options.»,
752 «const struct lls_parse_result *secondary», «From config file.»,
753 «const struct lls_command *cmd», «Common command for both parse results.»,
754 «struct lls_parse_result **lprp», «Effective configuration is returned here.»,
755 «char **errctx», «Error context, see lls_parse().»
756 », «
757 Merging works on a per-option basis as follows. If the multiple flag
758 is set for the option, the argument arrays of the primary and the
759 secondary parse result are concatenated and the concatenation is the
760 argument array for the merge result. It the multiple flag is not set,
761 the value of the primary parse result becomes the argument for the
762 merge result.
763
764 The two non-option argument arrays are concatenated in the same way
765 as the arguments to options with the multiple flag set.
766
767 All arguments are copied from the two input parse results. It is safe
768 to free them after the function returns. The merge result should be
769 freed with lls_parse_result() when it is no longer needed.
770 »,
771 «int», «Standard.»,
772 «
773 The only possible error is an out of memory condition. However,
774 behaviour is undefined if the primary or secondary parse result is
775 NULL, or was not obtained from the given command.
776 »
777 )
778
779 DECLARE_FUNCTION(
780 «lls_dump_parse_result»,
781 «Create contents of a configuration file from a parse result.»,
782 «
783 The subcommand marker ([subcommand]) is not included in the output.
784 », «
785 «const struct lls_parse_result *lpr», «As obtained from lls_parse() or lls_merge().»,
786 «const struct lls_command *cmd», «Subcommand or supercommand.»,
787 «bool non_default_only», «Only include option values that differ from the default.»
788 »,«
789 If non_default_only is false, options are included in the dump even
790 if they are not given in the parse result. However, flag options are
791 excluded in this case as well as options which take an argument for
792 which no default value has been defined.
793 »,
794 «char *», «Must be freed by the caller.»,
795 «
796 If no options are given, or if every option argument of the parse
797 result matches the default value of the option and non_default_only
798 is true, the function returns the empty string.
799
800 The only possible error is an out of memory condition, in which case
801 the NULL pointer is returned. Behaviour is undefined if any of the
802 pointer arguments is NULL, or if the parse result does not match the
803 given command.
804 »
805 )
806 VERBATIM_C(«#endif /* _LOPSUB_H */»)