Cova - Commands, Options, Values, Arguments

Showcase
1

Hey all,

I’ve just released the latest version of my library, Cova v0.8.0, and figured it’s a good time to share it here.

Cova is a cross-platform command line argument parsing library for Zig. My design focus for this library has been simple integration into any project with deep, robust customization if needed. A few standout features include:

  • Command, Option, and Value Types that all arguments are parsed to. These types can each be configured during comptime in a standardized way to meet the needs of a project.
  • Those Types can be converted from and to Structs, Unions, and Functions for easy integration with existing code, or created from scratch for more customization.
  • The library is POSIX compliant by default, but can easily be configured to match different argument styles.

If you’d like to check it out, the above link is a good starting point along with the API Docs, Guides, and this Basic App example. (Due to a 2 link limit, I couldn’t link the API Docs and Guides, but they can be found on the GitHub link.)

Hopefully this can help you in your next CLI project, and if you do check it out any feedback is greatly appreciated!

16 Likes
2

Welcome to the forum @00JCIV00, and thanks for sharing your work!

1 Like
3

I just realised I’m doing basically the same thing lol! Yours is much more complete though. Good work!

1 Like
4

Appreciate that. Also, there’s no harm in having options! If you want to pass a link to yours, I can put it in the “Alternatives” section of Cova’s readme.

1 Like
5

I’ve just finished up Cova’s v0.9.0 release. This version adds new ways to customize your CLI projects and better ways to parse input from end users. It also fixes several issues and introduces some great optimizations for binary size and memory usage. Details below:

v0.9.0

New Features

  • Implemented Argument Groups to help organize Arguments for Usage/Help messages and analysis.
  • Implemented Aliases for Commands & Options and Value Child Types.
  • Added more methods to make analyzing Arguments even easier.
  • Added customizable Callback Functions and new Formatting options for Usage/Help messages.
  • Implemented Mandatory Options with the new mandatory field.
  • Implemented Option Termination which is configurable under cova.ParseConfig.
  • Revamped the handling of Values with an Enum Child Type to make them seamless to work with.
  • Revamped Conversions for fields w/ default values.
  • Tested on additional platforms.
  • Updated Installation to use the new zig fetch --save.
  • Updated the Docs and Guides with more features and examples.

Breaking

  • Changed the get, check, and match methods for analyzing Options & Values to use Argument Groups.
  • Added new global_ and child_type_ prefixes for certain fields.
  • Added Allocator parameter requirement for all Callback Functions.

Fixes & Optimizations

  • Fixed bug with Long Option parsing.
  • Fixed bug with Boolean Value parsing.
  • Fixed Alignment Issue on ARM devices.
  • Fixed bug with Command.Custom.getVals().
  • Fixed bug with Command.Custom.to() parsing.
  • Fixed Zig removal of meta.trait.
  • Fixed Zig “local variable is never mutated” errors.
  • Removed several unnecessary, erroneous uses of const and @constCast().
  • Optimized the default size of the Value.Generic Union and added customization options allowing for much smaller binaries.
  • Optimized parts of Argument Initialization/De-initialization.

Of note, this version was originally meant to focus on Manpage & Tab Completion Script Generation. The feature list and fixes above became large enough to warrant their own release, so the doc/script generation has been pushed to be the sole focus of the next release.

5 Likes
6

After the v0.9.0 update I got some great feedback on the Readme for the repo. I’ve given it a facelift to try and make the library more approachable. As always, continued feedback is greatly appreciated!

v0.9.1

  • Revamped the Readme to be more concise and readable.
  • Updated for Zig Build API changes.
1 Like
7

After a lengthy delay, Cova’s v0.10.0 release is now live! This version adds several new features. Chief among them is the new Meta Doc Generation that enables you to create the following with a single simple build step:

  • Help Docs (Manpages & Markdown)
  • Tab Completion Scripts (Bash, Zsh, and PowerShell)
  • Argument Templates (JSON & KDL)

v0.10.0 (Supports Zig v0.12)

New Features

  • Meta Doc Generators for Help Docs, Tab Completion Scripts, and Argument Templates!
  • Inheritable Options that can be passed down to all Sub-Commands of a given Command (ex: cmd --opt and cmd sub-cmd --opt would refer to the same --opt).
  • New parent_cmd field for all Argument Types, allowing for easier bi-directional referencing.
  • New examples field for Commands which is used to show examples in Usage/Help messages and Help Docs.
  • New Argument Index (arg_idx) field for all Argument Types, so you can tell exactly where an Argument was provided in relation to other Arguments regardless of spacing.
  • New checkArgGroup() method for Commands to check if an Argument from the specified Argument Group was used.
  • Argument Type Configs now have an optimized() function that can slim down the Value Union and remove certain features to help reduce binary size. (These optimizations can be enabled individually as well.)

