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 three flags are understood: **stop_if_non_option**,
  96   **allow_abbreviations** and **display_usage_on_error**.
  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   display_usage_on_error
 112     If the setting is set to yes (default), the usage text for the
 113     relevant contexts is displayed in case of a fatal error.
 114     This may be useful to reduce the length of the error message and
 115     allow the user to see the error more easily.
 116
 117   Example of content of the *flags* parameter:
 118
 119   .. code-block:: c
 120
 121     "stop_if_non_option=1 allow_abbreviations=No"
 122
 123 |
 124
 125 * **void ctxopt_new_ctx(char *** \
 126   *name*\
 127   **, char *** \
 128   *opts_specs*\
 129   **);**
 130
 131   The next thing to do after having called **ctxopt_new_ctx** is to
 132   define the contexts and its associated options.
 133
 134   Using this function, you can name the new context and its authorized
 135   options and determine their main characteristics with a syntax easy
 136   to understand.
 137   If they already exist in another context, then they must have the same
 138   signature (described below) as in their previous appearance.
 139
 140   *name* is the name of the new context and *opts_specs* must contain a
 141   description of the options allowed in this context.
 142
 143   *opts_specs* is a string containing various components separated by
 144   spaces according to the syntax below:
 145
 146   opt
 147     A mandatory option named opt without parameter usable only one type in
 148     the context
 149
 150   opt1 opt2
 151       Two mandatory option named **opt1** and **opt2** without argument.
 152
 153   opt...
 154       Same as above but can appear multiple time in the context.
 155
 156   [opt...]
 157       Same as above but the option is optional
 158
 159   opt1 [opt2...]
 160       One mandatory and one optional option named **opt1** and **opt2**
 161       without argument. **opt2** can appear multiple times in the context.
 162
 163   opt #
 164       One mandatory option named **opt*** taking one mandatory argument.
 165
 166   opt #tag
 167       One mandatory option named **opt** taking one mandatory argument.
 168       **tag** is ignored but can be used to improve the readability.
 169
 170   opt [#]
 171       One mandatory option named **opt** taking one optional argument.
 172
 173   opt #...
 174       One mandatory option named **opt** taking one or more mandatory
 175       arguments.
 176
 177   opt>ctx... [#<value>]
 178       The mandatory multiple option named **opt** will switch to the
 179       context named **cxt** which will become the new current context.
 180
 181       It takes an optional argument with a tag named **<value>**.
 182
 183   [opt... [#...]]
 184       One optional option named **opt** taking multiple optional
 185       arguments.
 186
 187   The number of options/arguments allowed can be restricted by adding
 188   an operator and an integer just after the dots like in the following
 189   example:
 190
 191     opt...<3 #...=3
 192         Here, the mandatory option **opt** is restricted to only appear
 193         one or two times in the context.
 194         The number of its mandatory arguments must be exactly three.
 195
 196         Valid operators are **<**, **=** and **>**.
 197
 198   The multiplicity or not of the options and argument, their mandatory or
 199   optional characteristics constitutes their signatures.s
 200
 201   As said above, an option can appear in more than one context but must
 202   have the same signature.
 203
 204   Example:
 205
 206   .. code-block:: c
 207
 208     ctxopt_new_ctx("context1",
 209                    "[opt1>context2...] #arg1... [opt3]");
 210
 211     ctxopt_new_ctx("context2",
 212                    "[opt2 [#arg2]] [opt3]");
 213
 214   In the previous example, three options **opt1**, **opt2** and **opt3**
 215   are defined.
 216
 217     :opt1:
 218       is mandatory and can appear more than one time and take multiple
 219       mandatory arguments.
 220
 221     :opt2:
 222       is optional and take an optional argument.
 223
 224     :opt3:
 225       is optional and take no argument.
 226       Note that **opt3** is legal in both contexts.
 227
 228     |
 229
 230     **opt2**, if present in the command line, will be evaluated in the
 231     context **context2**.
 232     Note that, in this example, the **context2** can only be entered if
 233     **opt1** has previously been seen in the command line.
 234     Hence, **opt2** is only legal if **opt1** is present first.
 235
 236     **opt3** does not have this limitation.
 237     In fact, as **opt3** is optional in **context2** and if its action
 238     function is not interested in the name of the current context,
 239     then it could have been omitted from the second setting thanks to
 240     the backtracking: an option which is illegal in a context is retried
 241     in the previous context in the hierarchy.
 242
 243 |
 244
 245 * **void ctxopt_ctx_disp_usage(char *** \
 246   *ctx_name*\
 247   **, usage_behaviour** \
 248   *action*\
 249   **);**
 250
 251   This function builds and prints an usage help text for the
 252   specific context *ctx_name*.
 253   The symbols used in this text are the same as those used when defining
 254   options in **ctxopt_new_ctx**.
 255
 256   The parameter *action* can take the following values:
 257
 258   continue_after
 259     The program is not stopped when this function returns.
 260
 261   exit_after
 262     The program is stopped with a non zero return code (typically 1)
 263     when this function returns.
 264
 265   The usage text is followed by a legend explaining the symbols meanings.
 266   This function is useful when associated with a **help** or **usage**
 267   option.
 268
 269 |
 270
 271 * **void ctxopt_disp_usage(usage_behaviour** \
 272   *action*\
 273   **);**
 274
 275   This function is similar to the preceding one but displays the usage
 276   help text for all the defined contexts.
 277   It is useful when associated with a general **help** or **usage**
 278   option.
 279
 280   The parameter *action* can take the following values:
 281
 282   continue_after
 283     The program is not stopped when this function returns.
 284
 285   exit_after
 286     The program is stopped with a non zero return code (typically 1)
 287     when this function returns.
 288
 289 |
 290
 291 * **void ctxopt_add_global_settings(settings** \
 292   *s*\
 293   **,** \
 294   *...*\
 295   **);**
 296
 297   This function allows to set general **ctxopt** settings.
 298   As for now, the only possible setting for *s* is **error_functions**.
 299
 300   This setting tells **ctxopt_add_global_settings** to use the rest of
 301   its arguments in order to replace the built-in error functions with
 302   custom ones.
 303
 304   When the value of the first parameter is **error_functions**,
 305   then the second one must be one of the following constants:
 306
 307   :CTXOPTMISPAR:
 308     A mandatory parameter is missing.
 309
 310   :CTXOPTUNKPAR:
 311     A given parameter is unknown in the current context.
 312
 313   :CTXOPTDUPOPT:
 314      An option has been seen more than once but has not been declared as
 315      multiple in the context.
 316
 317   :CTXOPTINCOPT:
 318     An option is incompatible with an option already given in the context.
 319
 320   :CTXOPTMISARG:
 321     A mandatory argument is missing.
 322
 323   :CTXOPTCNTEOPT, CTXOPTCNTLOPT and CTXOPTCNTGOPT:
 324     The number of occurrences is not equal, lower or greater than a
 325     given value.
 326
 327   :CTXOPTCNTEARG, CTXOPTCNTLARG and CTXOPTCNTGARG:
 328     The number of arguments of an option is not equal, lower or greater
 329     than a given value.
 330
 331   and the third parameter is a function pointer with the following
 332   prototype:
 333
 334   .. code-block:: c
 335
 336     void (*) (errors err, state_t * state);
 337
 338   *state* will point to the publicly available analysis state structure.
 339   This structure contains a snapshot of variables related to the command
 340   line analysis so far.
 341   They and can be used to give the user clues about errors.
 342
 343   This structure available in **ctxopt.h** is:
 344
 345   .. code-block:: c
 346
 347     typedef struct
 348     {
 349       char * prog_name;        /* base name of the program name.         */
 350       char * ctx_name;         /* current context name.                  */
 351       char * ctx_par_name;     /* parameter which led to this context.   */
 352       char * opt_name;         /* current option name.                   */
 353       char * opt_params;       /* all parameters of the current option.  */
 354       int    opts_count;       /* limit of the number of occurrences of  *
 355                                |  the current option.                    */
 356       int opt_args_count;      /* limit of the number of parameters of   *
 357                                |  the current option.                    */
 358       char * pre_opt_par_name; /* parameter just before the current one. */
 359       char * cur_opt_par_name; /* current parameter.                     */
 360     } state_t;
 361
 362   All these pointers can be equal to the **NULL** pointer.
 363
 364   Example:
 365
 366   .. code-block:: c
 367
 368     ctxopt_add_global_settings(error_functions, CTXOPTMISPAR, error);
 369
 370 |
 371
 372 * **void ctxopt_add_ctx_settings(settings** \
 373   *s*\
 374   **,** \
 375   *...*\
 376   **);**
 377
 378   This function manages some settings for a given context.
 379   Its first parameter *s* determines the setting and the signification
 380   of the remaining arguments.
 381
 382   Its possible values are:
 383
 384   incompatibilities:
 385     This setting allows to declare a set of options incompatible with
 386     each other.
 387
 388     In this case the second argument must be a context name and the
 389     third argument must be a string containing option names separated
 390     by a space.
 391
 392     Example of **incompatibilities** setting:
 393
 394     .. code-block:: c
 395
 396       void ctxopt_add_ctx_settings(incompatibilities,
 397                                    "context1",
 398                                    "opt1 opt2 opt3");
 399
 400     The three options named **opt1**, **opt2** and **opt3** will be
 401     marked as mutually incompatibles in each instance of the context
 402     **context1**.
 403
 404   requirements:
 405     This setting allows options in a context to require the presence of
 406     sets of other options of which at least one must be present.
 407     Using this setting, the user can impose dependencies between options.
 408
 409     The option that imposes the requirement must be the first in the
 410     list of options listed in the third arguments.
 411
 412     Example of **requirements** setting:
 413
 414     .. code-block:: c
 415
 416       void ctxopt_add_ctx_settings(requirements;
 417                                    "context1",
 418                                    "opt1 opt2 opt3");
 419
 420     At least one of the two options named **opt2** and **opt3** must
 421     be present in the same context instance as **opt1** which is
 422     **context1** in this case
 423
 424     There may be multiple requirements via multiple calls to
 425     **ctxopt_add_ctx_settings** for the same first option (**opt1**
 426     in the previous example) and the same context.
 427     Each of them is considered in order.
 428
 429   actions:
 430     This setting allows to associate a function to the context.
 431
 432     The second argument (called *f* below) will be called as soon as the
 433     context is entered or exited during the evaluation phase.
 434
 435     Note that *f* will NOT be called if the context is empty
 436     (does not contain any option).
 437
 438     The next parameters must be pointers to arbitrary data which may
 439     be used by *f*.
 440
 441     In this setting, the last parameter must be **NULL**.
 442
 443     *f* must have the following prototype:
 444
 445     .. code-block:: c
 446
 447       int (*) (char     * name1,   /* Context name */
 448                direction  status,  /* entering or exiting */
 449                char     * name2,   /* previous or next context */
 450                int        nb_data, /* Number of data */
 451                void    ** data     /* Data */);
 452
 453     This function *f* will be called when entering **AND** exiting
 454     the context.
 455     Its arguments will then be set to:
 456
 457     *name1*
 458       the name of the context.
 459
 460     *status*
 461       will be **entering** when entering the context and **exiting**
 462       when exiting the context.
 463
 464     *name2*
 465       according to the content of *status*, the name of the context we
 466       are coming from or the name of the context we are returning to.
 467
 468       *name2* can be **NULL** if we are entering in the main context or
 469       are leaving it.
 470
 471     *nb_data*
 472       The number of data pointers passed to the **ctxopt_add_ctx_settings**
 473       function after the *s* parameter.
 474
 475     *data*
 476       The data pointers passed to the **ctxopt_add_ctx_settings** function
 477       after the *s* parameter and arranged in an array of *nb_data*
 478
 479     Example of **actions** setting:
 480
 481     .. code-block:: c
 482
 483       void ctxopt_add_ctx_settings(actions,
 484                                    "context1",
 485                                    action,
 486                                    &data_1, &data_2, &data_3,
 487                                    NULL);
 488
 489     This function call registers the **action** function to the context
 490     named **context1**.
 491
 492     The action function will be called **after** entering to and
 493     **before** exiting from each instance of the context
 494     named **context1**.
 495
 496     The optional *data_X* pointers will be passed to **action** through
 497     its data pointer to allow it to manipulate them if needed.
 498     The count of these pointers (3 here) will also be passed to action
 499     through its *nb_data* parameter.
 500
 501     The ending **NULL** is mandatory.
 502
 503 |
 504
 505 * **void ctxopt_add_opt_settings(settings** \
 506   *s*\
 507   **, char *** \
 508   *opt*\
 509   **,** \
 510   *...*\
 511   **);**
 512
 513   This function manages some settings for an option whose name is given in
 514   *opt*.
 515
 516   The first parameter *s* determines the exact setting and the
 517   signification of the remaining arguments.
 518   Its possible values are:
 519
 520   parameters
 521     This setting allows to associate command line parameters with *opt*.
 522     The set of parameters must be given in the third argument as a string
 523     containing words separated by blanks.
 524
 525     Each appearance of one of these parameters in the command line will
 526     trigger the action associated with the named option.
 527
 528     Each of these words must start with one and exactly one dash.
 529
 530     Example of **parameters** setting:
 531
 532     .. code-block:: c
 533
 534       ctxopt_add_opt_settings(parameters,
 535                               "opt1",
 536                               "-p -parm -p1");
 537
 538     In this example, **opt1** is the name of a previously defined option and
 539     **-p**, **-parm** and **-p1** will be three valid command line
 540     parameters for the option **opt1**.
 541
 542   actions
 543     This setting allows to associate a function to this options.
 544     As said above, this function will be called each time the option will be
 545     recognized when evaluating the command line.
 546
 547     The function pointer must be given as the third argument.
 548
 549     Following the function pointer, it is possible to add a bunch of
 550     other parameters which must be pointers to some pre-allocated arbitrary
 551     data.
 552
 553     These pointers will be passed to the function when called.
 554     The last parameter must be **NULL** to end the sequence.
 555
 556     The function needs to be given as the third argument and must
 557     match the following prototype:
 558
 559     .. code-block:: c
 560
 561       void (*) (char  * ctx_name,     /* Context name */
 562                 char  * opt_name,     /* Option name  */
 563                 char  * param,        /* Parameter name */
 564                 int     nb_values,    /* Number of arguments */
 565                 char ** values,       /* Arguments */
 566                 int     nb_opt_data,  /* Number of option data passed */
 567                 void ** opt_data,     /* Array of option data passed */
 568                 int     nb_ctx_data,  /* Number of context data passed */
 569                 void ** ctx_data      /* Array of context data passed */)
 570
 571     *ctx_name*
 572       is the name of the current context.
 573
 574     *opt_name*
 575       is the name of the option.
 576
 577     *param*
 578       is the name of the parameter that triggered the option *opt_name*.
 579
 580     *nb_values*
 581       is the number of arguments immediately following this option in
 582       the command line.
 583
 584     *values*
 585       is an array of stings containing the arguments following this
 586       option in the command line.
 587
 588     *nb_opt_data*
 589       is the number of data pointers which were given after the third
 590       arguments of **ctxopt_add_opt_settings**.
 591
 592     *opt_data*
 593       The data pointers passed after the third arguments of
 594       **ctxopt_add_opt_settings** and reorganized as an array of
 595       *nb_opt_data* elements.
 596
 597       The aim is to be able to consult/alter options specific data.
 598
 599     *nb_ctx_data*
 600        Same as *nb_opt_data* but referencing to the number of data
 601        pointers given to **ctxopt_add_ctx_settings** for the current
 602        context after its third argument.
 603
 604     *ctx_data*
 605       are the data pointers given to **ctxopt_add_ctx_settings** for the
 606       current context after its third argument.
 607
 608       The aim is to be able to consult/alter contexts specific data.
 609
 610     Example of **actions** setting:
 611
 612     .. code-block:: c
 613
 614       void action(char * ctx_name,
 615                   char * opt_name,
 616                   char * param,
 617                   int    nb_values,   char ** values,
 618                   int    nb_opt_data, void ** opt_data,
 619                   int    nb_ctx_data, void ** ctx_data)
 620       {
 621         ...
 622       }
 623
 624       ...
 625
 626       void ctxopt_add_opt_settings(actions, "opt1", action,
 627                                    &data_1, &data_2, &data_3,
 628                                    NULL);
 629
 630     This example associates the function *action* to the option **opt1**.
 631
 632     Here, the *data_** pointers will be accessible to the function
 633     *action* when called through its argument *opt_data* and their number
 634     (3 here) through its argument *nb_opt_data* as mentioned above.
 635
 636     *action* will also have access to the current context data in the
 637     same way through its arguments *ctx_data* and *nb_ctx_data*.
 638
 639     The *action* argument *param* will receive the value of the specific
 640     parameter which triggered it - one of the parameters registered with
 641     **ctxopt_add_opt_settings**.
 642
 643   constraints
 644     This setting registers a function whose responsibility is to validate
 645     that the arguments of the option respect some constraints.
 646
 647     To do that the third argument must be a function pointer and the fourth
 648     argument must be some arbitrary parameter to this function needed
 649     to validate the constraint.
 650
 651     The constraint function must match the following prototype:
 652
 653     .. code-block:: c
 654
 655        int (*) (int nb_args, char ** args, char * value, char * parameter);
 656
 657     Where:
 658
 659       *nb_args*
 660         is the number which will be set to the number of arguments fol-
 661         lowing the command line parameter.
 662
 663       *args*
 664         is an array of nb_args strings containing theses arguments.
 665
 666       *value*
 667         is an arbitrary string containing the constraints which must be
 668         respected by args.
 669
 670       *parameter*
 671         is the parameter of which *value* is an argument.
 672
 673     Three constraint functions are built-in and are described below.
 674     They give examples on how to build them.
 675
 676     Example of constraint function using the built-it regular expression
 677     constraint checker function:
 678
 679     .. code-block:: c
 680
 681       ctxopt_add_opt_settings(constraints,
 682                               "opt1",
 683                               ctxopt_re_constraint,
 684                               "[^:]+:.+");
 685
 686
 687     In this example all the arguments of the option **opt1** must match
 688     the extended regular expression::
 689
 690       [^:]+:.+
 691
 692     See below for details about the function **ctxopt_re_constraint**.
 693
 694   before or after
 695     These settings allow to tell ctxopt than some options must be
 696     evaluated **before** or **after** a given option in a context.
 697     This can be useful, for example, if an action triggered by the
 698     evaluation of a option is required to be executed before the action
 699     of another option.
 700
 701     Example of **before** setting:
 702
 703     .. code-block:: c
 704
 705       ctxopt_add_opt_settings(before,
 706                               "opt1",
 707                               "opt2 opt3");
 708
 709     In this example, **opt2** and **opt3** will be evaluated *before*
 710     **opt1**.
 711     The relative order of **opt2** and **opt3** evaluations will still
 712     follow their order of appearance in the command line.
 713
 714     Example of **after** setting:
 715
 716     .. code-block:: c
 717
 718       ctxopt_add_opt_settings(after,
 719                               "opt2",
 720                               "opt3 opt4");
 721
 722     In this example, **opt3** and **opt4** will be evaluated *after*
 723     **opt2**.
 724     This example shows than we can combine multiple settings reusing
 725     options previously mentioned.
 726
 727     Incompatible setting combinations are not checked and will be ignored
 728     or lead to undefined behaviors.
 729
 730 |
 731
 732 * **int ctxopt_format_constraint(int** \
 733   *nb_args*\
 734   **, char **** \
 735   *args*\
 736   **, char *** \
 737   *value*\
 738   **, char *** \
 739   *parameter*\
 740   **);**
 741
 742   This pre-defined constraint function checks whether the arguments
 743   in *args* respect a C printf format given in value, `%2d` by e.g.
 744   It returns 1 if the checking is successful and 0 if not.
 745
 746 |
 747
 748 * **int ctxopt_re_constraint(int** \
 749   *nb_args*\
 750   **, char **** \
 751   *args*\
 752   **, char *** \
 753   *value*\
 754   **, char *** \
 755   *parameter*\
 756   **);**
 757
 758   Another pre-defined constraint function which checks if the arguments
 759   of an option respects the extended regular expression given in *value*.
 760
 761   It returns 1 if the arguments respects the constraint and 0 if this
 762   is not the case.
 763
 764 |
 765
 766 * **int ctxopt_range_constraint(int** \
 767   *nb_args*\
 768   **, char **** \
 769   *args*\
 770   **, char *** \
 771   *value*\
 772   **, char *** \
 773   *parameter*\
 774   **);**
 775
 776   Yet another pre-defined constraint function. This one checks if the
 777   arguments of an option are in in a specified ranges.
 778
 779   *value* must contain a string made of a maximum of 2 long integers
 780   separated by spaces.
 781
 782   The first or the second of these numbers can be replaced with the
 783   character '`.`'. In this case only the minimum or maximum is checked
 784   and the '`.`' equals to plus or minus infinity depending of this
 785   place in the string.
 786
 787   It returns 1 if the arguments respects the constraint and 0 if this
 788   is not the case.
 789
 790 |
 791
 792 * **void ctxopt_analyze(int** \
 793   *nb_words*\
 794   **, char **** \
 795   *words*\
 796   **, int *** \
 797   *rem_count*\
 798   **, char ***** \
 799   *rem_args*\
 800   **);**
 801
 802   This function processes the registered contexts instances tree, detects
 803   errors and possibly reorganizes the options order according
 804   to given priorities.
 805
 806   The first two arguments are similar to the *argc* and *argv* arguments
 807   of the main function but without counting `argv[0]`.
 808   Therefore, in many cases, *nb_words* will have the value of `argc-1`
 809   and *words* will have the value of `argv+1`.
 810
 811   The last two will receive the number of remaining (non analyzed)
 812   command line words and the array of these remaining words.
 813   Remaining words can be words appearing after ``--`` per example.
 814
 815   All errors are fatal and terminates the program with a return code
 816   greater then 0.
 817
 818   Example:
 819
 820   .. code-block:: c
 821
 822     int     res_argc;
 823     char ** res_argv;
 824     ...
 825     ctxopt_analyze(argc-1, argv+1, &res_argc, &res_argv);
 826
 827 |
 828
 829 * **void ctxopt_evaluate(void);**
 830
 831   This function walks through the tree of context instances previously
 832   built by **ctxopt_analyze** and launches the action attached to
 833   each options, if any, one after the other.
 834
 835 * **ctxopt_free_memory(void)**
 836
 837   This function frees the memory used internally by **ctxopt**.
 838
 839 ENVIRONMENT
 840 ===========
 841
 842 **ctxopt** is able to switch to debug mode if the variable CTXOPT_DEBUG
 843 is set to any not-empty value.
 844
 845 If this is the case, informational messages about how **ctxopt**
 846 analyses the command line are printed on the error output.
 847
 848 Each of them are prefixed with "CTXOPT_DEBUG: ".