1/Hejsil/clap v0.60

8c98e6404b22aafc0184e999d8f068b81cc22fa1

Readme Contents 0 Dependencies History

zig-clap

A simple and easy to use command line argument parser library for Zig.

The master branch of zig-clap targets the master branch of Zig. For a version of zig-clap that targets a specific Zig release, have a look at the releases. Each release specifies the Zig version it compiles with in the release notes.

Features

Short arguments -a
- Chaining -abc where a and b does not take values.
- Multiple specifications are tallied (e.g. -v -v).
Long arguments --long
Supports both passing values using spacing and = (-a 100, -a=100)
- Short args also support passing values with no spacing or = (-a100)
- This all works with chaining (-ba 100, -ba=100, -ba100)
Supports options that can be specified multiple times (-e 1 -e 2 -e 3)
Print help message from parameter specification.
Parse help message to parameter specification.

API Reference

Automatically generated API Reference for the project can be found at https://Hejsil.github.io/zig-clap. Note that Zig autodoc is in beta; the website may be broken or incomplete.

Examples

`clap.parse`

The simplest way to use this library is to just call the clap.parse function.

const clap = @import("clap");
const std = @import("std");

const debug = std.debug;
const io = std.io;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    // First we specify what parameters our program can take.
    // We can use `parseParamsComptime` to parse a string into an array of `Param(Help)`
    const params = comptime clap.parseParamsComptime(
        \\-h, --help             Display this help and exit.
        \\-n, --number <usize>   An option parameter, which takes a value.
        \\-s, --string <str>...  An option parameter which can be specified multiple times.
        \\<str>...
        \\
    );

    // Initialize our diagnostics, which can be used for reporting useful errors.
    // This is optional. You can also pass `.{}` to `clap.parse` if you don't
    // care about the extra information `Diagnostics` provides.
    var diag = clap.Diagnostic{};
    var res = clap.parse(clap.Help, &params, clap.parsers.default, .{
        .diagnostic = &diag,
        .allocator = gpa.allocator(),
    }) catch |err| {
        // Report useful error and exit
        diag.report(io.getStdErr().writer(), err) catch {};
        return err;
    };
    defer res.deinit();

    if (res.args.help != 0)
        debug.print("--help\n", .{});
    if (res.args.number) |n|
        debug.print("--number = {}\n", .{n});
    for (res.args.string) |s|
        debug.print("--string = {s}\n", .{s});
    for (res.positionals) |pos|
        debug.print("{s}\n", .{pos});
}

The result will contain an args field and a positionals field. args will have one field for each none positional parameter of your program. The name of the field will be the longest name of the parameter.

The fields in args are typed. The type is based on the name of the value the parameter takes. Since --number takes a usize the field res.args.number has the type usize.

Note that this is only the case because clap.parsers.default has a field called usize which contains a parser that returns usize. You can pass in something other than clap.parsers.default if you want some other mapping.

const clap = @import("clap");
const std = @import("std");

const debug = std.debug;
const io = std.io;
const process = std.process;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    // First we specify what parameters our program can take.
    // We can use `parseParamsComptime` to parse a string into an array of `Param(Help)`
    const params = comptime clap.parseParamsComptime(
        \\-h, --help             Display this help and exit.
        \\-n, --number <INT>     An option parameter, which takes a value.
        \\-a, --answer <ANSWER>  An option parameter which takes an enum.
        \\-s, --string <STR>...  An option parameter which can be specified multiple times.
        \\<FILE>...
        \\
    );

    // Declare our own parsers which are used to map the argument strings to other
    // types.
    const YesNo = enum { yes, no };
    const parsers = comptime .{
        .STR = clap.parsers.string,
        .FILE = clap.parsers.string,
        .INT = clap.parsers.int(usize, 10),
        .ANSWER = clap.parsers.enumeration(YesNo),
    };

    var diag = clap.Diagnostic{};
    var res = clap.parse(clap.Help, &params, parsers, .{
        .diagnostic = &diag,
        .allocator = gpa.allocator(),
    }) catch |err| {
        diag.report(io.getStdErr().writer(), err) catch {};
        return err;
    };
    defer res.deinit();

    if (res.args.help != 0)
        debug.print("--help\n", .{});
    if (res.args.number) |n|
        debug.print("--number = {}\n", .{n});
    if (res.args.answer) |a|
        debug.print("--answer = {s}\n", .{@tagName(a)});
    for (res.args.string) |s|
        debug.print("--string = {s}\n", .{s});
    for (res.positionals) |pos|
        debug.print("{s}\n", .{pos});
}

`streaming.Clap`

The streaming.Clap is the base of all the other parsers. It's a streaming parser that uses an args.Iterator to provide it with arguments lazily.

const clap = @import("clap");
const std = @import("std");

const debug = std.debug;
const io = std.io;
const process = std.process;

