| blob | 4fb190a56f1f8470beedb753d5cd4d98ef4cc796 |
1 .\" Man page generated from reStructuredText.
2 .
3 .TH CTXOPT 3 "2020" "" ""
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 Note that \fIf\fP will NOT be called if the context is empty
424 (does not contain any option).
425 .sp
426 The next parameters must be pointers to arbitrary data which may
427 be used by \fIf\fP\&.
428 .sp
429 In this setting, the last parameter must be \fBNULL\fP\&.
430 .sp
431 \fIf\fP must have the following prototype:
432 .INDENT 7.0
433 .INDENT 3.5
434 .sp
435 .nf
436 .ft C
437 int (*) (char * name1, /* Context name */
438 direction status, /* entering or exiting */
439 char * name2, /* previous or next context */
440 int nb_data, /* Number of data */
441 void ** data /* Data */);
442 .ft P
443 .fi
444 .UNINDENT
445 .UNINDENT
446 .sp
447 This function \fIf\fP will be called when entering \fBAND\fP exiting
448 the context.
449 Its arguments will then be set to:
450 .INDENT 7.0
451 .TP
452 .B \fIname1\fP
453 the name of the context.
454 .TP
455 .B \fIstatus\fP
456 will be \fBentering\fP when entering the context and \fBexiting\fP
457 when exiting the context.
458 .TP
459 .B \fIname2\fP
460 according to the content of \fIstatus\fP, the name of the context we
461 are coming from or the name of the context we are returning to.
462 .sp
463 \fIname2\fP can be \fBNULL\fP if we are entering in the main context or
464 are leaving it.
465 .TP
466 .B \fInb_data\fP
467 The number of data pointers passed to the \fBctxopt_add_ctx_settings\fP
468 function after the \fIs\fP parameter.
469 .TP
470 .B \fIdata\fP
471 The data pointers passed to the \fBctxopt_add_ctx_settings\fP function
472 after the \fIs\fP parameter and arranged in an array of \fInb_data\fP
473 .UNINDENT
474 .sp
475 Example of \fBactions\fP setting:
476 .INDENT 7.0
477 .INDENT 3.5
478 .sp
479 .nf
480 .ft C
481 void ctxopt_add_ctx_settings(actions,
482 "context1",
483 action,
484 &data_1, &data_2, &data_3,
485 NULL);
486 .ft P
487 .fi
488 .UNINDENT
489 .UNINDENT
490 .sp
491 This function call registers the \fBaction\fP function to the context
492 named \fBcontext1\fP\&.
493 .sp
494 The action function will be called \fBafter\fP entering to and
495 \fBbefore\fP exiting from each instance of the context
496 named \fBcontext1\fP\&.
497 .sp
498 The optional \fIdata_X\fP pointers will be passed to \fBaction\fP through
499 its data pointer to allow it to manipulate them if needed.
500 The count of these pointers (3 here) will also be passed to action
501 through its \fInb_data\fP parameter.
502 .sp
503 The ending \fBNULL\fP is mandatory.
504 .UNINDENT
505 .UNINDENT
506 .nf
508 .fi
509 .sp
510 .INDENT 0.0
511 .IP \(bu 2
512 \fBvoid ctxopt_add_opt_settings(settings\fP \fIs\fP\fB, char *\fP \fIopt\fP\fB,\fP \fI\&...\fP\fB);\fP
513 .sp
514 This function manages some settings for an option whose name is given in
515 \fIopt\fP\&.
516 .sp
517 The first parameter \fIs\fP determines the exact setting and the
518 signification of the remaining arguments.
519 Its possible values are:
520 .INDENT 2.0
521 .TP
522 .B parameters
523 This setting allows to associate command line parameters with \fIopt\fP\&.
524 The set of parameters must be given in the third argument as a string
525 containing words separated by blanks.
526 .sp
527 Each appearance of one of these parameters in the command line will
528 trigger the action associated with the named option.
529 .sp
530 Each of these words must start with one and exactly one dash.
531 .sp
532 Example of \fBparameters\fP setting:
533 .INDENT 7.0
534 .INDENT 3.5
535 .sp
536 .nf
537 .ft C
538 ctxopt_add_opt_settings(parameters,
539 "opt1",
540 "\-p \-parm \-p1");
541 .ft P
542 .fi
543 .UNINDENT
544 .UNINDENT
545 .sp
546 In this example, \fBopt1\fP is the name of a previously defined option and
547 \fB\-p\fP, \fB\-parm\fP and \fB\-p1\fP will be three valid command line
548 parameters for the option \fBopt1\fP\&.
549 .TP
550 .B actions
551 This setting allows to associate a function to this options.
552 As said above, this function will be called each time the option will be
553 recognized when evaluating the command line.
554 .sp
555 The function pointer must be given as the third argument.
556 .sp
557 Following the function pointer, it is possible to add a bunch of
558 other parameters which must be pointers to some pre\-allocated arbitrary
559 data.
560 .sp
561 These pointers will be passed to the function when called.
562 The last parameter must be \fBNULL\fP to end the sequence.
563 .sp
564 The function needs to be given as the third argument and must
565 match the following prototype:
566 .INDENT 7.0
567 .INDENT 3.5
568 .sp
569 .nf
570 .ft C
571 void (*) (char * ctx_name, /* Context name */
572 char * opt_name, /* Option name */
573 char * param, /* Parameter name */
574 int nb_values, /* Number of arguments */
575 char ** values, /* Arguments */
576 int nb_opt_data, /* Number of option data passed */
577 void ** opt_data, /* Array of option data passed */
578 int nb_ctx_data, /* Number of context data passed */
579 void ** ctx_data /* Array of context data passed */)
580 .ft P
581 .fi
582 .UNINDENT
583 .UNINDENT
584 .INDENT 7.0
585 .TP
586 .B \fIctx_name\fP
587 is the name of the current context.
588 .TP
589 .B \fIopt_name\fP
590 is the name of the option.
591 .TP
592 .B \fIparam\fP
593 is the name of the parameter that triggered the option \fIopt_name\fP\&.
594 .TP
595 .B \fInb_values\fP
596 is the number of arguments immediately following this option in
597 the command line.
598 .TP
599 .B \fIvalues\fP
600 is an array of stings containing the arguments following this
601 option in the command line.
602 .TP
603 .B \fInb_opt_data\fP
604 is the number of data pointers which were given after the third
605 arguments of \fBctxopt_add_opt_settings\fP\&.
606 .TP
607 .B \fIopt_data\fP
608 The data pointers passed after the third arguments of
609 \fBctxopt_add_opt_settings\fP and reorganized as an array of
610 \fInb_opt_data\fP elements.
611 .sp
612 The aim is to be able to consult/alter options specific data.
613 .TP
614 .B \fInb_ctx_data\fP
615 Same as \fInb_opt_data\fP but referencing to the number of data
616 pointers given to \fBctxopt_add_ctx_settings\fP for the current
617 context after its third argument.
618 .TP
619 .B \fIctx_data\fP
620 are the data pointers given to \fBctxopt_add_ctx_settings\fP for the
621 current context after its third argument.
622 .sp
623 The aim is to be able to consult/alter contexts specific data.
624 .UNINDENT
625 .sp
626 Example of \fBactions\fP setting:
627 .INDENT 7.0
628 .INDENT 3.5
629 .sp
630 .nf
631 .ft C
632 void action(char * ctx_name,
633 char * opt_name,
634 char * param,
635 int nb_values, char ** values,
636 int nb_opt_data, void ** opt_data,
637 int nb_ctx_data, void ** ctx_data)
638 {
639 \&...
640 }
642 \&...
644 void ctxopt_add_opt_settings(actions, "opt1", action,
645 &data_1, &data_2, &data_3,
646 NULL);
647 .ft P
648 .fi
649 .UNINDENT
650 .UNINDENT
651 .sp
652 This example associates the function \fIaction\fP to the option \fBopt1\fP\&.
653 .sp
654 Here, the \fIdata_*\fP pointers will be accessible to the function
655 \fIaction\fP when called through its argument \fIopt_data\fP and their number
656 (3 here) through its argument \fInb_opt_data\fP as mentioned above.
657 .sp
658 \fIaction\fP will also have access to the current context data in the
659 same way through its arguments \fIctx_data\fP and \fInb_ctx_data\fP\&.
660 .sp
661 The \fIaction\fP argument \fIparam\fP will receive the value of the specific
662 parameter which triggered it \- one of the parameters registered with
663 \fBctxopt_add_opt_settings\fP\&.
664 .TP
665 .B constraints
666 This setting registers a function whose responsibility is to validate
667 that the arguments of the option respect some constraints.
668 .sp
669 To do that the third argument must be a function pointer and the fourth
670 argument must be some arbitrary parameter to this function needed
671 to validate the constraint.
672 .sp
673 The constraint function must match the following prototype:
674 .INDENT 7.0
675 .INDENT 3.5
676 .sp
677 .nf
678 .ft C
679 int (*) (int nb_args, char ** args, char * value, char * parameter);
680 .ft P
681 .fi
682 .UNINDENT
683 .UNINDENT
684 .sp
685 Where:
686 .INDENT 7.0
687 .INDENT 3.5
688 .INDENT 0.0
689 .TP
690 .B \fInb_args\fP
691 is the number which will be set to the number of arguments fol\-
692 lowing the command line parameter.
693 .TP
694 .B \fIargs\fP
695 is an array of nb_args strings containing theses arguments.
696 .TP
697 .B \fIvalue\fP
698 is an arbitrary string containing the constraints which must be
699 respected by args.
700 .TP
701 .B \fIparameter\fP
702 is the parameter of which \fIvalue\fP is an argument.
703 .UNINDENT
704 .UNINDENT
705 .UNINDENT
706 .sp
707 Three constraint functions are built\-in and are described below.
708 They give examples on how to build them.
709 .sp
710 Example of constraint function using the built\-it regular expression
711 constraint checker function:
712 .INDENT 7.0
713 .INDENT 3.5
714 .sp
715 .nf
716 .ft C
717 ctxopt_add_opt_settings(constraints,
718 "opt1",
719 ctxopt_re_constraint,
720 "[^:]+:.+");
721 .ft P
722 .fi
723 .UNINDENT
724 .UNINDENT
725 .sp
726 In this example all the arguments of the option \fBopt1\fP must match
727 the extended regular expression:
728 .INDENT 7.0
729 .INDENT 3.5
730 .sp
731 .nf
732 .ft C
733 [^:]+:.+
734 .ft P
735 .fi
736 .UNINDENT
737 .UNINDENT
738 .sp
739 See below for details about the function \fBctxopt_re_constraint\fP\&.
740 .UNINDENT
741 .UNINDENT
742 .nf
744 .fi
745 .sp
746 .INDENT 0.0
747 .IP \(bu 2
748 \fBint ctxopt_format_constraint(int\fP \fInb_args\fP\fB, char **\fP \fIargs\fP\fB, char *\fP \fIvalue\fP\fB, char *\fP \fIparameter\fP\fB);\fP
749 .sp
750 This pre\-defined constraint function checks whether the arguments
751 in \fIargs\fP respect a C printf format given in value, \fI%2d\fP by e.g.
752 It returns 1 if the checking is successful and 0 if not.
753 .UNINDENT
754 .nf
756 .fi
757 .sp
758 .INDENT 0.0
759 .IP \(bu 2
760 \fBint ctxopt_re_constraint(int\fP \fInb_args\fP\fB, char **\fP \fIargs\fP\fB, char *\fP \fIvalue\fP\fB, char *\fP \fIparameter\fP\fB);\fP
761 .sp
762 Another pre\-defined constraint function which checks if the arguments
763 of an option respects the extended regular expression given in \fIvalue\fP\&.
764 .sp
765 It returns 1 if the arguments respects the constraint and 0 if this
766 is not the case.
767 .UNINDENT
768 .nf
770 .fi
771 .sp
772 .INDENT 0.0
773 .IP \(bu 2
774 \fBint ctxopt_range_constraint(int\fP \fInb_args\fP\fB, char **\fP \fIargs\fP\fB, char *\fP \fIvalue\fP\fB, char *\fP \fIparameter\fP\fB);\fP
775 .sp
776 Yet another pre\-defined constraint function. This one checks if the
777 arguments of an option are in in a specified ranges.
778 .sp
779 \fIvalue\fP must contain a string made of a maximum of 2 long integers
780 separated by spaces.
781 .sp
782 The first or the second of these numbers can be replaced with the
783 character \(aq\fI\&.\fP\(aq. In this case only the minimum or maximum is checked
784 and the \(aq\fI\&.\fP\(aq equals to plus or minus infinity depending of this
785 place in the string.
786 .sp
787 It returns 1 if the arguments respects the constraint and 0 if this
788 is not the case.
789 .UNINDENT
790 .nf
792 .fi
793 .sp
794 .INDENT 0.0
795 .IP \(bu 2
796 \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
797 .sp
798 This function processes the registered contexts instances tree, detects
799 errors and possibly reorganizes the options order according
800 to given priorities.
801 .sp
802 The first two arguments are similar to the \fIargc\fP and \fIargv\fP arguments
803 of the main function but without counting \fIargv[0]\fP\&.
804 Therefore, in many cases, \fInb_words\fP will have the value of \fIargc\-1\fP
805 and \fIwords\fP will have the value of \fIargv+1\fP\&.
806 .sp
807 The last two will receive the number of remaining (non analyzed)
808 command line words and the array of these remaining words.
809 Remaining words can be words appearing after \fB\-\-\fP per example.
810 .sp
811 All errors are fatal and terminates the program with a return code
812 greater then 0.
813 .sp
814 Example:
815 .INDENT 2.0
816 .INDENT 3.5
817 .sp
818 .nf
819 .ft C
820 int res_argc;
821 char ** res_argv;
822 \&...
823 ctxopt_analyze(argc\-1, argv+1, &res_argc, &res_argv);
824 .ft P
825 .fi
826 .UNINDENT
827 .UNINDENT
828 .UNINDENT
829 .nf
831 .fi
832 .sp
833 .INDENT 0.0
834 .IP \(bu 2
835 \fBvoid ctxopt_evaluate(void);\fP
836 .sp
837 This function walks through the tree of context instances previously
838 built by \fBctxopt_analyze\fP and launches the action attached to
839 each options, if any, one after the other.
840 .UNINDENT
841 .SH AUTHOR
842 Pierre Gentile p.gen.progs@gmail.com
843 .SH COPYRIGHT
844 GPLv2
845 .\" Generated by docutils manpage writer.
846 .