ctxopt.rst

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