pub fn main() !void {
    const allocator = std.heap.page_allocator;

    // First we specify what parameters our program can take.
    const params = [_]clap.Param(u8){
        .{
            .id = 'h',
            .names = .{ .short = 'h', .long = "help" },
        },
        .{
            .id = 'n',
            .names = .{ .short = 'n', .long = "number" },
            .takes_value = .one,
        },
        .{ .id = 'f', .takes_value = .one },
    };

    var iter = try process.ArgIterator.initWithAllocator(allocator);
    defer iter.deinit();

    // Skip exe argument
    _ = iter.next();

    // Initialize our diagnostics, which can be used for reporting useful errors.
    // This is optional. You can also leave the `diagnostic` field unset if you
    // don't care about the extra information `Diagnostic` provides.
    var diag = clap.Diagnostic{};
    var parser = clap.streaming.Clap(u8, process.ArgIterator){
        .params = &params,
        .iter = &iter,
        .diagnostic = &diag,
    };

    // Because we use a streaming parser, we have to consume each argument parsed individually.
    while (parser.next() catch |err| {
        // Report useful error and exit
        diag.report(io.getStdErr().writer(), err) catch {};
        return err;
    }) |arg| {
        // arg.param will point to the parameter which matched the argument.
        switch (arg.param.id) {
            'h' => debug.print("Help!\n", .{}),
            'n' => debug.print("--number = {s}\n", .{arg.value.?}),

            // arg.value == null, if arg.param.takes_value == .none.
            // Otherwise, arg.value is the value passed with the argument, such as "-a=10"
            // or "-a 10".
            'f' => debug.print("{s}\n", .{arg.value.?}),
            else => unreachable,
        }
    }
}

Currently, this parser is the only parser that allows an array of Param that is generated at runtime.

`help`

The help prints a simple list of all parameters the program can take. It expects the Id to have a description method and an value method so that it can provide that in the output. HelpOptions is passed to help to control how the help message is printed.

const clap = @import("clap");
const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    const params = comptime clap.parseParamsComptime(
        \\-h, --help     Display this help and exit.
        \\-v, --version  Output version information and exit.
        \\
    );

    var res = try clap.parse(clap.Help, &params, clap.parsers.default, .{
        .allocator = gpa.allocator(),
    });
    defer res.deinit();

    // `clap.help` is a function that can print a simple help message. It can print any `Param`
    // where `Id` has a `describtion` and `value` method (`Param(Help)` is one such parameter).
    // The last argument contains options as to how `help` should print those parameters. Using
    // `.{}` means the default options.
    if (res.args.help != 0)
        return clap.help(std.io.getStdErr().writer(), clap.Help, &params, .{});
}

$ zig-out/bin/help --help
    -h, --help
            Display this help and exit.

    -v, --version
            Output version information and exit.

`usage`

The usage prints a small abbreviated version of the help message. It expects the Id to have a value method so it can provide that in the output.

const clap = @import("clap");
const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    const params = comptime clap.parseParamsComptime(
        \\-h, --help         Display this help and exit.
        \\-v, --version      Output version information and exit.
        \\    --value <str>  An option parameter, which takes a value.
        \\
    );

    var res = try clap.parse(clap.Help, &params, clap.parsers.default, .{
        .allocator = gpa.allocator(),
    });
    defer res.deinit();

    // `clap.usage` is a function that can print a simple help message. It can print any `Param`
    // where `Id` has a `value` method (`Param(Help)` is one such parameter).
    if (res.args.help != 0)
        return clap.usage(std.io.getStdErr().writer(), clap.Help, &params);
}

$ zig-out/bin/usage --help
[-hv] [--value <str>]

Package Contents

example/simple.zig
example/streaming-clap.zig
example/help.zig
example/README.md.template
example/simple-ex.zig
example/usage.zig
.gitattributes
LICENSE
.github/workflows/docs.yml
.github/workflows/main.yml
.github/FUNDING.yml
build.zig
README.md
clap.zig
zig.mod
clap/parsers.zig
clap/args.zig
clap/streaming.zig
build.zig.zon
.gitignore

History

	Published On	Tree @ Commit	Size
