Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

v0.9.0-beta #48

Merged
merged 69 commits into from
Dec 30, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
69 commits
Select commit Hold shift + click to select a range
2cb7750
Fixed a few Comment Errors
00JCIV00 Sep 24, 2023
ecc2468
Implemented Manpage Generation
00JCIV00 Sep 24, 2023
95f4ada
Implemented Initial Tab Completion Script Generation
00JCIV00 Sep 24, 2023
0b11809
Updated Docs for Auxiliary Docs Generation
00JCIV00 Sep 24, 2023
96331ee
Fixed Exhaustion Bug in Bash Tab Completion
00JCIV00 Sep 24, 2023
ab7b90a
Updated the Formatting for Manpages and Tab Completion Scripts
00JCIV00 Sep 29, 2023
44c16c2
Moved Value Usage/Help Handling to Value to mirrow Command and Option
00JCIV00 Sep 29, 2023
1c679ab
Fixed Long Option parsing bug
00JCIV00 Sep 29, 2023
2e78aef
Added Check/Match Analysis for Options
00JCIV00 Sep 30, 2023
b5224c4
Updated Docs for the new Option Check/Match Analysis methods
00JCIV00 Sep 30, 2023
5cec1a8
Added more customizable Formats for Help/Usage methods
00JCIV00 Oct 6, 2023
6a64c62
Updated README with `zig fetch` Install
00JCIV00 Oct 10, 2023
62c7b55
Implemented custom Usage/Help Functions for Commands
00JCIV00 Oct 10, 2023
2a3c173
Updated `build.zig.zon`
00JCIV00 Oct 15, 2023
51813e7
Implemented Custom Usage/Help Functions for Options & Usage
00JCIV00 Oct 16, 2023
a5be98e
Fixed Boolean Value parsing bug
00JCIV00 Oct 18, 2023
0e83d81
Updated Alternatives Section README.md
00JCIV00 Oct 20, 2023
c8c8551
Added `mem.Allocator` requirement for all Callback Functions
00JCIV00 Oct 20, 2023
f799141
Allowed Custom `Value.Typed` Types in `Value.Config.custom_types`
00JCIV00 Oct 20, 2023
b7cecb2
Implemented overwriting of base `Value.Generic` Types
00JCIV00 Oct 21, 2023
0def2bc
Implemented Argument Type Groups
00JCIV00 Oct 22, 2023
d4bdf1d
Updated Argument Type Groups implementation
00JCIV00 Oct 22, 2023
3219c67
Implemented Value Child Type Aliases
00JCIV00 Oct 22, 2023
54b83f7
Updated README.md
00JCIV00 Oct 22, 2023
402295a
Changed `aux_doc` to `generate`
00JCIV00 Oct 22, 2023
121a3e2
Implemented Command Aliases
00JCIV00 Oct 22, 2023
434ed6f
Added Validation for Command Aliases
00JCIV00 Oct 22, 2023
5bbc284
Added ability to add a Help Argument Group during Initialization
00JCIV00 Oct 22, 2023
be28c37
Added Alias printing for Help Messages
00JCIV00 Oct 22, 2023
5c04a72
Fixed small alignment issue on ARM devices
00JCIV00 Oct 23, 2023
db99e1d
Revamped Callback Function Naming Scheme
00JCIV00 Nov 7, 2023
2aa9c74
Implemented Case Sensitive Parsing Toggles
00JCIV00 Nov 7, 2023
079dc37
Added `case_sensitive` field to Command From functions
00JCIV00 Nov 9, 2023
b1f056a
Added majority of support for converting Enum Types
00JCIV00 Nov 11, 2023
c1d6b05
Updated Docs and Tests
00JCIV00 Nov 11, 2023
0e4fb20
Fixed minor issue with `getVals()` in `Command.zig`
00JCIV00 Nov 19, 2023
b273441
Fixed "local variable is never mutated" error from Zig update
00JCIV00 Nov 22, 2023
114556a
Updated for removal of `meta.trait` namespace.
00JCIV00 Nov 24, 2023
cca5576
Updated Option Termination
00JCIV00 Nov 24, 2023
345f038
Implemented Options from Fields w/ default value
00JCIV00 Nov 25, 2023
7448302
Added `max_children` to `Value.Config`
00JCIV00 Nov 25, 2023
a14c96b
Added ways to trim down the size of `Value.Generic`
00JCIV00 Nov 26, 2023
e05ca0e
Fixed minor issue with printing Argument Groups in `Command.zig`
00JCIV00 Nov 26, 2023
6483f80
Updated erroneous use of `const` in `cova.zig`
00JCIV00 Nov 26, 2023
d84b46a
Updated Usage messages
00JCIV00 Nov 26, 2023
54d7dfb
Implemented Hidden Arguments
00JCIV00 Nov 26, 2023
4e43419
Fixed reified `Value.Generic` creation
00JCIV00 Nov 27, 2023
814c0f6
Fixed handling of default values
00JCIV00 Nov 27, 2023
b14baf2
Added Executable Name build option
00JCIV00 Nov 29, 2023
2bca911
Improved Enum and Conversion handling for Values
00JCIV00 Nov 29, 2023
602fd67
Improved the `checkOpts()` function in `Command.zig`
00JCIV00 Nov 29, 2023
7372d80
Implemented `reset` function for `ArgIteratorGeneric`
00JCIV00 Nov 30, 2023
9246a94
Fixed bug in `Command.Custom.to()` parsing
00JCIV00 Dec 17, 2023
74ecbac
Updated `basic_app.zig` to be compatible to latest Zig
00JCIV00 Dec 17, 2023
99290af
Implemented Mandatory Options
00JCIV00 Dec 17, 2023
40a3405
Updated Docs
00JCIV00 Dec 20, 2023
286bc82
Updated field prefixes for `Value.Config`
00JCIV00 Dec 22, 2023
f54988d
Started updating Readme and Guides
00JCIV00 Dec 22, 2023
4b95a07
Implemented a few Initialization Optimizations
00JCIV00 Dec 27, 2023
fd9fd15
Removed default `valid_fn` for Values
00JCIV00 Dec 27, 2023
a98e39a
Removed `_is_init` field for Commands
00JCIV00 Dec 27, 2023
d4fe7e5
Updated the README, Docs, and Guides
00JCIV00 Dec 28, 2023
cf2f582
Implemented Option Aliases
00JCIV00 Dec 29, 2023
f6e16dd
Added Analysis w/ Argument Groups
00JCIV00 Dec 29, 2023
3d3bd91
Revamped Value Child Type Aliasing
00JCIV00 Dec 29, 2023
78f5eb7
Updated examples f/ v0.9.0 release
00JCIV00 Dec 30, 2023
8eb9155
Removed Doc Generation f/ v0.9.0 release
00JCIV00 Dec 30, 2023
fe57649
Finalized README, Docs, Guides, and Examples f/ v0.9.0 Release
00JCIV00 Dec 30, 2023
fee493e
Merge branch 'main' into v0.9.0
00JCIV00 Dec 30, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
66 changes: 37 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Commands, Options, Values, Arguments. A simple yet robust cross-platform command
___

