{"id":38840547,"url":"https://github.com/d4c7/zarg","last_synced_at":"2026-01-17T14:00:10.431Z","repository":{"id":180482327,"uuid":"665219693","full_name":"d4c7/zarg","owner":"d4c7","description":"[WIP] zarg is a minimalist and efficient command-line parsing library written in Zig","archived":false,"fork":false,"pushed_at":"2025-02-08T09:32:40.000Z","size":111,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T10:27:37.374Z","etag":null,"topics":["cli","command-line","command-line-parser","zig","zig-package"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d4c7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/EUPL-1.2.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-11T17:53:54.000Z","updated_at":"2025-02-08T09:32:43.000Z","dependencies_parsed_at":"2025-01-26T10:36:46.682Z","dependency_job_id":null,"html_url":"https://github.com/d4c7/zarg","commit_stats":null,"previous_names":["d4c7/zig-argueando","d4c7/zarg"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/d4c7/zarg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4c7%2Fzarg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4c7%2Fzarg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4c7%2Fzarg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4c7%2Fzarg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d4c7","download_url":"https://codeload.github.com/d4c7/zarg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4c7%2Fzarg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28509831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","command-line-parser","zig","zig-package"],"created_at":"2026-01-17T14:00:09.521Z","updated_at":"2026-01-17T14:00:10.354Z","avatar_url":"https://github.com/d4c7.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2023-2025 David Castañon Belloso \u003cd4c7@proton.me\u003e\nSPDX-License-Identifier: EUPL-1.2\nThis file is part of zarg project (https://github.com/d4c7/zarg)\n--\u003e\n# zarg\n\nzarg (former zig-argueando) is a minimalist and efficient command-line parsing library written in Zig. It is designed to offer a convenient way of parsing command-line arguments in a simple yet powerful manner. With zarg, you can easily set options, flags, and positional arguments for your command-line applications.\n\nVersion 0.0.1 for zig 0.3.0\n\n```\nWARNING: THIS IS A WORK IN PROGRESS, YOU SHOULD EXPECT BREAKING CHANGES AND BUGS\n```\n\n## Features\n\n- Parses command-line arguments into an autogenerated struct\n- Automatic generation of usage and help text including headers, footers, types...\n- Support for flags, options, and positional arguments\n- Support for multi-option arguments\n- You can define the separator between options and arguments\n- Provides built-in support for basic and complex argument types, including enums and JSON\n- Offers the ability to define and use custom argument types\n- Includes default validators for arguments, reducing the boilerplate code\n- Enables users to define and use custom validation rules for arguments\n- Choose between halting at the first encountered problem or collecting all problems\n- Highly customizable and easy to use\n- Lightweight with no dependencies\n- Leverages Zig's powerful compile-time feature **as much as possible**\n- Autocomplete support\n\n\n## Documentation\n\n[Un analizador de línea de comandos en Zig 🔧 (Parte I)](https://d4c7.github.io/zig-zagueando/posts/un-analizador-de-linea-de-comandos-en-zig-1/)\n\n[Un analizador de línea de comandos en Zig 🔧 (Parte II)](https://d4c7.github.io/zig-zagueando/posts/un-analizador-de-linea-de-comandos-en-zig-2/)\n\n## Install\n\n\nTo use zarg in your project, you need to add the dependency to your `build.zig.zon`:\n\n```bash\n$ zig fetch --save git+https://github.com/d4c7/zarg\n```\n\nThen you could add the module to to your `build.zig` file:\n\n```zig\nconst zarg = b.dependency(\"zarg\", .{\n    .target = target,\n    .optimize = optimize,\n});\n\nexe.root_module.addImport(\"zarg\", zarg.module(\"zarg\"));\n\n```\n\n## Usage\n\nDefine a struct that defines the command-line arguments, help texts, headers and types you want to parse:\n\n```zig\n    const clp = comptime zarg.CommandLineParser.init(.{\n        .header=\n        \\\\  ______ _ _ __ __ _ \n        \\\\ |_  / _` | '__/ _` |\n        \\\\  / / (_| | | | (_| |\n        \\\\ /___\\__,_|_|  \\__, |\n        \\\\               |___/  \n        ,.params = \u0026[_]zarg.Param{\n            help(.{ .long = \"help\", .short = \"h\", .help = \"Shows this help.\" }),\n            flag(.{ .long = \"version\", .help = \"Output version information and exit.\" }),\n            flag(.{ .long = \"verbose\", .short = \"v\", .help = \"Enable verbose output.\" }),\n            option(.{ .long = \"port\", .short = \"p\", .parser = \"TCP_PORT\", .default = \"1234\", .help = \"Listening Port.\" }),\n            option(.{ .long = \"host\", .short = \"H\", .parser = \"TCP_HOST\", .default = \"localhost\", .help = \"Host name\" }),\n            positional(.{ .parser = \"DIR\", .default = \".\", .check = \u0026Check.Dir(.{ .mode = .read_only }).f }),\n        }, \n        .desc = \"This command starts an HTTP Server and serves static content from directory DIR.\", \n        .footer = \"More info: \u003chttps://d4c7.github.io/zig-zagueando/\u003e.\",\n    });\n```\n\nThe field `params` in the struct defines the option and positional arguments.\n\nThen, in your `main` function, use the `parse` function to parse the command-line arguments:\n\n```zig\nvar s = clp.parseArgs(allocator);\ndefer s.deinit();\n\nif (s.helpRequested()) {\n    try s.printHelp(std.io.getStdErr().writer());\n    return;\n}\n\nif (s.hasProblems()) {\n    try s.printProblems(std.io.getStdErr().writer(), .all_problems);\n    return;\n}\n\nstd.debug.print(\"dir: {s}\\n\", .{s.arg.positional});\nstd.debug.print(\"port: {d}\\n\", .{s.arg.port});\nstd.debug.print(\"host: {s}\\n\", .{s.arg.host});\n\n```\n\nOutput sample\n\n```txt\n$ sample --help\n ______ _ _ __ __ _ \n|_  / _` | '__/ _` |\n / / (_| | | | (_| |\n/___\\__,_|_|  \\__, |\n              |___/ \nUsage: sample [(-h|--help)] [--version] [(-v|--verbose)] [(-p|--port)=TCP_PORT] [(-H|--host)=TCP_HOST] [DIR]\n\nThis command starts an HTTP Server and serves static content from directory DIR.\n\n  -h, --help             Shows this help.\n      --version          Output version information and exit.\n  -v, --verbose          Enable verbose output.\n  -p, --port=TCP_PORT    Listening Port.\n                         Default value: 1234\n  -H, --host=TCP_HOST    Host name\n                         Default value: localhost\n\n  TCP_PORT    TCP port value between 0 and 65535. Use port 0 to dynamically assign a port\n              Can use base prefix (0x,0o,0b). \n  TCP_HOST    TCP host name or IP. \n  DIR         Directory \n\nMore info: \u003chttps://d4c7.github.io/zig-zagueando/\u003e.\n```\n\nDetailed error reporting with `all_problems` mode:\n\n```txt\n$ zig-out/bin/sample_complete -c=black -k -p 70000 -vv\nsample_complete: \n * Unsupported value 'black' of type COLOR for option 'c': InvalidEnum (-c=black) at arg #1\n * Unrecognized option 'k' (-k) at arg #2\n * Unsupported value '70000' of type TCP_PORT for option 'p': Overflow (70000) at arg #4\n * Unexpected repeated flag 'v' (-vv) at arg #5\n * Expected between 1 and 5 Directory's, but found 0\n * Expected --alloc_opt\n * Expected 1 --array1a1's, but found 0\n * Expected between 1 and 2 --array1a2's, but found 0\n * Expected 1 --array1aN's, but found 0\nTry 'zig-out/bin/sample_complete --help' for more information.\n```\n\nView more examples in the [`examples`](examples) folder.\n\nYou can build the samples using:\n\n```\nzig build examples\n```\n## Misc\n\n### Run tests \n\n```\nzig test src/tests.zig\n```\n\n### Generate a coverture report\n\nRequire `kcov` installed\n```\nzig build cover\n```\n\nView the report \n```\nfirefox zig-out/coverture/index.html\n```\n\nNote: Since the Zig compiler exclusively compiles functions that are explicitly called or referenced and comptime can lead to substantial portions of code not being included in the runtime the coverage results only reflect the extent to which the utilized functions are covered. \n\n## Autocomplete\n\nYou can provide easily an autocompleter for a zarg command line parser. \n\n### How it works\n\nTo enable autocompletion, a command is compiled that analyzes the command line and suggests completion options based on the cursor position in that line. This command also allows installing a lightweight autocompletion script for a specific shell, which will call the autocompletion command for the heavy processing.\n\nYou can integreate in the same command or using a separate one, which is the recommended way.\n\nThe autocompleter analizes your provided CommandlineParser and suggest completions for:\n\n- Short option names\n- Long option names\n- Option argument types\n- Positional argument types\n\nThe built-in supported argument types are:\n- FILE: autocomplete with a file\n- DIR: autocomplete with a directory\n- ENUM: autocomplete with enum values\n\nYou could define your own parser with custom autocomplete behaviour.\n\n\n### How to use autocomplete\n\nIn order to generate an autocompleter command for a custom CommandlineParser use the following code: \n\n```zig\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    defer _ = gpa.deinit();\n\n    try zarg.Autocomplete.__main(my_clp, allocator);\n}\n```\n\n### Autocomplete sample\n\nA complete sample is provided:\n\n```\nzig build examples\n\nexport PATH=zig-out/bin/:$PATH\n\nsource \u003c(sample_autocomplete_completer install -s bash -t sample_autocomplete)\n# or output to /etc/bash_completion.d/\n\nsample_autocomplete --\u003cTAB\u003e\u003cTAB\u003e\n\n```\n\n### Road map\n\n- Fix and complete \n- Reorganize code\n- Data structures simplification\n- Params comptime smart param indexing \n- Documentation\n- Add missing basic parsers\n- Much more tests\n- Help structure rethink\n- Color support for help with custom styles\n- Upgrade to zig 0.14.0 (maintain branch per main zig version)\n\n\n## Caution\n\n**Please note that zarg is a work in progress being developed and tested**. If you are using a different Zig compiler version, we cannot guarantee that the library will work as expected. Before reporting any issues, please make sure you are using the recommended Zig compiler version. It is always a good practice to use the same compiler version that a library or application was developed with to avoid any compatibility issues. We are continuously working on providing support for newer versions of the Zig compiler. Please stay tuned for updates.\n\n## Contribution\n\nWe welcome all contributions! Please feel free to submit a PR or create an issue if you encounter any problem or have a feature request.\n\n## License\n\nzarg is licensed under the EUPL-1.2 license and MIT. Please check the [`LICENSES`](examples)  folder for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd4c7%2Fzarg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd4c7%2Fzarg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd4c7%2Fzarg/lists"}