v0.60	Sat, 30 Mar 2024 15:37:23 UTC	Tree	101.666 KB
v0.59	Tue, 12 Mar 2024 14:31:27 UTC	Tree	101.477 KB
v0.58	Sat, 24 Feb 2024 01:29:38 UTC	Tree	101.477 KB
v0.57	Fri, 02 Feb 2024 14:54:08 UTC	Tree	101.481 KB
v0.56	Fri, 02 Feb 2024 14:44:43 UTC	Tree	101.493 KB
v0.55	Tue, 09 Jan 2024 07:21:51 UTC	Tree	101.766 KB
v0.54	Fri, 05 Jan 2024 12:35:16 UTC	Tree	101.545 KB
v0.53	Tue, 02 Jan 2024 12:16:56 UTC	Tree	101.528 KB
v0.52	Wed, 13 Dec 2023 07:59:42 UTC	Tree	100.084 KB
v0.51	Thu, 16 Nov 2023 11:01:30 UTC	Tree	99.549 KB
v0.50	Fri, 10 Nov 2023 08:45:18 UTC	Tree	99.534 KB
v0.49	Sun, 10 Sep 2023 19:08:14 UTC	Tree	99.466 KB
v0.48	Thu, 03 Aug 2023 07:37:04 UTC	Tree	98.468 KB
v0.47	Tue, 27 Jun 2023 07:07:26 UTC	Tree	98.463 KB
v0.46	Thu, 22 Jun 2023 07:26:05 UTC	Tree	98.588 KB
v0.45	Sun, 18 Jun 2023 11:44:37 UTC	Tree	98.584 KB
v0.44	Thu, 15 Jun 2023 07:53:18 UTC	Tree	98.588 KB
v0.43	Mon, 17 Apr 2023 06:56:26 UTC	Tree	97.907 KB
v0.42	Fri, 14 Apr 2023 06:39:03 UTC	Tree	97.921 KB
v0.41	Sun, 02 Apr 2023 11:10:43 UTC	Tree	97.779 KB
v0.40	Mon, 20 Mar 2023 08:25:54 UTC	Tree	97.255 KB
v0.39	Sun, 19 Mar 2023 10:46:12 UTC	Tree	97.249 KB
v0.38	Mon, 06 Mar 2023 22:26:36 UTC	Tree	97.108 KB
v0.37	Wed, 01 Mar 2023 14:49:20 UTC	Tree	97.143 KB
v0.36	Tue, 28 Feb 2023 15:15:17 UTC	Tree	97.143 KB
v0.35	Sun, 26 Feb 2023 18:05:59 UTC	Tree	97.293 KB
v0.34	Wed, 22 Feb 2023 08:38:03 UTC	Tree	97.216 KB
v0.33	Mon, 06 Feb 2023 15:53:26 UTC	Tree	97.206 KB
v0.32	Mon, 06 Feb 2023 08:13:29 UTC	Tree	97.204 KB
v0.31	Sun, 05 Feb 2023 21:22:11 UTC	Tree	97.226 KB
v0.30	Thu, 12 Jan 2023 18:50:08 UTC	Tree	97.097 KB
v0.29	Wed, 04 Jan 2023 09:52:23 UTC	Tree	97.086 KB
v0.28	Tue, 20 Dec 2022 13:11:39 UTC	Tree	97.086 KB
v0.27	Fri, 09 Dec 2022 10:04:50 UTC	Tree	97.104 KB
v0.26	Fri, 09 Dec 2022 09:50:04 UTC	Tree	97.129 KB
v0.25	Thu, 01 Dec 2022 08:35:23 UTC	Tree	97.288 KB
v0.24	Tue, 22 Nov 2022 13:51:54 UTC	Tree	97.276 KB
v0.23	Tue, 15 Nov 2022 10:18:15 UTC	Tree	97.253 KB
v0.22	Tue, 08 Nov 2022 12:47:42 UTC	Tree	97.497 KB
v0.21	Tue, 01 Nov 2022 18:12:55 UTC	Tree	97.497 KB
v0.20	Mon, 03 Oct 2022 10:57:15 UTC	Tree	97.497 KB
v0.19	Mon, 03 Oct 2022 10:46:46 UTC	Tree	97.416 KB
v0.18	Sun, 18 Sep 2022 17:07:01 UTC	Tree	97.411 KB
v0.17	Thu, 25 Aug 2022 16:08:49 UTC	Tree	97.415 KB
v0.16	Thu, 28 Jul 2022 12:50:37 UTC	Tree	96.222 KB
v0.15	Mon, 25 Jul 2022 16:16:22 UTC	Tree	95.982 KB
v0.14	Fri, 22 Jul 2022 09:01:18 UTC	Tree	94.387 KB
v0.13	Thu, 28 Apr 2022 17:00:50 UTC	Tree	94.157 KB
v0.12	Wed, 30 Mar 2022 20:04:24 UTC	Tree	93.988 KB
v0.11	Wed, 30 Mar 2022 19:57:53 UTC	Tree	93.854 KB
v0.10	Thu, 24 Mar 2022 10:08:46 UTC	Tree	75.386 KB
v0.9	Wed, 23 Mar 2022 20:48:24 UTC	Tree	75.237 KB
v0.8	Mon, 21 Mar 2022 22:03:53 UTC	Tree	68.282 KB
v0.7	Wed, 09 Mar 2022 17:12:42 UTC	Tree	67.399 KB
v0.6	Wed, 02 Mar 2022 16:56:42 UTC	Tree	68.271 KB
v0.5	Fri, 25 Feb 2022 18:48:44 UTC	Tree	68.278 KB
v0.4	Fri, 25 Feb 2022 18:44:33 UTC	Tree	67.327 KB
v0.3	Tue, 22 Feb 2022 18:19:45 UTC	Tree	68.278 KB
v0.2	Thu, 03 Feb 2022 21:00:17 UTC	Tree	68.104 KB
v0.1	Thu, 03 Feb 2022 20:53:55 UTC	Tree	68.116 KB