{"id":20751453,"url":"https://github.com/p-gen/ctxopt","last_synced_at":"2025-04-28T13:33:08.288Z","repository":{"id":222028477,"uuid":"249561632","full_name":"p-gen/ctxopt","owner":"p-gen","description":"Options parser for simple or complex command lines. Take a look at the smenu project for an example of use.","archived":false,"fork":false,"pushed_at":"2022-06-19T22:25:54.000Z","size":924,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T10:04:46.044Z","etag":null,"topics":["api","c","command-line","command-line-parser","getopt"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/p-gen.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.rst","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-03-23T22:51:07.000Z","updated_at":"2025-02-20T10:11:17.000Z","dependencies_parsed_at":"2024-02-11T21:54:56.345Z","dependency_job_id":null,"html_url":"https://github.com/p-gen/ctxopt","commit_stats":null,"previous_names":["p-gen/ctxopt"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-gen%2Fctxopt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-gen%2Fctxopt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-gen%2Fctxopt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-gen%2Fctxopt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/p-gen","download_url":"https://codeload.github.com/p-gen/ctxopt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251319932,"owners_count":21570476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","c","command-line","command-line-parser","getopt"],"created_at":"2024-11-17T08:33:37.799Z","updated_at":"2025-04-28T13:33:08.002Z","avatar_url":"https://github.com/p-gen.png","language":"C","readme":"**ctxopt**: yet another command line options manager.\n#####################################################\n\n|\n\nFor many uses, the traditional getopt function is enough to parse the\noptions in command lines.\n\nHowever, cases exist where getopt shows its limits.\n**ctxopt** is able to manage complex configurations of command line\noptions and excels when they appear in structured or independent blocs.\n\nIn **ctxopt**, each option has the possibility of starting a new context\nin which the following command line options will be taken into account\nand analyzed.\nWith this concept, it becomes easy, for example, to have repetitions\nof identical options with each their independent sub-options.\n\nFeatures:\n---------\n\n**ctxopt** has many features, its main ones are:\n\n- Options are organized in a hierarchy of contexts.\n- Options are easily declared using a syntax similar to BNF notation in\n  each context.\n- Any number of parameters can be assigned to each option.\n- Parameters are not limited to just one character.\n- The parameters associated with an option can be abbreviated as long as\n  they do not conflict with another option in the same context.\n- Parameters can be aggregated, even the long ones.\n- Options evaluations trigger user-defined functions.\n- Options can appear multiple times in one or more contexts.\n- Options can be optional or mandatory.\n- Option arguments can be optional or mandatory.\n- Arguments can be multiple and their number controlled by simple rules.\n- Arguments can have user-defined or built-in constraints.\n- Options marked as mutually incompatibles are automatically detected.\n- Command line options are normally evaluated in order but can be forced\n  to be evaluated at the start of a context. They can also be asked to\n  be reordered automatically to be evaluated before or after a set of\n  other options in a context.\n- Error functions can be customized.\n- Automatic detection of missing|incompatible|unknown|... options or\n  parameters.\n\nContext notion illustrated by a tiny example:\n---------------------------------------------\n\nImagine a situation where you want an option to be allowed only if\nanother option was previously given.\n\nFor example, you want the *group* option to be allowed only after\na *user* option.\n\nWith **ctxopt** its easy, you just have to define two contexts (at least one\nis mandatory), tell the *user* option to switch to the second context\n(named ``ctx1`` here) and define the *group* option in the second context.\n\n+------------------+-----------------+--------------+-------------------+\n| Defined contexts | Allowed options | Next context | Option parameters |\n+==================+=================+==============+===================+\n| ``main``         | user            | ``ctx1``     | ``-u`` ``-user``  |\n+------------------+-----------------+--------------+-------------------+\n| ``ctx1``         | group           |              | ``-g`` ``-group`` |\n+------------------+-----------------+--------------+-------------------+\n\nAccording to the situation summarized in this table, the following\ncommand line (the context changes in brackets have been added only for\nunderstanding and not part of the command line)\n\n.. parsed-literal::\n  prog[main] -u[ctx1] u1 -g g1 g2 -user[ctx1] u2 -group g3\n\nwill be understood as:\n\n.. parsed-literal::\n  Context main:  prog -u u1          -user u2\n  Context ctx1:             -g g1 g2          -group g3\n\nIn this example, you can see that the previous context (``main`` here) is\nautomatically re-entered after the analysis of the *group* option because\nthe *user* option is unknown in the ``ctx1`` context.\n\nSee the file **example1.c** in the **examples** directory for details.\n\nUsage:\n------\n\nTo use **ctxopt**, the users must at least:\n\n- include **ctxopt.h** and **ctxopt.c** in his code.\n- define at least one context and describe its options.\n- set at least one parameter's name for the options described in the contexts.\n- write and attach an action callback function to each options.\n- possibly register constraint and other things (optional).\n- call ``ctxopt_init``.\n- call ``ctxopt_analyze``.\n- call ``ctxopt_evaluate``.\n\nOptional steps include:\n\n- register entering and/or exiting function for contexts.\n- register arguments constraint checking functions.\n- redefine non internal error functions.\n\nFor more, please read the provided man page.\n\nEnough theory, here is a basic Hello World example:\n---------------------------------------------------\n\n.. code:: c\n  :number-lines:\n\n  #include \"ctxopt.h\"\n  #include \u003cstdio.h\u003e\n  #include \u003cstdlib.h\u003e\n  #include \u003cstring.h\u003e\n\n  /* Callback functions */\n  /* ****************** */\n\n  void name_action(char * ctx_name, char * opt_name, char * param,\n                   int nb_values, char ** values, int nb_opt_data,\n                   void ** opt_data, int nb_ctx_data, void** ctx_data)\n  {\n    int v;\n\n    printf(\"Hello %s\", values[0]); /* First command line argument after name *\n                                    | (-n or -name).                         */\n\n    for (v = 1; v \u003c nb_values; v++) /* Other command line arguments.         */\n      printf(\", %s\", values[v]);\n\n    printf(\".\\n\");\n  }\n\n  /* Program entry */\n  /* ************* */\n\n  int main(int argc, char * argv[])\n  {\n    int     nb_rem_args = 0;    /* Nb of remaining unprocessed arguments. */\n    char ** rem_args    = NULL; /* Remaining arguments string array.      */\n\n    ctxopt_init(argv[0], \"stop_if_non_option=Yes allow_abbreviations=Yes\");\n    ctxopt_new_ctx(\"main\", \"[name... #\u003cstring\u003e...]\");\n    ctxopt_add_opt_settings(parameters, \"name\", \"-n -name\");\n    ctxopt_add_opt_settings(actions, \"name\", name_action, NULL);\n    ctxopt_analyze(argc - 1, argv + 1, \u0026nb_rem_args, \u0026rem_args);\n\n    if (nb_rem_args \u003e 0)\n    {\n      printf(\"Non-arguments are not allowed.\\n\");\n      exit(EXIT_FAILURE);\n    }\n\n    ctxopt_evaluate();\n\n    if (argc == 1)\n      printf(\"Hello world.\\n\");\n\n    exit(EXIT_SUCCESS);\n  }\n\nCode explanations:\n..................\n\nLine 1:\n\n  This ``#include`` gives access to the API necessary to use **ctxopt**.\n\nLine 9:\n\n  This function is the callback function call each time a parameter\n  associated with the option **name** is seen in the command line.\n\nLine 32:\n\n  The init function is mandatory and must be called first.\n\nLine 33:\n\n  Here the first (and unique here) context called **main** here is\n  created with the description of an option called **name**.\n\n  The **name** option is defined as an optional possible multiple option\n  taking mandatory possibly multiple arguments.\n  It is the ``#`` which indicates the presence of an argument,\n  ``\u003cstring\u003e`` is just a decaration to clarify the meaning of this\n  argument.\n\nLine 34:\n\n  It's now time to introduce the two parameters of the option **name**.\n  These are the parameters looked for in the command line.\n\nLine 35:\n\n  Here the callback function defined line 9 is associated with the option\n  **name**.\n\nLine 36:\n\n  Here the command line is parsed and errors like unknown parameter, not\n  enough arguments... are detected. All errors detected during this phase\n  are fatal.\n\nLine 38:\n\n  The remaining non-arguments, if any, are managed here.\n\nLine 44:\n\n  All the internal representation of the command line built during the\n  analysis phase (line 36) is finally evaluated and the callback\n  registered functions (here **name_action**) called.\n\nLine 46:\n\n  The special case where the command line only contains the program name\n  is treated here.\n\nExamples of running session:\n............................\n\n.. parsed-literal::\n\n  **$ ./hello -n Alice Bob -name Carol**\n  Hello Alice, Bob.\n  Hello Carol.\n\n  **$ ./hello -n**\n  -n requires argument(s).\n\n  Synopsis:\n  hello \\\n    [-n|-name... #\u003cstring\u003e...]\n\n  Syntactic explanations:\n  Only the parameters (prefixed by -) and the arguments, if any, must be entered.\n  The following is just there to explain the other symbols displayed.\n\n  #tag         : argument tag giving a clue to its meaning.\n  [...]        : the object between square brackets is optional.\n  ...          : the previous object can be repeated more than one time.\n\n  **$ ./hello**\n  Hello world.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp-gen%2Fctxopt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp-gen%2Fctxopt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp-gen%2Fctxopt/lists"}