/NOCLIP

Zig library for building posix-style command line interfaces

Primary LanguageZigISC LicenseISC

nearly obvious command line interface parser

A zig library for composing declarative command-line interfaces. Heavily inspired by click for Python.

Extemporaneous Bloviation

The alarm rings, and expletives spill from my mouth—instinctively, before any neuron has a chance to fire. You’d think this would get easier, having done it at least 12000 times, but I guess it just goes to show that practice does not necessarily converge on perfection, no matter what infinite limit t approaches. Eyes clamped shut against the encroaching underglow spilling from the curtains, I stretch my arms straight out from my sides and proceed to lose my balance, flying horizontally off of the mattress. An attempt at attitude control fails vigorously and I begin cartwheeling through open space, asserting a lopsided trajectory that intersects with the roof of the house. Passing through it unencumbered, I careen skyward and watch the ground recede into the distance, as the features of the landscape shrink and pop out of existence.

— George "Albert Einstein" Washington

Hello

Requires Zig 0.13.x. May work with 0.12.x.

Features

Warning
 NOCLIP is usable but not currently mature or well-tested. Unfinished features and bugs likely exist.

  • highly configurable short/long option and argument specification

    • named options can be associated with an environment variable

    • named flags, which take no value and can be biased true or false

    • multiple specification options, which can be provided many times to the CLI

    • overridable built-in conversion functions for standard types

    • required options that must be specified by the user

    • default values for options

  • arbitrarily nestable subcommands for building sophisticated tools

  • parser that supports many conventional CLI behaviors

    • congealed short flags (e.g. -abc is the same as -a -b -c)

    • -- to force early end of flag parsing

    • both --long value and --long=value styles are supported

  • option values are converted into rich native types using conversion callback functions

    • integers

    • basic tuple values

    • strings

    • enumerations as named choice sets

    • more to come

  • automatic help text generation and formatting

  • CLI specification and parser are built at compile time

Use

zig build demo for a demo. Otherwise just copy the file or use a submodule or something.

Usage: noclip-demo [options...] <arg> <subcommand ...>

  The definitive noclip demonstration utility

  This command demonstrates the functionality of the noclip library. cool!

Arguments:
  arg                         This is an argument that doesn't really do anything, but it's very
                              important.

Options:
  -t, --test <int> <int>      multi-value test option (env: NOCLIP_TEST)
  -c, --choice <choice>       enum choice option (env: NOCLIP_CHOICE) (default: demo.Choice.second)
  -d, --default <uint>        default value integer option (env: NOCLIP_DEFAULT) (default: 100)
  -m, --multi <u8>            multiple specification test option
  -f, --flag / -F, --no-flag  boolean flag (env: NOCLIP_FLAG)
  -M                          multiple specification test flag

Environment variables:
  NOCLIP_ENVIRON              environment variable only option

Subcommands:
  verb                        Perform some sort of work

LICENSE

INTERNET SOFTWARE CONSORTIUM LICENSE