From 5365f8fa8d6ebfbf3ba92816abe55a99feff6f25 Mon Sep 17 00:00:00 2001 From: Jack Jamison Date: Wed, 22 Jul 2026 09:09:18 -0400 Subject: clean up --- snag/src/libargs/args.h | 217 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 snag/src/libargs/args.h (limited to 'snag/src/libargs/args.h') diff --git a/snag/src/libargs/args.h b/snag/src/libargs/args.h new file mode 100644 index 0000000..ea91142 --- /dev/null +++ b/snag/src/libargs/args.h @@ -0,0 +1,217 @@ +// ----------------------------------------------------------------------------- +// Args: a C99 library for parsing command line arguments. +// Version: 3.3.0 +// ----------------------------------------------------------------------------- + +#ifndef args_h +#define args_h + +#include + +// ----------------------------------------------------------------------------- +// Types. +// ----------------------------------------------------------------------------- + +// An ArgParser instance stores registered flags, options and commands. +typedef struct ArgParser ArgParser; + +// A callback function should accept two arguments: the command's name and the +// command's ArgParser instance. It should return an integer status code. +typedef int (*ap_callback_t)(char* cmd_name, ArgParser* cmd_parser); + +// ----------------------------------------------------------------------------- +// Initialization, parsing, teardown. +// ----------------------------------------------------------------------------- + +// Allocates and initializes a new ArgParser instance. Returns NULL if memory +// allocation fails. +ArgParser* ap_new_parser(void); + +// Specifies a helptext string for the parser. If [helptext] is not NULL, this +// activates an automatic --help/-h flag. (Either --help or -h can be overridden +// by explicitly registered flags.) The parser stores and manages its own copy +// of the [helptext] string so [helptext] can be freed immediately after this +// call if it was dynamically constructed. +void ap_set_helptext(ArgParser* parser, const char* helptext); + +// Returns a pointer to the parser's helptext string. +char* ap_get_helptext(ArgParser* parser); + +// Specifies a version string for the parser. If [version] is not NULL, this +// activates an automatic --version/-v flag. (Either --version or -v can be +// overridden by explicitly registered flags.) The parser stores and manages its +// own copy of the [version] string so [version] can be freed immediately after +// this call if it was dynamically constructed. +void ap_set_version(ArgParser* parser, const char* version); + +// Returns a pointer to the parser's version string. +char* ap_get_version(ArgParser* parser); + +// Parses an array of string arguments. +// - Exits with an error message and a non-zero status code if the arguments are +// invalid. +// - The parameters are assumed to be [argc] and [argv] as supplied to main(), +// i.e. the first element of the array is assumed to be the binary name and +// is therefore ignored. +// - Returns true if the arguments were successfully parsed. +// - Returns false if parsing failed because sufficient memory could not be +// allocated. +bool ap_parse(ArgParser* parser, int argc, char** argv); + +// Frees the memory associated with the parser and any subparsers. +void ap_free(ArgParser* parser); + +// ----------------------------------------------------------------------------- +// Parsing modes. +// ----------------------------------------------------------------------------- + +// If set, the first positional argument ends option-parsing; all subsequent +// arguments will be treated as positionals. +void ap_first_pos_arg_ends_option_parsing(ArgParser* parser); + +// If set, all arguments will be treated as positionals. +void ap_all_args_as_pos_args(ArgParser* parser); + +// ----------------------------------------------------------------------------- +// Register flags and options. +// ----------------------------------------------------------------------------- + +// Registers a new flag. +void ap_add_flag(ArgParser* parser, const char* name); + +// Registers a new string-valued option. +void ap_add_str_opt(ArgParser* parser, const char* name, const char* fallback); + +// Registers a new integer-valued option. +void ap_add_int_opt(ArgParser* parser, const char* name, int fallback); + +// Registers a new double-valued option. +void ap_add_dbl_opt(ArgParser* parser, const char* name, double fallback); + +// Registers a new greedy string-valued option. +void ap_add_greedy_str_opt(ArgParser* parser, const char* name); + +// ----------------------------------------------------------------------------- +// Inspect flags and options. +// ----------------------------------------------------------------------------- + +// Returns the number of times the specified flag or option was found. +int ap_count(ArgParser* parser, const char* name); + +// Returns true if the specified flag or option was found. +bool ap_found(ArgParser* parser, const char* name); + +// Returns the value of a string option. +char* ap_get_str_value(ArgParser* parser, const char* name); + +// Returns the string value at the specified index. +char* ap_get_str_value_at_index(ArgParser* parser, const char* name, int index); + +// Returns the value of an integer option. +int ap_get_int_value(ArgParser* parser, const char* name); + +// Returns the integer value at the specified index. +int ap_get_int_value_at_index(ArgParser* parser, const char* name, int index); + +// Returns the value of a floating-point option. +double ap_get_dbl_value(ArgParser* parser, const char* name); + +// Returns the floating-point value at the specified index. +double ap_get_dbl_value_at_index(ArgParser* parser, const char* name, int index); + +// Returns an option's values as a freshly-allocated array of string +// pointers. The array's memory is not affected by calls to ap_free(). +// Returns NULL if memory allocation fails. +char** ap_get_str_values(ArgParser* parser, const char* name); + +// Returns an option's values as a freshly-allocated array of integers. +// The array's memory is not affected by calls to ap_free(). +// Returns NULL if memory allocation fails. +int* ap_get_int_values(ArgParser* parser, const char* name); + +// Returns an option's values as a freshly-allocated array of doubles. +// The array's memory is not affected by calls to ap_free(). +// Returns NULL if memory allocation fails. +double* ap_get_dbl_values(ArgParser* parser, const char* name); + +// ----------------------------------------------------------------------------- +// Positional arguments. +// ----------------------------------------------------------------------------- + +// Returns true if the parser has found one or more positional arguments. +bool ap_has_args(ArgParser* parser); + +// Returns the number of positional arguments. +int ap_count_args(ArgParser* parser); + +// Returns the positional argument at the specified index. +char* ap_get_arg_at_index(ArgParser* parser, int index); + +// Returns the positional arguments as a freshly-allocated array of string +// pointers. The memory occupied by the returned array is not affected by +// calls to ap_free(). Returns NULL if memory allocation fails. +char** ap_get_args(ArgParser* parser); + +// Attempts to parse and return the positional arguments as a freshly allocated +// array of integers. Exits with an error message on failure. The memory +// occupied by the returned array is not affected by calls to ap_free(). +// Returns NULL if memory allocation fails. +int* ap_get_args_as_ints(ArgParser* parser); + +// Attempts to parse and return the positional arguments as a freshly allocated +// array of doubles. Exits with an error message on failure. The memory +// occupied by the returned array is not affected by calls to ap_free(). +// Returns NULL if memory allocation fails. +double* ap_get_args_as_doubles(ArgParser* parser); + +// ----------------------------------------------------------------------------- +// Commands. +// ----------------------------------------------------------------------------- + +// Registers a new command. Returns the ArgParser instance for the command. +// Returns NULL if sufficient memory cannot be allocated for the new parser. +ArgParser* ap_new_cmd(ArgParser* parent_parser, const char* name); + +// Registers a callback function on a command parser. +void ap_set_cmd_callback(ArgParser* cmd_parser, ap_callback_t cmd_callback); + +// Returns true if [parent_parser] has found a command. +bool ap_found_cmd(ArgParser* parent_parser); + +// If [parent_parser] has found a command, returns its name, otherwise NULL. +char* ap_get_cmd_name(ArgParser* parent_parser); + +// If [parent_parser] has found a command, returns its ArgParser instance, +// otherwise NULL. +ArgParser* ap_get_cmd_parser(ArgParser* parent_parser); + +// If [parent_parser] has found a command, and if that command has a callback +// function, returns the exit code from the callback, otherwise 0. +int ap_get_cmd_exit_code(ArgParser* parent_parser); + +// This boolean switch toggles support for an automatic 'help' command that +// prints subcommand helptext. The value defaults to false but gets toggled +// automatically to true whenever a command is registered. You can use this +// function to disable the feature if required. +void ap_enable_help_command(ArgParser* parent_parser, bool enable); + +// If [parser] has a parent -- i.e. if [parser] is a command parser -- returns +// its parent, otherwise NULL. +ArgParser* ap_get_parent(ArgParser* parser); + +// ----------------------------------------------------------------------------- +// Utilities. +// ----------------------------------------------------------------------------- + +// Dumps a parser instance to stdout for debugging. +void ap_print(ArgParser* parser); + +// Returns true if an attempt to allocate memory failed. +bool ap_had_memory_error(ArgParser* parser); + +// Returns the argument supplied at index-zero to the root parser. Typically +// this is the filepath of the binary. This function can be called on the root +// parser or any command sub-parser. +char* ap_get_zeroth_root_arg(ArgParser* parser); + +#endif -- cgit v1.2.3