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