## Overview
Cova is based on the idea that Arguments will fall into one of three types: Commands, Options, or Values. These types are assembled into a single Command struct which is then used to parse argument tokens.
Cova is based on the idea that Arguments will fall into one of three types: Commands, Options, or Values. These Types are assembled into a single Command struct which is then used to parse argument tokens.

## Table of Contents
- [Demo](#demo)
Expand Down Expand Up @@ -34,9 +34,12 @@ Cova is based on the idea that Arguments will fall into one of three types: Comm
- The most Basic Setup requires only Cova imports, a library user Struct, and a few function calls for parsing.
- POSIX Compliant (as defined [here](https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html)) by default.
- Multiplatform. Tested across:
- x86-linux
- x86_64-linux
- arm-linux
- aarch64-linux
- x86_64-windows
- x86_64-macos
- *Should support all POSIX compliant systems.*
- Commands:
- Contain sub-Commands, Options, and Values.
Expand Down Expand Up @@ -68,12 +71,12 @@ Cova is based on the idea that Arguments will fall into one of three types: Comm
- Choose how errors should be reacted to with either a Usage/Help message or no reaction.
- Decide if Option parsing should be terminated after a standalone long prefix such as `--`.
- Commands:
- Configure Templates for auto-generated Command Help/Usage messages.
- Configure Templates or Callback Functions for generated Command Help/Usage messages.
- Set Rules for converting From/To a Struct, Union, or Function.
- Mandate that a Command takes a sub-Command if available.
- Mandate all Values be filled.
- Options:
- Configure Templates for Option Help/Usage messages.
- Configure Templates or Callback Functions for generated Option Help/Usage messages.
- Customize Short and Long prefixes (i.e. `/s` or `__long-opt`).
- Set the allowed Separator Character(s) between Options and their Values.
- Allow/Disallow Abbreviated Long Options (i.e `--long-opt` can be `--long`).
Expand All @@ -82,13 +85,15 @@ Cova is based on the idea that Arguments will fall into one of three types: Comm
- Configure Values to be Individual or Multi, allowing multiple of the same type to be stored in a single Value.
- Set the allowed Delimiter Characters between data elements provided to a single Value (i.e `my-cmd multi,string,value`).
- Set the Rules for how Values are *set* through **custom Parsing and Validation Functions!**
- ___And much more!___

## Goals
### Pre Public Beta Release
- [v0.7.0-beta](https://github.com/00JCIV00/cova/issues/9)
### Public Beta Release
- [v0.8.0-beta](https://github.com/00JCIV00/cova/issues?q=milestone%3Av0.8.0-beta)
- [v0.9.0-beta](https://github.com/00JCIV00/cova/issues?q=milestone%3Av0.9.0-beta+)
- [v0.9.0-beta](https://github.com/00JCIV00/cova/issues?q=milestone%3Av0.9.0-beta)
- [v0.10.0-beta](https://github.com/00JCIV00/cova/issues?q=milestone%3Av0.10.0-beta)

## Documentation
- [API](https://00jciv00.github.io/cova/#A;cova)
Expand All @@ -99,12 +104,8 @@ Cova is based on the idea that Arguments will fall into one of three types: Comm
1. Find the latest `v#.#.#` commit [here](https://github.com/00JCIV00/cova/commits/main).
2. Copy the full SHA for the commit.
3. Add the dependency to `build.zig.zon`:
```zig
.dependencies = .{
.cova = .{
.url = "https://github.com/00JCIV00/cova/archive/<GIT COMMIT SHA FROM STEP 2 HERE>.tar.gz",
},
},
```bash
zig fetch --save "https://github.com/00JCIV00/cova/archive/<GIT COMMIT SHA FROM STEP 2 HERE>.tar.gz"
```
4. Add the dependency and module to `build.zig`:
```zig
Expand All @@ -122,16 +123,17 @@ const exe = b.addExecutable(.{
// Add the Cova Module to the Executable
exe.addModule("cova", cova_mod);
```
5. Run `zig build <PROJECT BUILD STEP IF APPLICABLE>` to get the hash.
6. Insert the hash into `build.zig.zon`:
```zig
.dependencies = .{
.cova = .{
.url = "https://github.com/00JCIV00/cova/archive/<GIT COMMIT SHA FROM STEP 2 HERE>.tar.gz",
.hash = "HASH FROM STEP 5 HERE",
},
},
```

### Package Manager - Alternative
Note, this method makes Cova easier to update by simply re-running `zig fetch --save https://github.com/00JCIV00/cova/archive/[BRANCH].tar.gz`. However, it can lead to non-reproducible builds because the url will always point to the newest commit of the provided branch. Details can be found in [this discussion](https://ziggit.dev/t/feature-or-bug-w-zig-fetch-save/2565).
1. Choose a branch to stay in sync with.
- `main` is the latest stable branch.
- The highest `v#.#.#` is the development branch.
2. Add the dependency to `build.zig.zon`:
```shell
zig fetch --save https://github.com/00JCIV00/cova/archive/[BRANCH FROM STEP 1].tar.gz
```
3. Continue from Step 4 above.

### Build the Basic-App Demo from source
1. Use the latest Zig (v0.12) for your system. Available [here](https://ziglang.org/download/).
Expand Down Expand Up @@ -177,17 +179,17 @@ pub fn main() !void {
const alloc = arena.allocator();
const stdout = std.io.getStdOut().writer();

const main_cmd = &(try setup_cmd.init(alloc, .{}));
const main_cmd = try setup_cmd.init(alloc, .{});
defer main_cmd.deinit();

var args_iter = try cova.ArgIteratorGeneric.init(alloc);
defer args_iter.deinit();

cova.parseArgs(&args_iter, CommandT, main_cmd, stdout, .{}) catch |err| switch(err) {
cova.parseArgs(&args_iter, CommandT, &main_cmd, stdout, .{}) catch |err| switch(err) {
error.UsageHelpCalled,
else => return err,
}
try cova.utils.displayCmdInfo(CommandT, main_cmd, alloc, stdout);
try cova.utils.displayCmdInfo(CommandT, &main_cmd, alloc, stdout);
}
```

Expand All @@ -214,18 +216,22 @@ pub const ProjectStruct = struct {
// By default, Options will be given a long name and a short name based on the
// field name. (i.e. int = `-i` or `--int`)
sub_uint: ?u8 = 5,

// Primitive type fields will be converted into Values.
sub_string: []const u8,
},

// Struct fields will be converted into cova Commands.
subcmd: SubStruct = .{},

// The default values of Primitive type fields will be applied as the default value
// of the converted Option or Value.
int: ?i4 = 10,

// Optional Booleans will become cova Options that don't take a Value and are set to
// `true` simply by calling the Option's short or long name.
flag: ?bool = false,

// Arrays will be turned into Multi-Values or Multi-Options based on the array's
// child type.
strings: [3]const []const u8 = .{ "Three", "default", "strings." },
Expand Down Expand Up @@ -253,7 +259,7 @@ pub fn main() !void {
// Argument Types for correctness and distinct names, then it will return a
// memory allocated copy of the Command for argument token parsing and
// follow on analysis.
const main_cmd = &(try setup_cmd.init(alloc, .{}));
const main_cmd = try setup_cmd.init(alloc, .{});
defer main_cmd.deinit();

...
Expand Down Expand Up @@ -283,11 +289,12 @@ pub fn main() !void {

// The `parseArgs()` function will parse the provided ArgIterator's (`&args_iter`)
// tokens into Argument Types within the provided Command (`main_cmd`).
try cova.parseArgs(&args_iter, CommandT, main_cmd, stdout, .{});
try cova.parseArgs(&args_iter, CommandT, &main_cmd, stdout, .{});

// Once parsed, the provided Command will be available for analysis by the
// project code. Using `utils.displayCmdInfoi()` will create a neat display
// project code. Using `utils.displayCmdInfo()` will create a neat display
// of the parsed Command for debugging.
try utils.displayCmdInfo(CommandT, main_cmd, alloc, stdout);
try utils.displayCmdInfo(CommandT, &main_cmd, alloc, stdout);
}
```

Expand All @@ -297,11 +304,12 @@ pub fn main() !void {

### Advanced Setup
- [Advanced Demo](./examples/covademo.zig)
- The `covademo` is a showcase of most of Cova's features. This demo also serves as a test bed for features that are in development, so it's not well-documented in several areas. That said, it can still be a useful reference for how certain features should be used.
- The `covademo` is a showcase of most of Cova's features. This demo also serves as a test bed for features that are in development, so it's not well-documented in several areas. That said, it can still be a useful reference for how certain features can be used.


## Alternatives
- [yazap](https://github.com/PrajwalCH/yazap)
- [zig-args](https://github.com/MasterQ32/zig-args)
- [zig-args](https://github.com/mainQ32/zig-args)
- [zig-clap](https://github.com/Hejsil/zig-clap)
- [zig-cli](https://github.com/sam701/zig-cli)
- [zig-parse-args](https://github.com/winksaville/zig-parse-args)
25 changes: 16 additions & 9 deletions build.zig
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
//const build_options = b.addOptions();
const bin_name = b.option([]const u8, "name", "A name for the binary being created.");
b.exe_dir = "./bin";

// Static Lib (Unused)
Expand All @@ -13,6 +15,7 @@ pub fn build(b: *std.Build) void {
// .optimize = optimize,
//});
//b.installArtifact(lib);


// Tests
const cova_tests = b.addTest(.{
Expand All @@ -24,11 +27,6 @@ pub fn build(b: *std.Build) void {
const test_step = b.step("test", "Run cova library tests");
test_step.dependOn(&run_cova_tests.step);

// Lib Module
const cova_mod = b.addModule("cova", .{
.source_file = std.Build.FileSource.relative("src/cova.zig"),
});

// Docs
const cova_docs = cova_tests;
const build_docs = b.addInstallDirectory(.{
Expand All @@ -39,21 +37,27 @@ pub fn build(b: *std.Build) void {
const build_docs_step = b.step("docs", "Build the cova library docs");
build_docs_step.dependOn(&build_docs.step);

// Demo Exe
// Lib Module
const cova_mod = b.addModule("cova", .{
.source_file = std.Build.FileSource.relative("src/cova.zig"),
});

// Cova Demo Exe
const cova_demo = b.addExecutable(.{
.name = "covademo",
.name = bin_name orelse "covademo",
.root_source_file = .{ .path = "examples/covademo.zig" },
.target = target,
.optimize = optimize,
});
cova_demo.addModule("cova", cova_mod);
// - Build Exe
const build_cova_demo = b.addInstallArtifact(cova_demo, .{});
const build_cova_demo_step = b.step("demo", "Build the 'covademo' example (default: Debug)");
const build_cova_demo_step = b.step("cova-demo", "Build the 'covademo' example (default: Debug)");
build_cova_demo_step.dependOn(&build_cova_demo.step);

// Basic App Exe
const basic_app = b.addExecutable(.{
.name = "basic-app",
.name = bin_name orelse "basic-app",
.root_source_file = .{ .path = "examples/basic_app.zig" },
.target = target,
.optimize = optimize,
Expand All @@ -62,4 +66,7 @@ pub fn build(b: *std.Build) void {
const build_basic_app = b.addInstallArtifact(basic_app, .{});
const build_basic_app_step = b.step("basic-app", "Build the 'basic-app' example (default: Debug)");
build_basic_app_step.dependOn(&build_basic_app.step);


}

11 changes: 8 additions & 3 deletions build.zig.zon
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
.{
.name = "cova",
.version = "0.8.0",
.dependencies = .{},
.name = "cova",
.paths = .{
"build.zig",
"build.zig.zon",
"src",
},
.version = "0.9.0",
.dependencies = .{},
}
2 changes: 1 addition & 1 deletion docs/data-astNodes.js

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/data-calls.js

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/data-comptimeExprs.js

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/data-decls.js

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/data-exprs.js

Large diffs are not rendered by default.

Loading