{"id":32151856,"url":"https://github.com/hartbit/yaap","last_synced_at":"2025-10-21T10:54:17.332Z","repository":{"id":63911766,"uuid":"121786281","full_name":"hartbit/Yaap","owner":"hartbit","description":"Yet Another (Swift) Argument Parser","archived":false,"fork":false,"pushed_at":"2020-02-04T06:29:54.000Z","size":108,"stargazers_count":117,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-21T10:53:48.575Z","etag":null,"topics":["argparse","argparser","argument-parser","argument-parsers","argument-parsing","cli","linux","macos","shorthand-syntax","swift","swift-package-manager","swiftp","yaap","yet-another"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hartbit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-16T18:35:46.000Z","updated_at":"2025-01-13T17:45:08.000Z","dependencies_parsed_at":"2023-01-14T13:15:27.180Z","dependency_job_id":null,"html_url":"https://github.com/hartbit/Yaap","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hartbit/Yaap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartbit%2FYaap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartbit%2FYaap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartbit%2FYaap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartbit%2FYaap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hartbit","download_url":"https://codeload.github.com/hartbit/Yaap/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartbit%2FYaap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280248570,"owners_count":26297925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["argparse","argparser","argument-parser","argument-parsers","argument-parsing","cli","linux","macos","shorthand-syntax","swift","swift-package-manager","swiftp","yaap","yet-another"],"created_at":"2025-10-21T10:54:16.292Z","updated_at":"2025-10-21T10:54:17.325Z","avatar_url":"https://github.com/hartbit.png","language":"Swift","readme":"# Yaap [![version 1.0.0](https://img.shields.io/badge/version-1.0.0-brightgreen)](#installation) [![swift 5.1](https://img.shields.io/badge/swift-5.1-orange)](https://developer.apple.com/swift/) [![license MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\nYaap is Yet Another (Swift) Argument Parser that represents executable commands as types, and arguments as properties of those types. It supports:\n\n* Strongly-typed argument and option parsing\n* Automatic help and usage message generation\n* Multiple command routing\n* Smart error messages with suggestion on typos\n\nHere's a self-contained example of a `rand` executable that generates random numbers in a configurable interval to standard output, with everything from `--help` documentation, usage generation, and `--version` printing.\n\n```swift\nclass RandomCommand: Command {\n    let name = \"rand\"\n    let documentation = \"Generates a random number that lies in an interval.\"\n\n    @Argument(documentation: \"Exclusive maximum value\")\n    var maximum: Int\n\n    @Option(shorthand: \"m\", documentation: \"Inclusive minimum value\")\n    var minimum: Int = 0\n\n    let help = Help()\n    let version = Version(\"0.1.0\")\n\n    func run(outputStream: inout TextOutputStream, errorStream: inout TextOutputStream) throws {\n        guard maximum \u003e minimum else {\n            throw InvalidIntervalError(minimum: minimum, maximum: maximum)\n        }\n\n        outputStream.write(Int.random(in: minimum..\u003cmaximum).description)\n        outputStream.write(\"\\n\")\n    }\n}\n\nstruct InvalidIntervalError: LocalizedError {\n    let minimum: Int\n    let maximum: Int\n\n    var errorDescription: String? {\n        return \"invalid interval [\\(minimum), \\(maximum))\"\n    }\n}\n\nRandomCommand().parseAndRun()\n```\n\n## Installation\n\nYaap can be installed as a Swift Package Manager dependency. Here's the declaration for depending on the latest stable version:\n\n```swift\nlet package = Package(\n    dependencies: [\n        .package(url: \"https://github.com/hartbit/Yaap.git\", from: \"1.0.0\")\n    ]\n)\n```\n\n## Usage\n\n### Commands\n\nIn Yaap, a command is a self-contained operation defined as a class conforming to the `Command` protocol: arguments (if any) are defined as properties and execution logic is defined in a `run(outputStream:errorStream)` function. Simple programs only need one command but can grow more as necessary.\n\nA command must also define a `name` (the executable name), that will appear in the usage description, and an optional `documentation` property, that will appear in the help output.\n\n```swift\nclass HelloWorldCommand: Command {\n    let name = \"hello-world\"\n    let description = \"My first command\"\n\n    func run(outputStream: inout TextOutputStream, errorStream: inout TextOutputStream) throws {\n        outputStream.write(\"Hello World\")\n    }\n}\n```\n\nCommands can parse command-line arguments and run themselves with the `parseAndRun` function:\n\n```swift\nlet command = HelloWorldCommand()\ncommand.parseAndRun()\n```\n\nAny errors thrown by `run(outputStream:errorStream)` will be caught and reported to the standard error stream.\n\n### Arguments\n\nMandatory arguments are defined using the generic `Argument` type and are parsed in the order they are declared in the command. They can also be configured with an optional `name` and `documentation` that will show in the help output:\n\n```swift\nclass SplitCommand: Command {\n    let name = \"split\"\n\n    @Argument(documentation: \"The string to split.\")\n    var string: String\n\n    @Argument(name: \"separator\", documentation: \"The seperator to split the string with.\")\n    var sep: Character\n\n    func run(outputStream: inout TextOutputStream, errorStream: inout TextOutputStream) throws {\n        outputStream.write(string.split(separator: sep).joined(separator: \"\\n\"))\n        outputStream.write(\"\\n\")\n    }\n}\n```\n\n```\n$ split \"The Swift Programming Language\" \" \"\nThe\nSwift\nProgramming\nLanguage\n```\n\n### Options\n\nOptional arguments are defined using the generic `Option` type and must provide a `defaultValue`. The are parsed using the `--option value` or `--option=value` syntax where `option` is the name of the property, which can be customized with an optional `name` parameter. There is also an optional `shorthand` parameter to allow parsing them with a single character syntax of `-o value` or `-o=value`. Again, `documentation` can be provided for the help output:\n\n```swift\nclass SplitCommand: Command {\n    let name = \"split\"\n\n    @Argument\n    var string: String\n\n    @Option(name: \"separator\", shorthand: \"s\", documentation: \"The seperator to split the string with.\")\n    var sep: Character = \" \"\n\n    func run(outputStream: inout TextOutputStream, errorStream: inout TextOutputStream) throws {\n        outputStream.write(string.split(separator: sep).joined(separator: \"\\n\"))\n        outputStream.write(\"\\n\")\n    }\n}\n```\n\n```\n$ split a,b,c,d --separator ,\na\nb\nc\nd\n```\n\n### Sub-commands\n\n### Help\n\nYaap comes with a built-in `Help` property that parses `--help/-h` arguments and prints the command's detailed documentation to standard output. It can be configured with a different name and shorthand syntax. Using the `RandomCommand` example from above:\n\n```swift\nclass RandomCommand: Command {\n    let name = \"rand\"\n    let documentation = \"Generates a random number that lies in an interval.\"\n    let help = Help()\n\n    @Argument(documentation: \"Exclusive maximum value\")\n    var maximum: Int\n\n    @Option(shorthand: \"m\", documentation: \"Inclusive minimum value\")\n    var minimum: Int = 0\n\n    func run(outputStream: inout TextOutputStream, errorStream: inout TextOutputStream) throws {\n        // ...\n    }\n}\n```\n\n```\n$ rand --help\nOVERVIEW: Generates a random number that lies in an interval.\n\nUSAGE: rand [options] \u003cmaximum\u003e\n\nARGUMENTS:\n  maximum          Exclusive maximum value\n\nOPTIONS:\n  --help, -h       Display available options [default: false]\n  --minimum, -m    Inclusive minimum value [default: 0]\n```\n\n### Version\n\nYaap also comes with a built-in `Version` property that allows commands to respond to a `--version/-v` argument by printing their version number to standard output. The property can be customized to respond to a different argument name and optional shorthand syntax:\n\n```swift\nclass MyCommand: Command {\n    let name = \"program\"\n    let version = Version(\"4.2\", name: \"ver\", shorthand: nil)\n\n    func run(outputStream: inout TextOutputStream, errorStream: inout TextOutputStream) throws {\n        // ...\n    }\n}\n```\n\n```\n$ program --ver\n4.2\n```\n\n## Thanks\n\nI'd like to thank [SwiftCLI](https://github.com/jakeheis/SwiftCLI) for being a major influence in designing Yaap.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhartbit%2Fyaap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhartbit%2Fyaap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhartbit%2Fyaap/lists"}