From 2cb3c3df4099297b0a0554bb482e2de04fe86b5c Mon Sep 17 00:00:00 2001 From: sanine Date: Wed, 24 Aug 2022 00:02:17 -0500 Subject: add command-line arguments --- libs/cargs/docs/reference/cag_option_fetch.md | 32 +++++++++++++++++++++++ libs/cargs/docs/reference/cag_option_get.md | 26 ++++++++++++++++++ libs/cargs/docs/reference/cag_option_get_index.md | 29 ++++++++++++++++++++ libs/cargs/docs/reference/cag_option_get_value.md | 27 +++++++++++++++++++ libs/cargs/docs/reference/cag_option_prepare.md | 30 +++++++++++++++++++++ libs/cargs/docs/reference/cag_option_print.md | 28 ++++++++++++++++++++ libs/cargs/docs/reference/index.md | 30 +++++++++++++++++++++ 7 files changed, 202 insertions(+) create mode 100755 libs/cargs/docs/reference/cag_option_fetch.md create mode 100755 libs/cargs/docs/reference/cag_option_get.md create mode 100755 libs/cargs/docs/reference/cag_option_get_index.md create mode 100755 libs/cargs/docs/reference/cag_option_get_value.md create mode 100644 libs/cargs/docs/reference/cag_option_prepare.md create mode 100755 libs/cargs/docs/reference/cag_option_print.md create mode 100644 libs/cargs/docs/reference/index.md (limited to 'libs/cargs/docs/reference') diff --git a/libs/cargs/docs/reference/cag_option_fetch.md b/libs/cargs/docs/reference/cag_option_fetch.md new file mode 100755 index 0000000..331ac20 --- /dev/null +++ b/libs/cargs/docs/reference/cag_option_fetch.md @@ -0,0 +1,32 @@ +--- +title: cag_option_fetch +description: Fetches an option from the argument list. +--- + +_(since v1.0.0)_ +Fetches an option from the argument list. + +## Description +```c +bool cag_option_fetch(cag_option_context *context); +``` + +This function fetches a single option from the argument list. The context +will be moved to that item. Information can be extracted from the context +after the item has been fetched. +The arguments will be re-ordered, which means that non-option arguments will +be moved to the end of the argument list. After all options have been +fetched, all non-option arguments will be positioned after the index of +the context. + +## Parameters + * **context**: The context from which we will fetch the option. + +## Return Value +Returns true if there was another option or false if the end is reached. + +## Changelog + +| Version | Description | +|------------|--------------------------------------------------------| +| **v1.0.0** | The function is introduced. | diff --git a/libs/cargs/docs/reference/cag_option_get.md b/libs/cargs/docs/reference/cag_option_get.md new file mode 100755 index 0000000..8777744 --- /dev/null +++ b/libs/cargs/docs/reference/cag_option_get.md @@ -0,0 +1,26 @@ +--- +title: cag_option_get +description: Gets the identifier of the option. +--- + +_(since v1.0.0)_ +Gets the identifier of the option. + +## Description +```c +char cag_option_get(const cag_option_context *context); +``` +This function gets the identifier of the option, which should be unique to +this option and can be used to determine what kind of option this is. + +## Parameters + * **context**: The context from which the option was fetched. + +## Return Value +Returns the identifier of the option. + +## Changelog + +| Version | Description | +|------------|--------------------------------------------------------| +| **v1.0.0** | The function is introduced. | diff --git a/libs/cargs/docs/reference/cag_option_get_index.md b/libs/cargs/docs/reference/cag_option_get_index.md new file mode 100755 index 0000000..ef27d88 --- /dev/null +++ b/libs/cargs/docs/reference/cag_option_get_index.md @@ -0,0 +1,29 @@ +--- +title: cag_option_get_index +description: Gets the current index of the context. +--- + +_(since v1.0.0)_ +Gets the current index of the context. + +## Description +```c +int cag_option_get_index(const cag_option_context *context); +``` + +This function gets the index within the argv arguments of the context. The +context always points to the next item which it will inspect. This is +particularly useful to inspect the original argument array, or to get +non-option arguments after option fetching has finished. + +## Parameters + * **context**: The context from which the option was fetched. + +## Return Value +Returns the current index of the context. + +## Changelog + +| Version | Description | +|------------|--------------------------------------------------------| +| **v1.0.0** | The function is introduced. | diff --git a/libs/cargs/docs/reference/cag_option_get_value.md b/libs/cargs/docs/reference/cag_option_get_value.md new file mode 100755 index 0000000..462e2e7 --- /dev/null +++ b/libs/cargs/docs/reference/cag_option_get_value.md @@ -0,0 +1,27 @@ +--- +title: cag_option_get_value +description: Gets the value from the option. +--- + +_(since v1.0.0)_ +Gets the value from the option. + +## Description +```c +const char *cag_option_get_value(const cag_option_context *context); +``` + +This function gets the value from the option, if any. If the option does not +contain a value, this function will return NULL. + +## Parameters + * **context**: The context from which the option was fetched. + +## Return Value +Returns a pointer to the value or NULL if there is no value. + +## Changelog + +| Version | Description | +|------------|--------------------------------------------------------| +| **v1.0.0** | The function is introduced. | diff --git a/libs/cargs/docs/reference/cag_option_prepare.md b/libs/cargs/docs/reference/cag_option_prepare.md new file mode 100644 index 0000000..c9aa9e5 --- /dev/null +++ b/libs/cargs/docs/reference/cag_option_prepare.md @@ -0,0 +1,30 @@ +--- +title: cag_option_prepare +description: Prepare argument options context for parsing. +--- + +_(since v1.0.0)_ +Prepare argument options context for parsing. + +## Description +```c +void cag_option_prepare(cag_option_context *context, const cag_option *options, + size_t option_count, int argc, char **argv); +``` + +This function prepares the context for iteration and initializes the context +with the supplied options and arguments. After the context has been prepared, +it can be used to fetch arguments from it. + +## Parameters + * **context**: The context which will be initialized. + * **options**: The registered options which are available for the program. + * **option_count**: The amount of options which are available for the program. + * **argc**: The amount of arguments the user supplied in the main function. + * **argv**: A pointer to the arguments of the main function. + +## Changelog + +| Version | Description | +|------------|--------------------------------------------------------| +| **v1.0.0** | The function is introduced. | diff --git a/libs/cargs/docs/reference/cag_option_print.md b/libs/cargs/docs/reference/cag_option_print.md new file mode 100755 index 0000000..c4531eb --- /dev/null +++ b/libs/cargs/docs/reference/cag_option_print.md @@ -0,0 +1,28 @@ +--- +title: cag_option_print +description: Prints all options to the terminal. +--- + +_(since v1.0.0)_ +description: Prints all options to the terminal. + +## Description +```c +void cag_option_print(const cag_option *options, size_t option_count, + FILE *destination); +``` + +This function prints all options to the terminal. This can be used to generate +the output for a "--help" option. + +## Parameters + * **options**: The options which will be printed. + * **option_count**: The option count which will be printed. + * **destination**: The destination where the output will be printed. + + +## Changelog + +| Version | Description | +|------------|--------------------------------------------------------| +| **v1.0.0** | The function is introduced. | diff --git a/libs/cargs/docs/reference/index.md b/libs/cargs/docs/reference/index.md new file mode 100644 index 0000000..654d9fe --- /dev/null +++ b/libs/cargs/docs/reference/index.md @@ -0,0 +1,30 @@ +--- +title: Reference +description: A complete reference of the cargs command line arguments parser library for C/C++. +--- + +## Basic +The basic functions available in cargs, which can be used to do basic command line argument parsing. + +### Functions +* **[cag_option_prepare]({{ site.baseurl }}{% link reference/cag_option_prepare.md %})** +Prepare argument options context for parsing. + +* **[cag_option_fetch]({{ site.baseurl }}{% link reference/cag_option_fetch.md %})** +Fetches an option from the argument list. + +* **[cag_option_get]({{ site.baseurl }}{% link reference/cag_option_get.md %})** + Gets the identifier of the option. + +* **[cag_option_get_value]({{ site.baseurl }}{% link reference/cag_option_get_value.md %})** +Gets the value from the option. + +* **[cag_option_get_index]({{ site.baseurl }}{% link reference/cag_option_get_index.md %})** +Gets the current index of the context. + +## Output +This section describes functions which are used to output argument information. + +### Functions +* **[cag_option_print]({{ site.baseurl }}{% link reference/cag_option_print.md %})** +Prints all options to the terminal. -- cgit v1.2.1