| blob | ca9162a61acdf27ddcad69d5e06fb794cf7c912a |
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 .TP
201 .B opt...<3 #...=3
202 The mandatory option \fBopt\fP is restricted to only appear one or
203 two times in the context.
204 The number of its mandatory arguments must be exactly three.
205 .UNINDENT
206 .sp
207 The multiplicity or not of the options and argument, their mandatory or
208 optional characteristics constitutes their signatures.s
209 .sp
210 As said above, an option can appear in more than one context but must
211 have the same signature.
212 .sp
213 Example:
214 .INDENT 2.0
215 .INDENT 3.5
216 .sp
217 .nf
218 .ft C
219 ctxopt_new_ctx("context1",
220 "[opt1>context2...] #arg1... [opt3]");
222 ctxopt_new_ctx("context2",
223 "[opt2 [#arg2]] [opt3]");
224 .ft P
225 .fi
226 .UNINDENT
227 .UNINDENT
228 .sp
229 In the previous example, three options \fBopt1\fP, \fBopt2\fP and \fBopt3\fP
230 are defined.
231 .INDENT 2.0
232 .INDENT 3.5
233 .INDENT 0.0
234 .TP
235 .B opt1
236 is mandatory and can appear more than one time and take multiple
237 mandatory arguments.
238 .TP
239 .B opt2
240 is optional and take an optional argument.
241 .TP
242 .B opt3
243 is optional and take no argument.
244 Note that \fBopt3\fP is legal in both contexts.
245 .UNINDENT
246 .nf
248 .fi
249 .sp
250 .sp
251 \fBopt2\fP, if present in the command line, will be evaluated in the
252 context \fBcontext2\fP\&.
253 Note that, in this example, the \fBcontext2\fP can only be entered if
254 \fBopt1\fP has previously been seen in the command line.
255 Hence, \fBopt2\fP is only legal if \fBopt1\fP is present first.
256 .sp
257 \fBopt3\fP does not have this limitation.
258 In fact, as \fBopt3\fP is optional in \fBcontext2\fP and if its action
259 function is not interested in the name of the current context,
260 then it could have been omitted from the second setting thanks to
261 the backtracking: an option which is illegal in a context is retried
262 in the previous context in the hierarchy.
263 .UNINDENT
264 .UNINDENT
265 .UNINDENT
266 .nf
268 .fi
269 .sp
270 .INDENT 0.0
271 .IP \(bu 2
272 \fBvoid ctxopt_ctx_disp_usage(char *\fP \fIctx_name\fP\fB, usage_behaviour\fP \fIaction\fP\fB);\fP
273 .sp
274 This function builds and prints an usage help text for the
275 specific context \fIctx_name\fP\&.
276 The symbols used in this text are the same as those used when defining
277 options in \fBctxopt_new_ctx\fP\&.
278 .sp
279 The parameter \fIaction\fP can take the following values:
280 .INDENT 2.0
281 .TP
282 .B continue_after
283 The program is not stopped when this function returns.
284 .TP
285 .B exit_after
286 The program is stopped with a non zero return code (typically 1)
287 when this function returns.
288 .UNINDENT
289 .sp
290 The usage text is followed by a legend explaining the symbols meanings.
291 This function is useful when associated with a \fBhelp\fP or \fBusage\fP
292 option.
293 .UNINDENT
294 .nf
296 .fi
297 .sp
298 .INDENT 0.0
299 .IP \(bu 2
300 \fBvoid ctxopt_disp_usage(usage_behaviour\fP \fIaction\fP\fB);\fP
301 .sp
302 This function is similar to the preceding one but displays the usage
303 help text for all the defined contexts.
304 It is useful when associated with a general \fBhelp\fP or \fBusage\fP
305 option.
306 .sp
307 The parameter \fIaction\fP can take the following values:
308 .INDENT 2.0
309 .TP
310 .B continue_after
311 The program is not stopped when this function returns.
312 .TP
313 .B exit_after
314 The program is stopped with a non zero return code (typically 1)
315 when this function returns.
316 .UNINDENT
317 .UNINDENT
318 .nf
320 .fi
321 .sp
322 .INDENT 0.0
323 .IP \(bu 2
324 \fBvoid ctxopt_add_global_settings(settings\fP \fIs\fP\fB,\fP \fI\&...\fP\fB);\fP
325 .sp
326 This function allows to set general \fBctxopt\fP settings.
327 As for now, the only possible setting for \fIs\fP is \fBerror_functions\fP\&.
328 .sp
329 This setting tells \fBctxopt_add_global_settings\fP to use the rest of
330 its arguments in order to replace the built\-in error functions with
331 custom ones.
332 .sp
333 When the value of the first parameter is \fBerror_functions\fP,
334 then the second one must be one of the following constants:
335 .INDENT 2.0
336 .TP
337 .B CTXOPTMISPAR
338 A mandatory parameter is missing.
339 .TP
340 .B CTXOPTUNKPAR
341 A given parameter is unknown in the current context.
342 .TP
343 .B CTXOPTDUPOPT
344 An option has been seen more than once but has not been declared as
345 multiple in the context.
346 .TP
347 .B CTXOPTINCOPT
348 An option is incompatible with an option already given in the context.
349 .TP
350 .B CTXOPTMISARG
351 A mandatory argument is missing.
352 .TP
353 .B CTXOPTCNTEOPT, CTXOPTCNTLOPT and CTXOPTCNTGOPT
354 The number of occurrences is not equal, lower or greater than a
355 given value.
356 .TP
357 .B CTXOPTCNTEARG, CTXOPTCNTLARG and CTXOPTCNTGARG
358 The number of arguments of an option is not equal, lower or greater
359 than a given value.
360 .UNINDENT
361 .sp
362 and the third parameter is a function pointer with the following
363 prototype:
364 .INDENT 2.0
365 .INDENT 3.5
366 .sp
367 .nf
368 .ft C
369 void (*) (errors err, state_t * state);
370 .ft P
371 .fi
372 .UNINDENT
373 .UNINDENT
374 .sp
375 \fIstate\fP will point to the publicly available analysis state structure.
376 This structure contains a snapshot of variables related to the command
377 line analysis so far.
378 They and can be used to give the user clues about errors.
379 .sp
380 This structure available in \fBctxopt.h\fP is:
381 .INDENT 2.0
382 .INDENT 3.5
383 .sp
384 .nf
385 .ft C
386 typedef struct
387 {
388 char * prog_name; /* base name of the program name. */
389 char * ctx_name; /* current context name. */
390 char * ctx_par_name; /* parameter which led to this context. */
391 char * opt_name; /* current option name. */
392 char * opt_params; /* all parameters of the current option. */
393 int opts_count; /* limit of the number of occurrences of *
394 | the current option. */
395 int opt_args_count; /* limit of the number of parameters of *
396 | the current option. */
397 char * pre_opt_par_name; /* parameter just before the current one. */
398 char * cur_opt_par_name; /* current parameter. */
399 } state_t;
400 .ft P
401 .fi
402 .UNINDENT
403 .UNINDENT
404 .sp
405 All these pointers can be equal to the \fBNULL\fP pointer.
406 .sp
407 Example:
408 .INDENT 2.0
409 .INDENT 3.5
410 .sp
411 .nf
412 .ft C
413 ctxopt_add_global_settings(error_functions, CTXOPTMISPAR, error);
414 .ft P
415 .fi
416 .UNINDENT
417 .UNINDENT
418 .UNINDENT
419 .nf
421 .fi
422 .sp
423 .INDENT 0.0
424 .IP \(bu 2
425 \fBvoid ctxopt_add_ctx_settings(settings\fP \fIs\fP\fB,\fP \fI\&...\fP\fB);\fP
426 .sp
427 This function manages some settings for a given context.
428 Its first parameter \fIs\fP determines the setting and the signification
429 of the remaining arguments.
430 .sp
431 Its possible values are:
432 .INDENT 2.0
433 .TP
434 .B incompatibilities:
435 This setting allows to declare a set of options incompatible with
436 each other.
437 .sp
438 In this case the second argument must be a context name and the
439 third argument must be a string containing option names separated
440 by a space.
441 .sp
442 Example of \fBincompatibilities\fP setting:
443 .INDENT 7.0
444 .INDENT 3.5
445 .sp
446 .nf
447 .ft C
448 void ctxopt_add_ctx_settings(incompatibilities,
449 context1,
450 "opt1 opt2 opt3");
451 .ft P
452 .fi
453 .UNINDENT
454 .UNINDENT
455 .sp
456 The three options named \fBopt1\fP, \fBopt2\fP and \fBopt3\fP will be
457 marked as mutually incompatibles in each instance of the context
458 \fBcontext1\fP\&.
459 .TP
460 .B actions:
461 This setting allows to associate a function to the context.
462 .sp
463 The second argument (called \fIf\fP below) will be called as soon as the
464 context is entered or exited during the evaluation phase.
465 .sp
466 Note that \fIf\fP will NOT be called if the context is empty
467 (does not contain any option).
468 .sp
469 The next parameters must be pointers to arbitrary data which may
470 be used by \fIf\fP\&.
471 .sp
472 In this setting, the last parameter must be \fBNULL\fP\&.
473 .sp
474 \fIf\fP must have the following prototype:
475 .INDENT 7.0
476 .INDENT 3.5
477 .sp
478 .nf
479 .ft C
480 int (*) (char * name1, /* Context name */
481 direction status, /* entering or exiting */
482 char * name2, /* previous or next context */
483 int nb_data, /* Number of data */
484 void ** data /* Data */);
485 .ft P
486 .fi
487 .UNINDENT
488 .UNINDENT
489 .sp
490 This function \fIf\fP will be called when entering \fBAND\fP exiting
491 the context.
492 Its arguments will then be set to:
493 .INDENT 7.0
494 .TP
495 .B \fIname1\fP
496 the name of the context.
497 .TP
498 .B \fIstatus\fP
499 will be \fBentering\fP when entering the context and \fBexiting\fP
500 when exiting the context.
501 .TP
502 .B \fIname2\fP
503 according to the content of \fIstatus\fP, the name of the context we
504 are coming from or the name of the context we are returning to.
505 .sp
506 \fIname2\fP can be \fBNULL\fP if we are entering in the main context or
507 are leaving it.
508 .TP
509 .B \fInb_data\fP
510 The number of data pointers passed to the \fBctxopt_add_ctx_settings\fP
511 function after the \fIs\fP parameter.
512 .TP
513 .B \fIdata\fP
514 The data pointers passed to the \fBctxopt_add_ctx_settings\fP function
515 after the \fIs\fP parameter and arranged in an array of \fInb_data\fP
516 .UNINDENT
517 .sp
518 Example of \fBactions\fP setting:
519 .INDENT 7.0
520 .INDENT 3.5
521 .sp
522 .nf
523 .ft C
524 void ctxopt_add_ctx_settings(actions,
525 "context1",
526 action,
527 &data_1, &data_2, &data_3,
528 NULL);
529 .ft P
530 .fi
531 .UNINDENT
532 .UNINDENT
533 .sp
534 This function call registers the \fBaction\fP function to the context
535 named \fBcontext1\fP\&.
536 .sp
537 The action function will be called \fBafter\fP entering to and
538 \fBbefore\fP exiting from each instance of the context
539 named \fBcontext1\fP\&.
540 .sp
541 The optional \fIdata_X\fP pointers will be passed to \fBaction\fP through
542 its data pointer to allow it to manipulate them if needed.
543 The count of these pointers (3 here) will also be passed to action
544 through its \fInb_data\fP parameter.
545 .sp
546 The ending \fBNULL\fP is mandatory.
547 .UNINDENT
548 .UNINDENT
549 .nf
551 .fi
552 .sp
553 .INDENT 0.0
554 .IP \(bu 2
555 \fBvoid ctxopt_add_opt_settings(settings\fP \fIs\fP\fB, char *\fP \fIopt\fP\fB,\fP \fI\&...\fP\fB);\fP
556 .sp
557 This function manages some settings for an option whose name is given in
558 \fIopt\fP\&.
559 .sp
560 The first parameter \fIs\fP determines the exact setting and the
561 signification of the remaining arguments.
562 Its possible values are:
563 .INDENT 2.0
564 .TP
565 .B parameters
566 This setting allows to associate command line parameters with \fIopt\fP\&.
567 The set of parameters must be given in the third argument as a string
568 containing words separated by blanks.
569 .sp
570 Each appearance of one of these parameters in the command line will
571 trigger the action associated with the named option.
572 .sp
573 Each of these words must start with one and exactly one dash.
574 .sp
575 Example of \fBparameters\fP setting:
576 .INDENT 7.0
577 .INDENT 3.5
578 .sp
579 .nf
580 .ft C
581 ctxopt_add_opt_settings(parameters,
582 "opt1",
583 "\-p \-parm \-p1");
584 .ft P
585 .fi
586 .UNINDENT
587 .UNINDENT
588 .sp
589 In this example, \fBopt1\fP is the name of a previously defined option and
590 \fB\-p\fP, \fB\-parm\fP and \fB\-p1\fP will be three valid command line
591 parameters for the option \fBopt1\fP\&.
592 .TP
593 .B actions
594 This setting allows to associate a function to this options.
595 As said above, this function will be called each time the option will be
596 recognized when evaluating the command line.
597 .sp
598 The function pointer must be given as the third argument.
599 .sp
600 Following the function pointer, it is possible to add a bunch of
601 other parameters which must be pointers to some pre\-allocated arbitrary
602 data.
603 .sp
604 These pointers will be passed to the function when called.
605 The last parameter must be \fBNULL\fP to end the sequence.
606 .sp
607 The function needs to be given as the third argument and must
608 match the following prototype:
609 .INDENT 7.0
610 .INDENT 3.5
611 .sp
612 .nf
613 .ft C
614 void (*) (char * ctx_name, /* Context name */
615 char * opt_name, /* Option name */
616 char * param, /* Parameter name */
617 int nb_values, /* Number of arguments */
618 char ** values, /* Arguments */
619 int nb_opt_data, /* Number of option data passed */
620 void ** opt_data, /* Array of option data passed */
621 int nb_ctx_data, /* Number of context data passed */
622 void ** ctx_data /* Array of context data passed */)
623 .ft P
624 .fi
625 .UNINDENT
626 .UNINDENT
627 .INDENT 7.0
628 .TP
629 .B \fIctx_name\fP
630 is the name of the current context.
631 .TP
632 .B \fIopt_name\fP
633 is the name of the option.
634 .TP
635 .B \fIparam\fP
636 is the name of the parameter that triggered the option \fIopt_name\fP\&.
637 .TP
638 .B \fInb_values\fP
639 is the number of arguments immediately following this option in
640 the command line.
641 .TP
642 .B \fIvalues\fP
643 is an array of stings containing the arguments following this
644 option in the command line.
645 .TP
646 .B \fInb_opt_data\fP
647 is the number of data pointers which were given after the third
648 arguments of \fBctxopt_add_opt_settings\fP\&.
649 .TP
650 .B \fIopt_data\fP
651 The data pointers passed after the third arguments of
652 \fBctxopt_add_opt_settings\fP and reorganized as an array of
653 \fInb_opt_data\fP elements.
654 .sp
655 The aim is to be able to consult/alter options specific data.
656 .TP
657 .B \fInb_ctx_data\fP
658 Same as \fInb_opt_data\fP but referencing to the number of data
659 pointers given to \fBctxopt_add_ctx_settings\fP for the current
660 context after its third argument.
661 .TP
662 .B \fIctx_data\fP
663 are the data pointers given to \fBctxopt_add_ctx_settings\fP for the
664 current context after its third argument.
665 .sp
666 The aim is to be able to consult/alter contexts specific data.
667 .UNINDENT
668 .sp
669 Example of \fBactions\fP setting:
670 .INDENT 7.0
671 .INDENT 3.5
672 .sp
673 .nf
674 .ft C
675 void action(char * ctx_name,
676 char * opt_name,
677 char * param,
678 int nb_values, char ** values,
679 int nb_opt_data, void ** opt_data,
680 int nb_ctx_data, void ** ctx_data)
681 {
682 \&...
683 }
685 \&...
687 void ctxopt_add_opt_settings(actions, "opt1", action,
688 &data_1, &data_2, &data_3,
689 NULL);
690 .ft P
691 .fi
692 .UNINDENT
693 .UNINDENT
694 .sp
695 This example associates the function \fIaction\fP to the option \fBopt1\fP\&.
696 .sp
697 Here, the \fIdata_*\fP pointers will be accessible to the function
698 \fIaction\fP when called through its argument \fIopt_data\fP and their number
699 (3 here) through its argument \fInb_opt_data\fP as mentioned above.
700 .sp
701 \fIaction\fP will also have access to the current context data in the
702 same way through its arguments \fIctx_data\fP and \fInb_ctx_data\fP\&.
703 .sp
704 The \fIaction\fP argument \fIparam\fP will receive the value of the specific
705 parameter which triggered it \- one of the parameters registered with
706 \fBctxopt_add_opt_settings\fP\&.
707 .TP
708 .B constraints
709 This setting registers a function whose responsibility is to validate
710 that the arguments of the option respect some constraints.
711 .sp
712 To do that the third argument must be a function pointer and the fourth
713 argument must be some arbitrary parameter to this function needed
714 to validate the constraint.
715 .sp
716 The constraint function must match the following prototype:
717 .INDENT 7.0
718 .INDENT 3.5
719 .sp
720 .nf
721 .ft C
722 int (*) (int nb_args, char ** args, char * value, char * parameter);
723 .ft P
724 .fi
725 .UNINDENT
726 .UNINDENT
727 .sp
728 Where:
729 .INDENT 7.0
730 .INDENT 3.5
731 .INDENT 0.0
732 .TP
733 .B \fInb_args\fP
734 is the number which will be set to the number of arguments fol\-
735 lowing the command line parameter.
736 .TP
737 .B \fIargs\fP
738 is an array of nb_args strings containing theses arguments.
739 .TP
740 .B \fIvalue\fP
741 is an arbitrary string containing the constraints which must be
742 respected by args.
743 .TP
744 .B \fIparameter\fP
745 is the parameter of which \fIvalue\fP is an argument.
746 .UNINDENT
747 .UNINDENT
748 .UNINDENT
749 .sp
750 Three constraint functions are built\-in and are described below.
751 They give examples on how to build them.
752 .sp
753 Example of constraint function using the built\-it regular expression
754 constraint checker function:
755 .INDENT 7.0
756 .INDENT 3.5
757 .sp
758 .nf
759 .ft C
760 ctxopt_add_opt_settings(constraints,
761 "opt1",
762 ctxopt_re_constraint,
763 "[^:]+:.+");
764 .ft P
765 .fi
766 .UNINDENT
767 .UNINDENT
768 .sp
769 In this example all the arguments of the option \fBopt1\fP must match
770 the extended regular expression:
771 .INDENT 7.0
772 .INDENT 3.5
773 .sp
774 .nf
775 .ft C
776 [^:]+:.+
777 .ft P
778 .fi
779 .UNINDENT
780 .UNINDENT
781 .sp
782 See below for details about the function \fBctxopt_re_constraint\fP\&.
783 .UNINDENT
784 .UNINDENT
785 .nf
787 .fi
788 .sp
789 .INDENT 0.0
790 .IP \(bu 2
791 \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
792 .sp
793 This pre\-defined constraint function checks whether the arguments
794 in \fIargs\fP respect a C printf format given in value, \fI%2d\fP by e.g.
795 It returns 1 if the checking is successful and 0 if not.
796 .UNINDENT
797 .nf
799 .fi
800 .sp
801 .INDENT 0.0
802 .IP \(bu 2
803 \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
804 .sp
805 Another pre\-defined constraint function which checks if the arguments
806 of an option respects the extended regular expression given in \fIvalue\fP\&.
807 .sp
808 It returns 1 if the arguments respects the constraint and 0 if this
809 is not the case.
810 .UNINDENT
811 .nf
813 .fi
814 .sp
815 .INDENT 0.0
816 .IP \(bu 2
817 \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
818 .sp
819 Yet another pre\-defined constraint function. This one checks if the
820 arguments of an option are in in a specified ranges.
821 .sp
822 \fIvalue\fP must contain a string made of a maximum of 2 long integers
823 separated by spaces.
824 .sp
825 The first or the second of these numbers can be replaced with the
826 character \(aq\fI\&.\fP\(aq. In this case only the minimum or maximum is checked
827 and the \(aq\fI\&.\fP\(aq equals to plus or minus infinity depending of this
828 place in the string.
829 .sp
830 It returns 1 if the arguments respects the constraint and 0 if this
831 is not the case.
832 .UNINDENT
833 .nf
835 .fi
836 .sp
837 .INDENT 0.0
838 .IP \(bu 2
839 \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
840 .sp
841 This function processes the registered contexts instances tree, detects
842 errors and possibly reorganizes the options order according
843 to given priorities.
844 .sp
845 The first two arguments are similar to the \fIargc\fP and \fIargv\fP arguments
846 of the main function but without counting \fIargv[0]\fP\&.
847 Therefore, in many cases, \fInb_words\fP will have the value of \fIargc\-1\fP
848 and \fIwords\fP will have the value of \fIargv+1\fP\&.
849 .sp
850 The last two will receive the number of remaining (non analyzed)
851 command line words and the array of these remaining words.
852 Remaining words can be words appearing after \fB\-\-\fP per example.
853 .sp
854 All errors are fatal and terminates the program with a return code
855 greater then 0.
856 .sp
857 Example:
858 .INDENT 2.0
859 .INDENT 3.5
860 .sp
861 .nf
862 .ft C
863 int res_argc;
864 char ** res_argv;
865 \&...
866 ctxopt_analyze(argc\-1, argv+1, &res_argc, &res_argv);
867 .ft P
868 .fi
869 .UNINDENT
870 .UNINDENT
871 .UNINDENT
872 .nf
874 .fi
875 .sp
876 .INDENT 0.0
877 .IP \(bu 2
878 \fBvoid ctxopt_evaluate(void);\fP
879 .sp
880 This function walks through the tree of context instances previously
881 built by \fBctxopt_analyze\fP and launches the action attached to
882 each options, if any, one after the other.
883 .UNINDENT
884 .SH AUTHOR
885 Pierre Gentile p.gen.progs@gmail.com
886 .SH COPYRIGHT
887 GPLv2
888 .\" Generated by docutils manpage writer.
889 .