| blob | cdbd4ea51850113c50fa63be5cb1aa3022c25698 |
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 requirements:
473 This setting allows options in a context to require the presence of
474 sets of other options of which at least one must be present.
475 Using this setting, the user can impose dependencies between options.
476 .sp
477 The option that imposes the requirement must be the first in the
478 list of options listed in the third arguments.
479 .sp
480 Example of \fBrequirements\fP setting:
481 .INDENT 7.0
482 .INDENT 3.5
483 .sp
484 .nf
485 .ft C
486 void ctxopt_add_ctx_settings(requirements;
487 "context1",
488 "opt1 opt2 opt3");
489 .ft P
490 .fi
491 .UNINDENT
492 .UNINDENT
493 .sp
494 At least one of the two options named \fBopt2\fP and \fBopt3\fP must
495 be present in the same context instance as \fBopt1\fP which is
496 \fBcontext1\fP in this case
497 .sp
498 There may be multiple requirements via multiple calls to
499 \fBctxopt_add_ctx_settings\fP for the same first option (\fBopt1\fP
500 in the previous example) and the same context.
501 Each of them is considered in order.
502 .TP
503 .B actions:
504 This setting allows to associate a function to the context.
505 .sp
506 The second argument (called \fIf\fP below) will be called as soon as the
507 context is entered or exited during the evaluation phase.
508 .sp
509 Note that \fIf\fP will NOT be called if the context is empty
510 (does not contain any option).
511 .sp
512 The next parameters must be pointers to arbitrary data which may
513 be used by \fIf\fP\&.
514 .sp
515 In this setting, the last parameter must be \fBNULL\fP\&.
516 .sp
517 \fIf\fP must have the following prototype:
518 .INDENT 7.0
519 .INDENT 3.5
520 .sp
521 .nf
522 .ft C
523 int (*) (char * name1, /* Context name */
524 direction status, /* entering or exiting */
525 char * name2, /* previous or next context */
526 int nb_data, /* Number of data */
527 void ** data /* Data */);
528 .ft P
529 .fi
530 .UNINDENT
531 .UNINDENT
532 .sp
533 This function \fIf\fP will be called when entering \fBAND\fP exiting
534 the context.
535 Its arguments will then be set to:
536 .INDENT 7.0
537 .TP
538 .B \fIname1\fP
539 the name of the context.
540 .TP
541 .B \fIstatus\fP
542 will be \fBentering\fP when entering the context and \fBexiting\fP
543 when exiting the context.
544 .TP
545 .B \fIname2\fP
546 according to the content of \fIstatus\fP, the name of the context we
547 are coming from or the name of the context we are returning to.
548 .sp
549 \fIname2\fP can be \fBNULL\fP if we are entering in the main context or
550 are leaving it.
551 .TP
552 .B \fInb_data\fP
553 The number of data pointers passed to the \fBctxopt_add_ctx_settings\fP
554 function after the \fIs\fP parameter.
555 .TP
556 .B \fIdata\fP
557 The data pointers passed to the \fBctxopt_add_ctx_settings\fP function
558 after the \fIs\fP parameter and arranged in an array of \fInb_data\fP
559 .UNINDENT
560 .sp
561 Example of \fBactions\fP setting:
562 .INDENT 7.0
563 .INDENT 3.5
564 .sp
565 .nf
566 .ft C
567 void ctxopt_add_ctx_settings(actions,
568 "context1",
569 action,
570 &data_1, &data_2, &data_3,
571 NULL);
572 .ft P
573 .fi
574 .UNINDENT
575 .UNINDENT
576 .sp
577 This function call registers the \fBaction\fP function to the context
578 named \fBcontext1\fP\&.
579 .sp
580 The action function will be called \fBafter\fP entering to and
581 \fBbefore\fP exiting from each instance of the context
582 named \fBcontext1\fP\&.
583 .sp
584 The optional \fIdata_X\fP pointers will be passed to \fBaction\fP through
585 its data pointer to allow it to manipulate them if needed.
586 The count of these pointers (3 here) will also be passed to action
587 through its \fInb_data\fP parameter.
588 .sp
589 The ending \fBNULL\fP is mandatory.
590 .UNINDENT
591 .UNINDENT
592 .nf
594 .fi
595 .sp
596 .INDENT 0.0
597 .IP \(bu 2
598 \fBvoid ctxopt_add_opt_settings(settings\fP \fIs\fP\fB, char *\fP \fIopt\fP\fB,\fP \fI\&...\fP\fB);\fP
599 .sp
600 This function manages some settings for an option whose name is given in
601 \fIopt\fP\&.
602 .sp
603 The first parameter \fIs\fP determines the exact setting and the
604 signification of the remaining arguments.
605 Its possible values are:
606 .INDENT 2.0
607 .TP
608 .B parameters
609 This setting allows to associate command line parameters with \fIopt\fP\&.
610 The set of parameters must be given in the third argument as a string
611 containing words separated by blanks.
612 .sp
613 Each appearance of one of these parameters in the command line will
614 trigger the action associated with the named option.
615 .sp
616 Each of these words must start with one and exactly one dash.
617 .sp
618 Example of \fBparameters\fP setting:
619 .INDENT 7.0
620 .INDENT 3.5
621 .sp
622 .nf
623 .ft C
624 ctxopt_add_opt_settings(parameters,
625 "opt1",
626 "\-p \-parm \-p1");
627 .ft P
628 .fi
629 .UNINDENT
630 .UNINDENT
631 .sp
632 In this example, \fBopt1\fP is the name of a previously defined option and
633 \fB\-p\fP, \fB\-parm\fP and \fB\-p1\fP will be three valid command line
634 parameters for the option \fBopt1\fP\&.
635 .TP
636 .B actions
637 This setting allows to associate a function to this options.
638 As said above, this function will be called each time the option will be
639 recognized when evaluating the command line.
640 .sp
641 The function pointer must be given as the third argument.
642 .sp
643 Following the function pointer, it is possible to add a bunch of
644 other parameters which must be pointers to some pre\-allocated arbitrary
645 data.
646 .sp
647 These pointers will be passed to the function when called.
648 The last parameter must be \fBNULL\fP to end the sequence.
649 .sp
650 The function needs to be given as the third argument and must
651 match the following prototype:
652 .INDENT 7.0
653 .INDENT 3.5
654 .sp
655 .nf
656 .ft C
657 void (*) (char * ctx_name, /* Context name */
658 char * opt_name, /* Option name */
659 char * param, /* Parameter name */
660 int nb_values, /* Number of arguments */
661 char ** values, /* Arguments */
662 int nb_opt_data, /* Number of option data passed */
663 void ** opt_data, /* Array of option data passed */
664 int nb_ctx_data, /* Number of context data passed */
665 void ** ctx_data /* Array of context data passed */)
666 .ft P
667 .fi
668 .UNINDENT
669 .UNINDENT
670 .INDENT 7.0
671 .TP
672 .B \fIctx_name\fP
673 is the name of the current context.
674 .TP
675 .B \fIopt_name\fP
676 is the name of the option.
677 .TP
678 .B \fIparam\fP
679 is the name of the parameter that triggered the option \fIopt_name\fP\&.
680 .TP
681 .B \fInb_values\fP
682 is the number of arguments immediately following this option in
683 the command line.
684 .TP
685 .B \fIvalues\fP
686 is an array of stings containing the arguments following this
687 option in the command line.
688 .TP
689 .B \fInb_opt_data\fP
690 is the number of data pointers which were given after the third
691 arguments of \fBctxopt_add_opt_settings\fP\&.
692 .TP
693 .B \fIopt_data\fP
694 The data pointers passed after the third arguments of
695 \fBctxopt_add_opt_settings\fP and reorganized as an array of
696 \fInb_opt_data\fP elements.
697 .sp
698 The aim is to be able to consult/alter options specific data.
699 .TP
700 .B \fInb_ctx_data\fP
701 Same as \fInb_opt_data\fP but referencing to the number of data
702 pointers given to \fBctxopt_add_ctx_settings\fP for the current
703 context after its third argument.
704 .TP
705 .B \fIctx_data\fP
706 are the data pointers given to \fBctxopt_add_ctx_settings\fP for the
707 current context after its third argument.
708 .sp
709 The aim is to be able to consult/alter contexts specific data.
710 .UNINDENT
711 .sp
712 Example of \fBactions\fP setting:
713 .INDENT 7.0
714 .INDENT 3.5
715 .sp
716 .nf
717 .ft C
718 void action(char * ctx_name,
719 char * opt_name,
720 char * param,
721 int nb_values, char ** values,
722 int nb_opt_data, void ** opt_data,
723 int nb_ctx_data, void ** ctx_data)
724 {
725 \&...
726 }
728 \&...
730 void ctxopt_add_opt_settings(actions, "opt1", action,
731 &data_1, &data_2, &data_3,
732 NULL);
733 .ft P
734 .fi
735 .UNINDENT
736 .UNINDENT
737 .sp
738 This example associates the function \fIaction\fP to the option \fBopt1\fP\&.
739 .sp
740 Here, the \fIdata_*\fP pointers will be accessible to the function
741 \fIaction\fP when called through its argument \fIopt_data\fP and their number
742 (3 here) through its argument \fInb_opt_data\fP as mentioned above.
743 .sp
744 \fIaction\fP will also have access to the current context data in the
745 same way through its arguments \fIctx_data\fP and \fInb_ctx_data\fP\&.
746 .sp
747 The \fIaction\fP argument \fIparam\fP will receive the value of the specific
748 parameter which triggered it \- one of the parameters registered with
749 \fBctxopt_add_opt_settings\fP\&.
750 .TP
751 .B constraints
752 This setting registers a function whose responsibility is to validate
753 that the arguments of the option respect some constraints.
754 .sp
755 To do that the third argument must be a function pointer and the fourth
756 argument must be some arbitrary parameter to this function needed
757 to validate the constraint.
758 .sp
759 The constraint function must match the following prototype:
760 .INDENT 7.0
761 .INDENT 3.5
762 .sp
763 .nf
764 .ft C
765 int (*) (int nb_args, char ** args, char * value, char * parameter);
766 .ft P
767 .fi
768 .UNINDENT
769 .UNINDENT
770 .sp
771 Where:
772 .INDENT 7.0
773 .INDENT 3.5
774 .INDENT 0.0
775 .TP
776 .B \fInb_args\fP
777 is the number which will be set to the number of arguments fol\-
778 lowing the command line parameter.
779 .TP
780 .B \fIargs\fP
781 is an array of nb_args strings containing theses arguments.
782 .TP
783 .B \fIvalue\fP
784 is an arbitrary string containing the constraints which must be
785 respected by args.
786 .TP
787 .B \fIparameter\fP
788 is the parameter of which \fIvalue\fP is an argument.
789 .UNINDENT
790 .UNINDENT
791 .UNINDENT
792 .sp
793 Three constraint functions are built\-in and are described below.
794 They give examples on how to build them.
795 .sp
796 Example of constraint function using the built\-it regular expression
797 constraint checker function:
798 .INDENT 7.0
799 .INDENT 3.5
800 .sp
801 .nf
802 .ft C
803 ctxopt_add_opt_settings(constraints,
804 "opt1",
805 ctxopt_re_constraint,
806 "[^:]+:.+");
807 .ft P
808 .fi
809 .UNINDENT
810 .UNINDENT
811 .sp
812 In this example all the arguments of the option \fBopt1\fP must match
813 the extended regular expression:
814 .INDENT 7.0
815 .INDENT 3.5
816 .sp
817 .nf
818 .ft C
819 [^:]+:.+
820 .ft P
821 .fi
822 .UNINDENT
823 .UNINDENT
824 .sp
825 See below for details about the function \fBctxopt_re_constraint\fP\&.
826 .TP
827 .B before or after
828 These settings allow to tell ctxopt than some options must be
829 evaluated \fBbefore\fP or \fBafter\fP a given option in a context.
830 This can be useful, for example, if an action triggered by the
831 evaluation of a option is required to be executed before the action
832 of another option.
833 .sp
834 Example of \fBbefore\fP setting:
835 .INDENT 7.0
836 .INDENT 3.5
837 .sp
838 .nf
839 .ft C
840 ctxopt_add_opt_settings(before,
841 "opt1",
842 "opt2 opt3");
843 .ft P
844 .fi
845 .UNINDENT
846 .UNINDENT
847 .sp
848 In this example, \fBopt2\fP and \fBopt3\fP will be evaluated \fIbefore\fP
849 \fBopt1\fP\&.
850 The relative order of \fBopt2\fP and \fBopt3\fP evaluations will still
851 follow their order of appearance in the command line.
852 .sp
853 Example of \fBafter\fP setting:
854 .INDENT 7.0
855 .INDENT 3.5
856 .sp
857 .nf
858 .ft C
859 ctxopt_add_opt_settings(after,
860 "opt2",
861 "opt3 opt4");
862 .ft P
863 .fi
864 .UNINDENT
865 .UNINDENT
866 .sp
867 In this example, \fBopt3\fP and \fBopt4\fP will be evaluated \fIafter\fP
868 \fBopt2\fP\&.
869 This example shows than we can combine multiple settings reusing
870 options previously mentioned.
871 .sp
872 Incompatible setting combinations are not checked and will be ignored
873 or lead to undefined behaviors.
874 .UNINDENT
875 .UNINDENT
876 .nf
878 .fi
879 .sp
880 .INDENT 0.0
881 .IP \(bu 2
882 \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
883 .sp
884 This pre\-defined constraint function checks whether the arguments
885 in \fIargs\fP respect a C printf format given in value, \fI%2d\fP by e.g.
886 It returns 1 if the checking is successful and 0 if not.
887 .UNINDENT
888 .nf
890 .fi
891 .sp
892 .INDENT 0.0
893 .IP \(bu 2
894 \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
895 .sp
896 Another pre\-defined constraint function which checks if the arguments
897 of an option respects the extended regular expression given in \fIvalue\fP\&.
898 .sp
899 It returns 1 if the arguments respects the constraint and 0 if this
900 is not the case.
901 .UNINDENT
902 .nf
904 .fi
905 .sp
906 .INDENT 0.0
907 .IP \(bu 2
908 \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
909 .sp
910 Yet another pre\-defined constraint function. This one checks if the
911 arguments of an option are in in a specified ranges.
912 .sp
913 \fIvalue\fP must contain a string made of a maximum of 2 long integers
914 separated by spaces.
915 .sp
916 The first or the second of these numbers can be replaced with the
917 character \(aq\fI\&.\fP\(aq. In this case only the minimum or maximum is checked
918 and the \(aq\fI\&.\fP\(aq equals to plus or minus infinity depending of this
919 place in the string.
920 .sp
921 It returns 1 if the arguments respects the constraint and 0 if this
922 is not the case.
923 .UNINDENT
924 .nf
926 .fi
927 .sp
928 .INDENT 0.0
929 .IP \(bu 2
930 \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
931 .sp
932 This function processes the registered contexts instances tree, detects
933 errors and possibly reorganizes the options order according
934 to given priorities.
935 .sp
936 The first two arguments are similar to the \fIargc\fP and \fIargv\fP arguments
937 of the main function but without counting \fIargv[0]\fP\&.
938 Therefore, in many cases, \fInb_words\fP will have the value of \fIargc\-1\fP
939 and \fIwords\fP will have the value of \fIargv+1\fP\&.
940 .sp
941 The last two will receive the number of remaining (non analyzed)
942 command line words and the array of these remaining words.
943 Remaining words can be words appearing after \fB\-\-\fP per example.
944 .sp
945 All errors are fatal and terminates the program with a return code
946 greater then 0.
947 .sp
948 Example:
949 .INDENT 2.0
950 .INDENT 3.5
951 .sp
952 .nf
953 .ft C
954 int res_argc;
955 char ** res_argv;
956 \&...
957 ctxopt_analyze(argc\-1, argv+1, &res_argc, &res_argv);
958 .ft P
959 .fi
960 .UNINDENT
961 .UNINDENT
962 .UNINDENT
963 .nf
965 .fi
966 .sp
967 .INDENT 0.0
968 .IP \(bu 2
969 \fBvoid ctxopt_evaluate(void);\fP
970 .sp
971 This function walks through the tree of context instances previously
972 built by \fBctxopt_analyze\fP and launches the action attached to
973 each options, if any, one after the other.
974 .IP \(bu 2
975 \fBctxopt_free_memory(void)\fP
976 .sp
977 This function frees the memory used internally by \fBctxopt\fP\&.
978 .UNINDENT
979 .SH ENVIRONMENT
980 .sp
981 \fBctxopt\fP is able to switch to debug mode if the variable CTXOPT_DEBUG
982 is set to any not\-empty value.
983 .sp
984 If this is the case, informational messages about how \fBctxopt\fP
985 analyses the command line are printed on the error output.
986 .sp
987 Each of them are prefixed with "CTXOPT_DEBUG: ".
988 .SH AUTHOR
989 Pierre Gentile p.gen.progs@gmail.com
990 .SH COPYRIGHT
991 MPLv2.0
992 .\" Generated by docutils manpage writer.
993 .