| blob | d24d18173906d20e7c4cb6d21e81dce1f7228758 |
1 .\" Man page generated from reStructuredText.
2 .
3 .TH CTXOPT "" "" ""
4 .SH NAME
5 ctxopt \- An advanced command line options manager.
6 .
7 .nr rst2man-indent-level 0
8 .
9 .de1 rstReportMargin
10 \\$1 \\n[an-margin]
11 level \\n[rst2man-indent-level]
12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
13 -
14 \\n[rst2man-indent0]
15 \\n[rst2man-indent1]
16 \\n[rst2man-indent2]
17 ..
18 .de1 INDENT
19 .\" .rstReportMargin pre:
20 . RS \\$1
21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
22 . nr rst2man-indent-level +1
23 .\" .rstReportMargin post:
24 ..
25 .de UNINDENT
26 . RE
27 .\" indent \\n[an-margin]
28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .nr rst2man-indent-level -1
30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
32 ..
33 .SH DESCRIPTION
34 .sp
35 \fBctxopt\fP provides an advanced way to parse and evaluate complex command
36 line parameters and arguments.
37 .sp
38 Only two files \fBctxopt.h\fP and \fBctxopt.c\fP are needed to use \fBctxopt\fP
39 in your projects.
40 .SS CONCEPTS
41 .sp
42 The command line can be considered as a tree of contexts.
43 This offers the possibility of having a hierarchy of option groups.
44 .sp
45 Each option has a set of parameters which must start with a single dash
46 and may appear in the command line.
47 These parameters are not limited to a dash followed by single letter.
48 In what follows, I will consider for simplicity that these are the options
49 which are visible in the command line and not one of their parameters.
50 .sp
51 Unless explicitly stated, the options are processed in the same order
52 as they appear in the command line, from left to right.
53 .sp
54 Any option may have the ability to modify the current context.
55 If such an option is seen in the command line, then the next option will
56 be looked for in this new context.
57 .sp
58 Initially the default context is the first created one in the program.
59 .sp
60 Exiting a context can be explicit, see below, or implicit if the current
61 option is not supported in this context.
62 The previous context in the hierarchy then becomes the current context
63 if it is not already the highest one.
64 .sp
65 An option which is unknown in the current context will be automatically
66 reevaluated in the previous one in the hierarchy.
67 If there is no such context, then a fatal error occurs.
68 .sp
69 A context can be explicitly delimited by a pair of symbols \fB{\fP and
70 \fB}\fP\&.
71 The symbol \fB{\fP car appear just before or after the option responsible
72 of the context change.
73 .sp
74 The symbol \fB}\fP forces the end of a context.
75 .sp
76 The presence of \fB{\fP and \fB}\fP is purely optional and rarely necessary
77 but can help readability.
78 .SS FUNCTIONS
79 .sp
80 The API consists in the following functions:
81 .INDENT 0.0
82 .IP \(bu 2
83 \fBvoid ctxopt_init(char *\fP \fIprog_name\fP\fB);\fP
84 .sp
85 This function initializes the internal structures uses by \fBctxopt\fP\&.
86 It is mandatory and must me called first.
87 .sp
88 Its only argument \fIprog_name\fP is typically the content of \fBargv[0]\fP
89 which nearly always contains the name of the program.
90 .sp
91 \fIprog_name\fP is used by the error system.
92 .UNINDENT
93 .nf
95 .fi
96 .sp
97 .INDENT 0.0
98 .IP \(bu 2
99 \fBvoid ctxopt_new_ctx(char *\fP \fIname\fP\fB, char *\fP \fIopts_specs\fP\fB);\fP
100 .sp
101 The next thing to do after having called \fBctxopt_new_ctx\fP is to
102 define the contexts and its associated options.
103 .sp
104 Using this function, you can name the new context and its authorized
105 options and determine their main characteristics with a syntax easy
106 to understand.
107 If they already exist in another context, then they must have the same
108 signature (described below) as in their previous appearance.
109 .sp
110 \fIname\fP is the name of the new context and \fIopts_specs\fP must contain a
111 description of the options allowed in this context.
112 .sp
113 \fIopts_specs\fP is a string containing various components separated by
114 spaces according to the syntax below:
115 .INDENT 2.0
116 .TP
117 .B opt
118 A mandatory option named opt without parameter usable only one type in
119 the context
120 .TP
121 .B opt1 opt2
122 Two mandatory option named \fBopt1\fP and \fBopt2\fP without argument.
123 .TP
124 .B opt...
125 Same as above but can appear multiple time in the context.
126 .TP
127 .B [opt...]
128 Same as above but the option is optional
129 .TP
130 .B opt1 [opt2...]
131 One mandatory and one optional option named \fBopt1\fP and \fBopt2\fP
132 without argument. \fBopt2\fP can appear multiple times in the context.
133 .TP
134 .B opt #
135 One mandatory option named \fBopt*\fP taking one mandatory argument.
136 .TP
137 .B opt #tag
138 One mandatory option named \fBopt\fP taking one mandatory argument.
139 \fBtag\fP is ignored but can be used to improve the readability.
140 .TP
141 .B opt [#]
142 One mandatory option named \fBopt\fP taking one optional argument.
143 .TP
144 .B opt #...
145 One mandatory option named \fBopt\fP taking one or more mandatory
146 arguments.
147 .TP
148 .B opt>ctx... [#<value>]
149 The mandatory multiple option named \fBopt\fP will switch to the
150 context named \fBcxt\fP which will become the new current context.
151 .sp
152 It takes an optional argument with a tag named \fB<value>\fP\&.
153 .TP
154 .B [opt... [#...]]
155 One optional option named \fBopt\fP taking multiple optional
156 arguments.
157 .TP
158 .B opt...<3 #...=3
159 The mandatory option \fBopt\fP is restricted to only appear one or
160 two times in the context.
161 The number of its mandatory arguments must be exactly three.
162 .UNINDENT
163 .sp
164 The multiplicity or not of the options and argument, their mandatory or
165 optional characteristics constitutes their signatures.s
166 .sp
167 As said above, an option can appear in more than one context but must
168 have the same signature.
169 .sp
170 Example:
171 .INDENT 2.0
172 .INDENT 3.5
173 .sp
174 .nf
175 .ft C
176 ctxopt_new_ctx("context1",
177 "[opt1>context2...] #arg1... [opt3]");
179 ctxopt_new_ctx("context2",
180 "[opt2 [#arg2]] [opt3]");
181 .ft P
182 .fi
183 .UNINDENT
184 .UNINDENT
185 .sp
186 In the previous example, three options \fBopt1\fP, \fBopt2\fP and \fBopt3\fP
187 are defined.
188 .INDENT 2.0
189 .INDENT 3.5
190 .INDENT 0.0
191 .TP
192 .B opt1
193 is mandatory and can appear more than one time and take multiple
194 mandatory arguments.
195 .TP
196 .B opt2
197 is optional and take an optional argument.
198 .TP
199 .B opt3
200 is optional and take no argument.
201 Note that \fBopt3\fP is legal in both contexts.
202 .UNINDENT
203 .nf
205 .fi
206 .sp
207 .sp
208 \fBopt2\fP, if present in the command line, will be evaluated in the
209 context \fBcontext2\fP\&.
210 Note that, in this example, the \fBcontext2\fP can only be entered if
211 \fBopt1\fP has previously been seen in the command line.
212 Hence, \fBopt2\fP is only legal if \fBopt1\fP is present first.
213 .sp
214 \fBopt3\fP does not have this limitation.
215 In fact, as \fBopt3\fP is optional in \fBcontext2\fP and if its action
216 function is not interested in the name of the current context,
217 then it could have been omitted from the second setting thanks to
218 the backtracking: an option which is illegal in a context is retried
219 in the previous context in the hierarchy.
220 .UNINDENT
221 .UNINDENT
222 .UNINDENT
223 .nf
225 .fi
226 .sp
227 .INDENT 0.0
228 .IP \(bu 2
229 \fBvoid ctxopt_ctx_disp_usage(char *\fP \fIctx_name\fP\fB, usage_behaviour\fP \fIaction\fP\fB);\fP
230 .sp
231 This function builds and prints an usage help text for the
232 specific context \fIctx_name\fP\&.
233 The symbols used in this text are the same as those used when defining
234 options in \fBctxopt_new_ctx\fP\&.
235 .sp
236 The parameter \fIaction\fP can take the following values:
237 .INDENT 2.0
238 .TP
239 .B continue_after
240 The program is not stopped when this function returns.
241 .TP
242 .B exit_after
243 The program is stopped with a non zero return code (typically 1)
244 when this function returns.
245 .UNINDENT
246 .sp
247 The usage text is followed by a legend explaining the symbols meanings.
248 This function is useful when associated with a \fBhelp\fP or \fBusage\fP
249 option.
250 .UNINDENT
251 .nf
253 .fi
254 .sp
255 .INDENT 0.0
256 .IP \(bu 2
257 \fBvoid ctxopt_disp_usage(usage_behaviour\fP \fIaction\fP\fB);\fP
258 .sp
259 This function is similar to the preceding one but displays the usage
260 help text for all the defined contexts.
261 It is useful when associated with a general \fBhelp\fP or \fBusage\fP
262 option.
263 .sp
264 The parameter \fIaction\fP can take the following values:
265 .INDENT 2.0
266 .TP
267 .B continue_after
268 The program is not stopped when this function returns.
269 .TP
270 .B exit_after
271 The program is stopped with a non zero return code (typically 1)
272 when this function returns.
273 .UNINDENT
274 .UNINDENT
275 .nf
277 .fi
278 .sp
279 .INDENT 0.0
280 .IP \(bu 2
281 \fBvoid ctxopt_add_global_settings(settings\fP \fIs\fP\fB,\fP \fI\&...\fP\fB);\fP
282 .sp
283 This function allows to set general \fBctxopt\fP settings.
284 As for now, the only possible setting for \fIs\fP is \fBerror_functions\fP\&.
285 .sp
286 This setting tells \fBctxopt_add_global_settings\fP to use the rest of
287 its arguments in order to replace the built\-in error functions with
288 custom ones.
289 .sp
290 When the value of the first parameter is \fBerror_functions\fP,
291 then the second one must be one of the following constants:
292 .INDENT 2.0
293 .TP
294 .B CTXOPTMISPAR
295 A mandatory parameter is missing.
296 .TP
297 .B CTXOPTUNKPAR
298 A given parameter is unknown in the current context.
299 .TP
300 .B CTXOPTDUPOPT
301 An option has been seen more than once but has not been declared as
302 multiple in the context.
303 .TP
304 .B CTXOPTINCOPT
305 An option is incompatible with an option already given in the context.
306 .TP
307 .B CTXOPTMISARG
308 A mandatory argument is missing.
309 .TP
310 .B CTXOPTCNTEOPT, CTXOPTCNTLOPT and CTXOPTCNTGOPT
311 The number of occurrences is not equal, lower or greater than a
312 given value.
313 .TP
314 .B CTXOPTCNTEARG, CTXOPTCNTLARG and CTXOPTCNTGARG
315 The number of arguments of an option is not equal, lower or greater
316 than a given value.
317 .UNINDENT
318 .sp
319 and the third parameter is a function pointer with the following
320 prototype:
321 .INDENT 2.0
322 .INDENT 3.5
323 .sp
324 .nf
325 .ft C
326 void (*) (errors err, state_t * state);
327 .ft P
328 .fi
329 .UNINDENT
330 .UNINDENT
331 .sp
332 \fIstate\fP will point to the publicly available analysis state structure.
333 This structure contains a snapshot of variables related to the command
334 line analysis so far.
335 They and can be used to give the user clues about errors.
336 .sp
337 This structure available in \fBctxopt.h\fP is:
338 .INDENT 2.0
339 .INDENT 3.5
340 .sp
341 .nf
342 .ft C
343 typedef struct
344 {
345 char * prog_name; /* base name of the program name. */
346 char * ctx_name; /* current context name. */
347 char * ctx_par_name; /* parameter which led to this context. */
348 char * opt_name; /* current option name. */
349 char * opt_params; /* all parameters of the current option. */
350 int opts_count; /* limit of the number of occurrences of *
351 | the current option. */
352 int opt_args_count; /* limit of the number of parameters of *
353 | the current option. */
354 char * pre_opt_par_name; /* parameter just before the current one. */
355 char * cur_opt_par_name; /* current parameter. */
356 } state_t;
357 .ft P
358 .fi
359 .UNINDENT
360 .UNINDENT
361 .sp
362 All these pointers can be equal to the \fBNULL\fP pointer.
363 .sp
364 Example:
365 .INDENT 2.0
366 .INDENT 3.5
367 .sp
368 .nf
369 .ft C
370 ctxopt_add_global_settings(error_functions, CTXOPTMISPAR, error);
371 .ft P
372 .fi
373 .UNINDENT
374 .UNINDENT
375 .UNINDENT
376 .nf
378 .fi
379 .sp
380 .INDENT 0.0
381 .IP \(bu 2
382 \fBvoid ctxopt_add_ctx_settings(settings\fP \fIs\fP\fB,\fP \fI\&...\fP\fB);\fP
383 .sp
384 This function manages some settings for a given context.
385 Its first parameter \fIs\fP determines the setting and the signification
386 of the remaining arguments.
387 .sp
388 Its possible values are:
389 .INDENT 2.0
390 .TP
391 .B incompatibilities:
392 This setting allows to declare a set of options incompatible with
393 each other.
394 .sp
395 In this case the second argument must be a context name and the
396 third argument must be a string containing option names separated
397 by a space.
398 .sp
399 Example of \fBincompatibilities\fP setting:
400 .INDENT 7.0
401 .INDENT 3.5
402 .sp
403 .nf
404 .ft C
405 void ctxopt_add_ctx_settings(incompatibilities,
406 context1,
407 "opt1 opt2 opt3");
408 .ft P
409 .fi
410 .UNINDENT
411 .UNINDENT
412 .sp
413 The three options named \fBopt1\fP, \fBopt2\fP and \fBopt3\fP will be
414 marked as mutually incompatibles in each instance of the context
415 \fBcontext1\fP\&.
416 .TP
417 .B actions:
418 This setting allows to associate a function to the context.
419 .sp
420 The second argument (called \fIf\fP below) will be called as soon as the
421 context is entered or exited during the evaluation phase.
422 .sp
423 The next parameters must be pointers to arbitrary data which may
424 be used by \fIf\fP\&.
425 .sp
426 In this setting, the last parameter must be \fBNULL\fP\&.
427 .sp
428 \fIf\fP must have the following prototype:
429 .INDENT 7.0
430 .INDENT 3.5
431 .sp
432 .nf
433 .ft C
434 int (*) (char * name1, /* Context name */
435 direction status, /* entering or exiting */
436 char * name2, /* previous or next context */
437 int nb_data, /* Number of data */
438 void ** data /* Data */);
439 .ft P
440 .fi
441 .UNINDENT
442 .UNINDENT
443 .sp
444 This function \fIf\fP will be called when entering \fBAND\fP exiting
445 the context.
446 Its arguments will then be set to:
447 .INDENT 7.0
448 .TP
449 .B \fIname1\fP
450 the name of the context.
451 .TP
452 .B \fIstatus\fP
453 will be \fBentering\fP when entering the context and \fBexiting\fP
454 when exiting the context.
455 .TP
456 .B \fIname2\fP
457 according to the content of \fIstatus\fP, the name of the context we
458 are coming from or the name of the context we are returning to.
459 .sp
460 \fIname2\fP can be \fBNULL\fP if we are entering in the main context or
461 are leaving it.
462 .TP
463 .B \fInb_data\fP
464 The number of data pointers passed to the \fBctxopt_add_ctx_settings\fP
465 function after the \fIs\fP parameter.
466 .TP
467 .B \fIdata\fP
468 The data pointers passed to the \fBctxopt_add_ctx_settings\fP function
469 after the \fIs\fP parameter and arranged in an array of \fInb_data\fP
470 .UNINDENT
471 .sp
472 Example of \fBactions\fP setting:
473 .INDENT 7.0
474 .INDENT 3.5
475 .sp
476 .nf
477 .ft C
478 void ctxopt_add_ctx_settings(actions,
479 "context1",
480 action,
481 &data_1, &data_2, &data_3,
482 NULL);
483 .ft P
484 .fi
485 .UNINDENT
486 .UNINDENT
487 .sp
488 This function call registers the \fBaction\fP function to the context
489 named \fBcontext1\fP\&.
490 .sp
491 The action function will be called \fBafter\fP entering to and
492 \fBbefore\fP exiting from each instance of the context
493 named \fBcontext1\fP\&.
494 .sp
495 The optional \fIdata_X\fP pointers will be passed to \fBaction\fP through
496 its data pointer to allow it to manipulate them if needed.
497 The count of these pointers (3 here) will also be passed to action
498 through its \fInb_data\fP parameter.
499 .sp
500 The ending \fBNULL\fP is mandatory.
501 .UNINDENT
502 .UNINDENT
503 .nf
505 .fi
506 .sp
507 .INDENT 0.0
508 .IP \(bu 2
509 \fBvoid ctxopt_add_opt_settings(settings\fP \fIs\fP\fB, char *\fP \fIopt\fP\fB,\fP \fI\&...\fP\fB);\fP
510 .sp
511 This function manages some settings for an option whose name is given in
512 \fIopt\fP\&.
513 .sp
514 The first parameter \fIs\fP determines the exact setting and the
515 signification of the remaining arguments.
516 Its possible values are:
517 .INDENT 2.0
518 .TP
519 .B parameters
520 This setting allows to associate command line parameters with \fIopt\fP\&.
521 The set of parameters must be given in the third argument as a string
522 containing words separated by blanks.
523 .sp
524 Each appearance of one of these parameters in the command line will
525 trigger the action associated with the named option.
526 .sp
527 Each of these words must start with one and exactly one dash.
528 .sp
529 Example of \fBparameters\fP setting:
530 .INDENT 7.0
531 .INDENT 3.5
532 .sp
533 .nf
534 .ft C
535 ctxopt_add_opt_settings(parameters,
536 "opt1",
537 "\-p \-parm \-p1");
538 .ft P
539 .fi
540 .UNINDENT
541 .UNINDENT
542 .sp
543 In this example, \fBopt1\fP is the name of a previously defined option and
544 \fB\-p\fP, \fB\-parm\fP and \fB\-p1\fP will be three valid command line
545 parameters for the option \fBopt1\fP\&.
546 .TP
547 .B actions
548 This setting allows to associate a function to this options.
549 As said above, this function will be called each time the option will be
550 recognized when evaluating the command line.
551 .sp
552 The function pointer must be given as the third argument.
553 .sp
554 Following the function pointer, it is possible to add a bunch of
555 other parameters which must be pointers to some pre\-allocated arbitrary
556 data.
557 .sp
558 These pointers will be passed to the function when called.
559 The last parameter must be \fBNULL\fP to end the sequence.
560 .sp
561 The function needs to be given as the third argument and must
562 match the following prototype:
563 .INDENT 7.0
564 .INDENT 3.5
565 .sp
566 .nf
567 .ft C
568 void (*) (char * ctx_name, /* Context name */
569 char * opt_name, /* Option name */
570 char * param, /* Parameter name */
571 int nb_values, /* Number of arguments */
572 char ** values, /* Arguments */
573 int nb_opt_data, /* Number of option data passed */
574 void ** opt_data, /* Array of option data passed */
575 int nb_ctx_data, /* Number of context data passed */
576 void ** ctx_data /* Array of context data passed */)
577 .ft P
578 .fi
579 .UNINDENT
580 .UNINDENT
581 .INDENT 7.0
582 .TP
583 .B \fIctx_name\fP
584 is the name of the current context.
585 .TP
586 .B \fIopt_name\fP
587 is the name of the option.
588 .TP
589 .B \fIparam\fP
590 is the name of the parameter that triggered the option \fIopt_name\fP\&.
591 .TP
592 .B \fInb_values\fP
593 is the number of arguments immediately following this option in
594 the command line.
595 .TP
596 .B \fIvalues\fP
597 is an array of stings containing the arguments following this
598 option in the command line.
599 .TP
600 .B \fInb_opt_data\fP
601 is the number of data pointers which were given after the third
602 arguments of \fBctxopt_add_opt_settings\fP\&.
603 .TP
604 .B \fIopt_data\fP
605 The data pointers passed after the third arguments of
606 \fBctxopt_add_opt_settings\fP and reorganized as an array of
607 \fInb_opt_data\fP elements.
608 .sp
609 The aim is to be able to consult/alter options specific data.
610 .TP
611 .B \fInb_ctx_data\fP
612 Same as \fInb_opt_data\fP but referencing to the number of data
613 pointers given to \fBctxopt_add_ctx_settings\fP for the current
614 context after its third argument.
615 .TP
616 .B \fIctx_data\fP
617 are the data pointers given to \fBctxopt_add_ctx_settings\fP for the
618 current context after its third argument.
619 .sp
620 The aim is to be able to consult/alter contexts specific data.
621 .UNINDENT
622 .sp
623 Example of \fBactions\fP setting:
624 .INDENT 7.0
625 .INDENT 3.5
626 .sp
627 .nf
628 .ft C
629 void action(char * ctx_name,
630 char * opt_name,
631 char * param,
632 int nb_values, char ** values,
633 int nb_opt_data, void ** opt_data,
634 int nb_ctx_data, void ** ctx_data)
635 {
636 \&...
637 }
639 \&...
641 void ctxopt_add_opt_settings(actions, "opt1", action,
642 &data_1, &data_2, &data_3,
643 NULL);
644 .ft P
645 .fi
646 .UNINDENT
647 .UNINDENT
648 .sp
649 This example associates the function \fIaction\fP to the option \fBopt1\fP\&.
650 .sp
651 Here, the \fIdata_*\fP pointers will be accessible to the function
652 \fIaction\fP when called through its argument \fIopt_data\fP and their number
653 (3 here) through its argument \fInb_opt_data\fP as mentioned above.
654 .sp
655 \fIaction\fP will also have access to the current context data in the
656 same way through its arguments \fIctx_data\fP and \fInb_ctx_data\fP\&.
657 .sp
658 The \fIaction\fP argument \fIparam\fP will receive the value of the specific
659 parameter which triggered it \- one of the parameters registered with
660 \fBctxopt_add_opt_settings\fP\&.
661 .TP
662 .B constraints
663 This setting registers a function whose responsibility is to validate
664 that the arguments of the option respect some constraints.
665 .sp
666 To do that the third argument must be a function pointer and the fourth
667 argument must be some arbitrary parameter to this function needed
668 to validate the constraint.
669 .sp
670 The constraint function must match the following prototype:
671 .INDENT 7.0
672 .INDENT 3.5
673 .sp
674 .nf
675 .ft C
676 int (*) (int nb_args, char ** args, char * value);
677 .ft P
678 .fi
679 .UNINDENT
680 .UNINDENT
681 .sp
682 Where:
683 .INDENT 7.0
684 .INDENT 3.5
685 .INDENT 0.0
686 .TP
687 .B \fInb_args\fP
688 is the number which will be set to the number of arguments fol\-
689 lowing the command line parameter.
690 .TP
691 .B \fIargs\fP
692 is an array of nb_args strings containing theses arguments.
693 .TP
694 .B \fIvalue\fP
695 is an arbitrary string containing the constraints which must be
696 respected by args.
697 .UNINDENT
698 .UNINDENT
699 .UNINDENT
700 .sp
701 Three constraint functions are built\-in and are described below.
702 They give examples on how to build them.
703 .sp
704 Example of constraint function using the built\-it regular expression
705 constraint checker function:
706 .INDENT 7.0
707 .INDENT 3.5
708 .sp
709 .nf
710 .ft C
711 ctxopt_add_opt_settings(constraints,
712 "opt1",
713 ctxopt_re_constraint,
714 "[^:]+:.+");
715 .ft P
716 .fi
717 .UNINDENT
718 .UNINDENT
719 .sp
720 In this example all the arguments of the option \fBopt1\fP must match
721 the extended regular expression:
722 .INDENT 7.0
723 .INDENT 3.5
724 .sp
725 .nf
726 .ft C
727 [^:]+:.+
728 .ft P
729 .fi
730 .UNINDENT
731 .UNINDENT
732 .sp
733 See below for details about the function \fBctxopt_re_constraint\fP\&.
734 .UNINDENT
735 .UNINDENT
736 .nf
738 .fi
739 .sp
740 .INDENT 0.0
741 .IP \(bu 2
742 \fBint ctxopt_format_constraint(int\fP \fInb_args\fP\fB, char **\fP \fIargs\fP\fB, char *\fP \fIvalue\fP\fB);\fP
743 .sp
744 This pre\-defined constraint function checks whether the arguments
745 in \fIargs\fP respect a C printf format given in value, \fI%2d\fP by e.g.
746 It returns 1 if the checking is successful and 0 if not.
747 .UNINDENT
748 .nf
750 .fi
751 .sp
752 .INDENT 0.0
753 .IP \(bu 2
754 \fBint ctxopt_re_constraint(int\fP \fInb_args\fP\fB, char **\fP \fIargs\fP\fB, char *\fP \fIvalue\fP\fB);\fP
755 .sp
756 Another pre\-defined constraint function which checks if the arguments
757 of an option respects the extended regular expression given in \fIvalue\fP\&.
758 .sp
759 It returns 1 if the arguments respects the constraint and 0 if this
760 is not the case.
761 .UNINDENT
762 .nf
764 .fi
765 .sp
766 .INDENT 0.0
767 .IP \(bu 2
768 \fBint ctxopt_range_constraint(int\fP \fInb_args\fP\fB, char **\fP \fIargs\fP\fB, char *\fP \fIvalue\fP\fB);\fP
769 .sp
770 Yet another pre\-defined constraint function. This one checks if the
771 arguments of an option are in in a specified ranges.
772 .sp
773 \fIvalue\fP must contain a string made of a maximum of 2 long integers
774 separated by spaces.
775 .sp
776 The first or the second of these numbers can be replaced with the
777 character \(aq\fI\&.\fP\(aq. In this case only the minimum or maximum is checked
778 and the \(aq\fI\&.\fP\(aq equals to plus or minus infinity depending of this
779 place in the string.
780 .sp
781 It returns 1 if the arguments respects the constraint and 0 if this
782 is not the case.
783 .UNINDENT
784 .nf
786 .fi
787 .sp
788 .INDENT 0.0
789 .IP \(bu 2
790 \fBvoid ctxopt_analyze(int\fP \fInb_words\fP\fB, char **\fP \fIwords\fP\fB, int *\fP \fIrem_count\fP\fB, char ***\fP \fIrem_args\fP\fB);\fP
791 .sp
792 This function processes the registered contexts instances tree, detects
793 errors and possibly reorganizes the options order according
794 to given priorities.
795 .sp
796 The first two arguments are similar to the \fIargc\fP and \fIargv\fP arguments
797 of the main function but without counting \fIargv[0]\fP\&.
798 Therefore, in many cases, \fInb_words\fP will have the value of \fIargc\-1\fP
799 and \fIwords\fP will have the value of \fIargv+1\fP\&.
800 .sp
801 The last two will receive the number of remaining (non analyzed)
802 command line words and the array of these remaining words.
803 Remaining words can be words appearing after \fB\-\-\fP per example.
804 .sp
805 All errors are fatal and terminates the program with a return code
806 greater then 0.
807 .sp
808 Example:
809 .INDENT 2.0
810 .INDENT 3.5
811 .sp
812 .nf
813 .ft C
814 int res_argc;
815 char ** res_argv;
816 \&...
817 ctxopt_analyze(argc\-1, argv+1, &res_argc, &res_argv);
818 .ft P
819 .fi
820 .UNINDENT
821 .UNINDENT
822 .UNINDENT
823 .nf
825 .fi
826 .sp
827 .INDENT 0.0
828 .IP \(bu 2
829 \fBvoid ctxopt_evaluate(void);\fP
830 .sp
831 This function walks through the tree of context instances previously
832 built by \fBctxopt_analyze\fP and launches the action attached to
833 each options, if any, one after the other.
834 .UNINDENT
835 .\" Generated by docutils manpage writer.
836 .