C++ API

First, create an instance of the UCLI::Parser class which looks like this:

class Parser
{
public:
    Parser() noexcept = default;

    Parser& setHelpHeader(const char* header) noexcept;
    Parser& setHelpFooter(const char* footer) noexcept;
    Parser& setUseGeneratedHelp(bool bUseGeneratedHelp) noexcept;
    Parser& setHelpSubcommandIndentationSpaces(size_t indentSpaces) noexcept;

    Parser& setArrayDelimiter(char delimiter) noexcept;
    Parser& setFlagPrefix(char prefix) noexcept;

    Parser& setBoolToggle(bool bToggle) noexcept;

    Parser& pushCommand(const Command& command) noexcept;
    Parser& pushFlag(const Flag& flag) noexcept;

    Parser& pushDefaultCommand(const Command& command) noexcept;
    Parser& pushDefaultFlag(const Flag& flag) noexcept;

    Parser& parse(int argc, char** argv) noexcept;
    Parser& release() noexcept;
    ~Parser() noexcept;
};

Commands

Commands are arguments like help or h. They can have subcommands and flags. A command looks like this:

struct UCLI_Command
{
    const char* longName;
    char shortName;
    const char* description;

    char** defaultValues;
    size_t defaultValuesCount;

    union
    {
        struct
        {
            char** stringValues;
            size_t stringValuesCount;
        } stringValues;
        bool* boolValue;
    };
    UCLI_CommandType type;

    UCLI_Command* subcommands;
    size_t subcommandsCount;

    UCLI_Flag* flags;
    size_t flagsCount;

    UCLI_CommandEvent callback;
    void* context;
};

The members are as follows:

longName - The long name of the command(help). Set to nullptr to not use it
shortName - The short name of the command(h). Set to \0 to not use it
description - A description of the command. Used only if you're using the generated help message
defaultValues & defaultValuesCount - An array of default value strings that will be set in case no value is assigned to the given command. Boolean commands are not covered, due to them already having a default value
type - Your command type. One of UCLI_COMMAND_TYPE_VOID, UCLI_COMMAND_TYPE_BOOL, UCLI_COMMAND_TYPE_STRING or UCLI_COMMAND_TYPE_ARRAY.
Data:
- boolType - If the type is set to UCLI_COMMAND_TYPE_BOOL this value will be toggled if the command is run
- stringValues & stringValuesCount - A list of string values that is filled if the command type is UCLI_COMMAND_TYPE_STRING or UCLI_COMMAND_TYPE_ARRAY
callback - A callback function that is called when the command is selected
context - A void* to a user-defined context variable
subcommands & subcommandsCount - A list of child commands
flags & flagsCount - A list of child flags

Top-level commands can be added using the UCLI::Parser::pushCommand function.

If a command is unrecognised, we use the default command. Use the UCLI::Parser::pushDefaultCommand() function to set the default command.

Warning

If the default command is not set and you have stated that you use the generated help command, then the default command will automatically be set to the help command

Flags

Flags are arguments which start with a -. For example --flag, -f or -faBcD.

Flags have the same structure as commands and are pushed using their respective functions. The only difference is that flags cannot have child commands and child flags of their own.

Configuration

Help

The library supports automatically generating a help message from your command schema. It is accessible using the -h/--help flags and help/h commands.

We automatically generate these commands by default, though you can control whether we generate this command using the setUseGeneratedHelp(bool) method.

We also allow you to print a header and a footer for your help message using the setHelpHeader(const char*) and setHelpFooter(const char*) respectively.

Array delimiter

By default, we use , as the delimiter for inline array arguments(--files=file1,file2,file3), however you are free to change the delimeter using the setArrayDelimeter(const char*) command;

Flag prefix

If you don't want to use the - character for flags, you can change the flag prefix character using the UCLI::Parser::setFlagPrefix(char) function.

Boolean toggling

By default we set boolean arguments to true if they are encountered and not assigned to explicitly. However, you can change this behavior to toggling the boolean instead using the UCLI::Parser::setBoolToggle() function.

Parsing

Once you have configured the parser, simply run UCLI::Parser::parse(int, char**). Once this function returns, you can use the replaced data from your provided schema.

Once you are done using the data provided by your UCLI::Parser instance, you can run UCLI::Parser::release() or wait until the parser goes out of scope to automatically free all data through the destructor.

C API

The C API is the same as the C++ API, except the C API prefixes all functions with UCLI_Parser_ and you need to allocate and free a parser instance manually using the UCLI_Parser_init() and UCLI_Parser_free() functions.