Argtable3 Documentation

Argtable3 is a self-contained, single-file ANSI C library designed for robust CLI development. Key advantages include:

• GNU-style syntax: Supports standard command-line patterns.
• Declarative API: Define what the syntax looks like rather than how to parse it.
• Automated UI: Automatically generates consistent help messages and error handling.
• Portability: Written in ANSI C with no external dependencies; works on UNIX-like systems, Windows, and embedded systems.
• Ease of Integration: Can be used as a single-file library by dropping the source into your project.

Argtable3 provides a robust API for implementing multi-command interfaces (like git or docker) where a main application contains multiple individual commands, each with its own specific arguments and behavior.

To implement sub-commands, you follow a lifecycle of:

1. Initialization: Set up the sub-command system using arg_cmd_init.
2. Registration: Add sub-commands to the system using arg_cmd_register.
3. Dispatching: Use arg_cmd_dispatch to execute the logic associated with the sub-command identified in the user's input.
4. Cleanup: Teardown the system using arg_cmd_uninit.

Argtable3 provides a set of utility functions for managing dynamic, resizable strings. These are designed to simplify building and manipulating text (such as constructing command handler outputs) without requiring manual memory allocation or buffer size management.

Key capabilities include:

• Creation/Destruction: Initializing and releasing string resources.
• Resetting/Setting: Clearing contents or setting a new value.
• Concatenation: Appending strings, single characters, or formatted text.
• Access: Retrieving the underlying C-style string for use in standard C functions.

Argtable3 supports several specialized data types for command-line options. Each type has a corresponding set of functions for definition (typically suffixed with 0, 1, or n depending on the number of arguments or specific behavior):

• Boolean Flags: arg_lit_t (via arg_lit0, arg_lit1, arg_litn)
• Integers: arg_int_t (via arg_int0, arg_int1, arg_intn)
• Doubles (Floating Point): arg_dbl_t (via arg_dbl0, arg_dbl1, arg_dbln)
• Strings: arg_str_t (via arg_str0, arg_str1, arg_strn)
• Regular Expressions: arg_rex_t (via arg_rex0, arg_rex1, arg_rexn)
• File Paths: arg_file_t (via arg_file0, arg_file1, arg_filen)
• Dates: arg_date_t (via arg_date0, arg_date1, arg_daten)
• Custom/Remaining: arg_rem_t (via arg_rem)

To make Argtable3 available to all projects on your system, install it directly via the vcpkg CLI.

When using this method, do not hardcode the CMAKE_TOOLCHAIN_FILE in your CMakeLists.txt. Instead, pass it as a command-line argument to CMake so that different developers can point to their own vcpkg installation paths.

# Install the static library version
$ vcpkg install argtable3:x64-windows-static

# Configure CMake using the command line toolchain path
$ mkdir build
$ cd build
$ cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=D:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake
$ cmake --build .

Integrate Argtable3 into Meson projects using the WrapDB. This automates downloading and building the dependency via a .wrap file in your subprojects directory.

# Install the wrap file
$ meson wrap install argtable3

# In your meson.build
argtable3_dep = dependency('argtable3', version: '>=3.3.1')

executable('main', 'main.c', dependencies: [argtable3_dep])

# Build
$ meson setup build
$ meson compile -C build

To install Argtable3 globally via vcpkg, use the vcpkg install command. When using CMake, do not hardcode the CMAKE_TOOLCHAIN_FILE in your CMakeLists.txt; instead, pass it via the command line during configuration.

# Install globally
$ vcpkg install argtable3:x64-windows-static

# Configure CMake with global vcpkg
$ mkdir build && cd build
$ cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=D:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake
$ cmake --build .

The documentation is built by first running Doxygen to process API source files, and then using make html within the /docs directory to process the MyST source files via Sphinx.

Warning: The build system creates copies of .md files in the build directory. Sphinx errors and warnings refer to these copies, not the original version-controlled files. Do not edit the files referenced in error messages directly, as changes will not be saved to your source.

cd argtable3/docs
doxygen
make html

When a new version of Argtable3 is released, you must update the vcpkg registry to allow users to access it. This involves updating the port metadata, the build script, and the version database.

Workflow Overview

1. Prepare: Fork/clone vcpkg and create a new branch.
2. Modify Port Files: Update vcpkg.json (version) and portfile.cmake (URL and build commands).
3. Update Version Database: Use vcpkg x-add-version to automate hash calculation and database updates.
4. Test: Remove old versions and install the new port locally across different triplets.
5. Submit: Commit changes and open a Pull Request to microsoft/vcpkg.

# Example branch name
git checkout -b update-argtable3-to-3.3.0

To maintain or update the argtable3 recipe in the Conan Center Index, you must first set up a local environment with Git, Python, and Conan.

1. Install Conan using a Python virtual environment:

   python -m venv .venv
   # On Windows:
   .venv\Scripts\activate
   # On Linux/macOS:
   source .venv/bin/activate
   pip install conan

2. Fork and Clone the conan-io/conan-center-index repository on GitHub, then clone your fork locally.

3. Create a new branch for your version update:

   git checkout -b update-argtable3-to-3.3.0

The simplest and recommended way to use Argtable3 is to embed the amalgamation source files (argtable3.c and argtable3.h) directly into your project. This avoids the complexity of building the library separately and allows the compiler to perform better inter-procedure optimizations.

Note: Amalgamation files are not included in the main repository. You can obtain them by:

1. Downloading the amalgamation distribution from the release page (e.g., argtable-<version>-amalgamation.zip or .tar.gz).
2. Generating the distribution yourself using the tool in the tools directory:
   • Navigate to the tools directory.
   • Run ./build dist to generate the files in the <ROOT>/dist directory.

# Generate amalgamation files if building from source
cd tools
./build dist

Argtable3 is a single-file ANSI-C library. To integrate it, add argtable3.c to your project files and include argtable3.h in your source code.

/* Include the header in your C source */
#include "argtable3.h"

/* Add argtable3.c to your compilation unit/build system */