Doc Improvements

  • Updated the Docs to use the new Zig Autodocs. They’re also now created through CI using a GitHub Workflow.
  • Revamped the Guides and moved them to a GitHub Wiki for the Cova repo.
  • Simplified the README to be leaner and cleaner. (Always looking for feedback on this)
  • Better basic-app and covademo examples.

Fixes & Optimizations

  • Revamped allocation model that closely resembles Zig’s Managed Types.
  • Better Value parsing.
  • Improved Value Union default Types.
  • Several updates to stay in line with Zig changes (no comptime var, b.path(), etc)

Breaking

  • Several fields from the Argument Types and Configs have been renamed for better consistency.
  • Meta Doc Gen has been completely reworked from the very limited version available in v0.9.0.

Working on the past couple of release notes and following other projects has shown me that it’s likely better to announce new features in more of a Dev Log fashion. With that in mind, I’ll try and create individual posts for some of the bigger features in this release and maintain those posts for new features going forward.

Last but not least I have to thank a few people for helping me out:

  • @castholm for helping with the Meta Doc Gen build step.
  • @ianprime0509 for fixing an issue with the new Zig Autodocs.
  • @matu3ba for leading me to make the Argument Templates.
7 Likes
8

Cova v0.10.1 is up today. This version is primarily enhancements and fixes to features from v0.10.0.

I’ve had a lot of success using this in my own projects, and it’s come a long way thanks in no small part to user feedback. So, as always, feedback is greatly appreciated!

Cova v0.10.1 (Supports Zig v0.13)

Features

  • Zig v0.13 support.
  • Improved the Documentation, Examples, & Build Process.
  • Added the “cova” Log Scope.
  • Added a reset() method f/ Commands similar to the one for std.ArrayList.
  • Exposed indent_fmt f/ Values.
  • Added getAllAs() to Values to help w/ multi-value analysis.
  • Created the UsageHelpConfig f/ Initialization. (This will be reworked into DefaultArgConfig in v0.11)
  • Added excluded_short_opts to the FromConfig f/ Commands to allow for more granular conversion control with Default Arguments.

Fixes

  • Fixed Enum handling f/ Values.
  • Fixed Boolean parsing issue f/ Values.

Here’s a roadmap of the features planned for the v0.11 release as well.

4 Likes
9

Lately I’ve been deep in a few other projects so work on Cova has been a little slow. However I have made a few nice updates since the v0.10.1 to support my other projects:

  1. Support for Parameter Names when making a Command from a Function

For instance, given the following function signature:

/// Calculate a WEP Key or WPA Pre-Shared Key (PSK) using MD5 or PBKDF2 with HMAC-SHA1.
pub fn genKey(protocol: Protocol, ssid: []const u8, passphrase: []const u8) ![32]u8 {

You can now set sub-descriptions to provide help/meta doc details like so:

        CommandT.from(@TypeOf(wpa.genKey), .{
            .cmd_name = "gen-key",
            .cmd_description = "Generate a WPA Key.",
            .sub_descriptions = &.{
                .{ "protocol", "WiFi Network Security Protocol." },
                .{ "ssid", "WiFi Network SSID." },
                .{ "passphrase", "WiFi Network Passphrase." },
            },
        }),
  1. Support for Abbreviated Commands

If you’ve ever used ip on Linux, you’re likely aware that you can shorten Command names. For instance, the following Commands are all equivalent:

ip address add
ip addr ad
ip a a

This is now also possible in Cova simply by enabling allow_abbreviated_commands in your Command Config.

(Of note, this is also supported for Option long names from an earlier release.)

  1. Better Option Analysis

The getOpts() method for Commands is now a little more sensible. It will create a hashmap only from Options that have set or default Values.

  1. Empty Option Handling

This one is best described here.

Basically, Options with non-Boolean Values can now be set without taking a Value. For instance:

cmd --my-str-opt "Some text"

and

cmd --my-str-opt

can both be made valid, with the latter being checked via opt.val.isEmpty() instead of opt.val.getAs().

  1. Option Aliases in Usage

Options will now display their Long Name Aliases alongside their Short and Long Names in a Usage Message. For instance given the following Option

        .{ 
            .name = "string_opt",
            .description = "A string option.",
            // ...
            .short_name = 's',
            .long_name = "string",
            .alias_long_names = &.{ "text" },
            // ...
            .val = ValueT.ofType([]const u8, .{
                // ...
                .alias_child_type = "string",
                // ...
        },

You’ll now see the following Usage Message:
-s,--string,--text <string>

1 Like