{"id":20311064,"url":"https://github.com/dillonkearns/elm-cli-options-parser","last_synced_at":"2025-10-28T18:41:19.015Z","repository":{"id":32870554,"uuid":"138126316","full_name":"dillonkearns/elm-cli-options-parser","owner":"dillonkearns","description":"Build type-safe command-line utilities in Elm!","archived":false,"fork":false,"pushed_at":"2025-09-10T19:01:49.000Z","size":934,"stargazers_count":56,"open_issues_count":6,"forks_count":11,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-09-10T23:27:06.527Z","etag":null,"topics":["cli","elm","options-parsing"],"latest_commit_sha":null,"homepage":"","language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dillonkearns.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-21T06:04:30.000Z","updated_at":"2025-09-10T19:01:53.000Z","dependencies_parsed_at":"2024-11-14T17:37:28.858Z","dependency_job_id":"f6f26e65-1994-40e6-9b2f-97a6c90f30d4","html_url":"https://github.com/dillonkearns/elm-cli-options-parser","commit_stats":{"total_commits":607,"total_committers":5,"mean_commits":121.4,"dds":0.03953871499176276,"last_synced_commit":"15ef52647d64fb9e54dfce59f88f37249b670c0e"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/dillonkearns/elm-cli-options-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-cli-options-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-cli-options-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-cli-options-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-cli-options-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dillonkearns","download_url":"https://codeload.github.com/dillonkearns/elm-cli-options-parser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-cli-options-parser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281494241,"owners_count":26511338,"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-28T02:00:06.022Z","response_time":60,"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":["cli","elm","options-parsing"],"created_at":"2024-11-14T17:35:45.341Z","updated_at":"2025-10-28T18:41:18.974Z","avatar_url":"https://github.com/dillonkearns.png","language":"Elm","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Elm CLI Options Parser\n\n[![Build Status](https://travis-ci.org/dillonkearns/elm-cli-options-parser.svg?branch=master)](https://travis-ci.org/dillonkearns/elm-cli-options-parser)\n\n`elm-cli-options-parser` allows you to build command-line options parsers in Elm.\nIt uses a syntax similar to `Json.Decode.Pipeline`.\n\nYou can\nplay around with `elm-cli-options-parser` in a [live terminal simulation in Ellie here](https://ellie-app.com/8b8QWfcxx4Ca1)!\n\n## Example\n\nSee the [`examples`](https://github.com/dillonkearns/elm-cli-options-parser/tree/master/examples/src) folder for full end-to-end examples, including how to wire\nyour Elm options parser up through NodeJS so it can receive the command line input.\n\nTake this `git` command:\n\n```console\ngit log --author=dillon --max-count=5 --stat a410067\n```\n\nTo parse the above command, we could build a `Program` as follows (this snippet doesn't include the wiring of the OptionsParser-Line options from NodeJS, see the [`examples`](https://github.com/dillonkearns/elm-cli-options-parser/tree/master/examples/src) folder):\n\n```elm\nimport Cli.Option as Option\nimport Cli.OptionsParser as OptionsParser exposing (with)\nimport Cli.OptionsParser.BuilderState as BuilderState\nimport Cli.Program as Program\n\n\ntype CliOptions\n    = Init\n    | Clone String\n    | Log LogOptions\n\n\ntype alias LogOptions =\n    { maybeAuthorPattern : Maybe String\n    , maybeMaxCount : Maybe Int\n    , statisticsMode : Bool\n    , maybeRevisionRange : Maybe String\n    , restArgs : List String\n    }\n\nprogramConfig : Program.Config CliOptions\nprogramConfig =\n    Program.config\n        |\u003e Program.add\n            (OptionsParser.buildSubCommand \"init\" Init\n                |\u003e OptionsParser.withDoc \"initialize a git repository\"\n            )\n        |\u003e Program.add\n            (OptionsParser.buildSubCommand \"clone\" Clone\n                |\u003e with (Option.requiredPositionalArg \"repository\")\n            )\n        |\u003e Program.add (OptionsParser.map Log logOptionsParser)\n\n\nlogOptionsParser : OptionsParser.OptionsParser LogOptions BuilderState.NoMoreOptions\nlogOptionsParser =\n    OptionsParser.buildSubCommand \"log\" LogOptions\n        |\u003e with (Option.optionalKeywordArg \"author\")\n        |\u003e with\n            (Option.optionalKeywordArg \"max-count\"\n                |\u003e Option.validateMapIfPresent String.toInt\n            )\n        |\u003e with (Option.flag \"stat\")\n        |\u003e OptionsParser.withOptionalPositionalArg\n            (Option.optionalPositionalArg \"revision range\")\n        |\u003e OptionsParser.withRestArgs\n            (Option.restArgs \"rest args\")\n```\n\n```elm\n{-\nNow running:\n`git log --author=dillon --max-count=5 --stat a410067`\nwill yield the following output (with wiring as in the [`examples`](https://github.com/dillonkearns/elm-cli-options-parser/tree/master/examples/src) folder):\n-}\nmatchResult : CliOptions\nmatchResult =\n    Log\n        { maybeAuthorPattern = Just \"dillon\"\n        , maybeMaxCount = Just 5\n        , statisticsMode = True\n        , revisionRange = Just \"a410067\"\n        }\n```\n\nIt will also generate the help text for you, so it's guaranteed to be in sync.\nThe example code above will generate the following help text:\n\n```console\n$ ./git --help\ngit log [--author \u003cauthor\u003e] [--max-count \u003cmax-count\u003e] [--stat] [\u003crevision range\u003e]\n```\n\nNote: the `--help` option is a built-in command, so no need to write a `OptionsParser` for that.\n\n## Design Goals\n\n1. **Build in great UX by design**\n   For example, single character options like `-v` can be confusing.\n   Are they always confusing? Maybe not, but eliminating the possibility makes\n   things much more explicit and predictable.\n   For example, `grep -v` is an alias for `--invert-match` (`-V` is the alias\n   for `--version`). And there is a confusing and somewhat ambiguous syntax for\n   passing arguments to single character flags\n   (for example, you can group multiple flags like `grep -veabc`, which is the\n   same as `grep --invert-match --regexp=abc`). This is difficult for humans to\n   parse or remember, and this library is opinionated about doing things in a\n   way that is very explicit, unambiguous, and easy to understand.\n\n   Another example, the `--help` flag should always be there and work in a standard way...\n   so this is baked into the library rather than being an optional or a manual\n   configuration.\n\n1. **Guaranteed to be in-sync** - by automatically generating help messages\n   you know that users are getting the right information. The design of the\n   validation API also ensures that users get focused errors that point to\n   exactly the point of failure and the reason for the failure.\n\n1. **Be explicit and unambiguous** - like the Elm ethos, this library aims to give you very clear error\n   messages the instant it knows the options can't be parsed, rather than when it\n   discovers it's missing something it requires. For example, if you\n   pass in an unrecognized flag, you will immediately get an error with typo\n   suggestions.\n   Another example, this library [enforces that you don't specify an ambiguous mix of optional\n   and required positional args](#todo-link). This could easily be fixed with\n   some convention to move all optional arguments to the very end regardless of\n   what order you specify them in, but this would go against this value of\n   explicitness.\n\n## Options Parser Terminology\n\nHere is a diagram to clarify the terminology used by this library. Note that\nterms can vary across different standards. For example, posix uses the term\n`option` for what this library calls a `keyword argument`. I chose these terms\nbecause I found them to be the most intuitive and unambiguous.\n\n![Terminology Legend](https://raw.githubusercontent.com/dillonkearns/elm-cli-options-parser/master/terminology.png)\n\n## Some Inspiration for this package\n\n- http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html.\n- https://pythonconquerstheuniverse.wordpress.com/2010/07/25/command-line-syntax-some-basic-concepts/\n- https://devcenter.heroku.com/articles/cli-style-guide\n- http://docopt.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdillonkearns%2Felm-cli-options-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdillonkearns%2Felm-cli-options-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdillonkearns%2Felm-cli-options-parser/lists"}