Cova - Commands, Options, Values, Arguments

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!

13 Likes

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

1 Like

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

1 Like

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

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

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

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