ctxopt.rst

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