# cligen

**Repository Path**: ttsu00/cligen

## Basic Information

- **Project Name**: cligen
- **Description**: One-stop code and documentation generator for CLI (command-line interface) tools written in C
- **Primary Language**: Unknown
- **License**: LGPL-2.1
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-10-14
- **Last Updated**: 2024-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cligen

One-stop code and documentation generator for CLI (command-line
interface) tools written in C.

## Why?

This project was born during the process of
[migrating](https://gitlab.com/gnutls/gnutls/-/milestones/23#tab-issues)
the GnuTLS CLI infrastructure from GNU
[AutoGen](https://www.gnu.org/software/autogen/).  Several other tools
had been considered but none of them satisfied the following
requirements:

- The generator produces option parsing code and documentation from
  the same specification
- The generator is written and works with minimal (build-)dependencies
- The generated code works without separate runtime library

## Usage

### Writing the JSON specification

See [certtool example](fixtures/input/certtool-options.json).  The
schema is defined in [cligen.schema.json](cligen.schema.json) so you
can validate your specification with:

```console
$ jsonschema --error-format "ERROR: {error.path} {error.message}" \
             --instance your-options.json cligen.schema.json
```

after installing python3-jsonschema package.

### Generating the code and documentation

To generate command-line parser code (based on getopt) from JSON
specification:

```console
$ PYTHONPATH=. ./cli-codegen.py --package YOUR_PACKAGE --version YOUR_VERSION \
                                your-options.json foo.c foo.h
```

To generate man page from JSON specification:

```console
$ PYTHONPATH=. ./cli-docgen.py --format man \
                               --package YOUR_PACKAGE --version YOUR_VERSION \
                               your-options.json foo.1
```

To generate texinfo documentation from JSON specification:

```console
$ PYTHONPATH=. ./cli-docgen.py --format texi \
                               --package YOUR_PACKAGE --version YOUR_VERSION \
                               your-options.json foo.texi
```

### Integrating the infrastructure into your project

The easiest way would be to embed the cligen project as a git
submodule.  To make it easy to integrate with Automake, a helper
Makefile is provided, which can be included from the top-level
Makefile.am:

```console
$ git submodule add https://gitlab.com/gnutls/cligen.git
$ cat Makefile.am
include $(top_srcdir)/cligen/cligen.mk
noinst_PYTHON += $(cligen_sources)
```

### Using the generated code from your program

Include the generated header file (`*.h`) and link to the generated
source file (`*.c`).  To parse command line arguments, call
`parse_options` function defined as:

```c
int process_options (int argc, char **argv);
```

To check the option status, use:

- `HAVE_OPT(name)`: expands to the option presence (`true` or `false`)
- `OPT_ARG(name)`: expands to the option argument (string or integer,
  depending on the specification
- `ENABLED_OPT(name)`: expands to the option enablement status (`true`
  or `false`)
- `OPTS_COUNT(name)`: expands to the count of occurrences of the
  option, if it is defined as `multiple`
- `OPTS_ARRAY(name)`: expands to the array of option arguments, if the
  option is defined as `multiple` and takes an argument.

## TODO

- Add different flavors of codegen output other than `getopt` ([argp](https://www.gnu.org/software/libc/manual/html_node/Argp.html), GLib [OptionContext](https://docs.gtk.org/glib/struct.OptionContext.html))

## License

LGPL-2.1-or-later