{"id":17092701,"url":"https://github.com/onelivesleft/simple_parseopt","last_synced_at":"2025-03-23T16:33:43.217Z","repository":{"id":171691262,"uuid":"223807915","full_name":"onelivesleft/simple_parseopt","owner":"onelivesleft","description":"Nim module which provides clean, zero-effort command line parsing","archived":false,"fork":false,"pushed_at":"2021-10-07T11:17:16.000Z","size":2270,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-28T22:44:15.130Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","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/onelivesleft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELIST.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":"2019-11-24T20:47:43.000Z","updated_at":"2024-05-27T18:14:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"685a6f4a-9383-4c4f-8c70-bb1342bd9fa1","html_url":"https://github.com/onelivesleft/simple_parseopt","commit_stats":null,"previous_names":["onelivesleft/simple_parseopt"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onelivesleft%2Fsimple_parseopt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onelivesleft%2Fsimple_parseopt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onelivesleft%2Fsimple_parseopt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onelivesleft%2Fsimple_parseopt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onelivesleft","download_url":"https://codeload.github.com/onelivesleft/simple_parseopt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245131891,"owners_count":20565917,"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","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":[],"created_at":"2024-10-14T14:02:07.608Z","updated_at":"2025-03-23T16:33:43.186Z","avatar_url":"https://github.com/onelivesleft.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# simple_parseopt\nNim module which provides clean, zero-effort command line parsing.\n\n---\n\n## Basic Use\n\nThis module gives you two ways to parse the command line: `get_options` and `get_options_and_supplied`\n\n\n**get_options**\n\nAt its simplest, declare a block like this:\n\n```nim\n# foo.nim\n\nlet options = get_options:\n    name          = \"Default Name\"\n    active        = false\n    letter_one    = 'a'\n    age           = 1\n    hello:string\n    big:float64   = 1.1\n    small:float   = 2.2\n    flat:uint     = 2\n    arguments:seq[string]\n\necho options.name \u0026 \" is \" \u0026 options.age.repr \u0026 \" years old!\"\n```\n\nNotice it follows the same syntax as a `var` block.\n\nIn the example `foo.nim` above, the variable `options` will be set to an `object` with fields as described in the `get_options` block.  Each field will also be set up as a command-line parameter for the user running the program to use; bools will toggle, while other fields will take a value argument.\n\n```bash\nfoo -name \"J. Random\" -active -big 1011121.121498 -letter-one z\n```\n\nThis will set the `name` `string` to `\"J. Random\"`, toggle the `active` `bool` to `true`, set the `big` `float64` to `1011121.121498`, and set `letter_one` to `z` (notice the underscore in the field becomes a hyphen at the command line).\n\nYou may use any basic type: `bool`, `string`, `int`, `float`, `uint`, `char`, and the sized variants thereof, as well as `seq`s of those types: `seq[string]`, `seq[int]`, `seq[float]`, etc. (You may not use `seq[bool]`)\n\nThe last `seq[string]` will automatically be used to store any arguments set without a parameter name (you can disable this behaviour with `no_implicit_bare()`)\n\n\n*Details*\n\nThe code above will translate into the equivalent of:\n\n```nim\ntype Options = object\n    name:string\n    active:bool\n    letter_one:char\n    age:int\n    hello:string\n    big:float64\n    small:float\n    flat:uint\n    arguments:seq[string]\n\noptions = Options(name: \"Default Name\", active: false, letter_one: 'a', age: 1, big: 1.1, small: 2.2, flat: 2)\n\nparse_command_line_into(options)\n```\n\nWhere `parse_command_line_into` is some hypothetical procedure which parses the user-supplied command line and sets fields in `options` appropriately.\n\n---\n\n**get_options_and_supplied**\n\nUsing a `get_options_and_supplied` block will behave just like `get_options`, except it will return a tuple of two objects.  The first is as detailed above.  The second object will have identical field names, but all its fields will be of type `bool`.\n\nAny field which the user has supplied on the command line will have its `bool` in the second object set to `true`.\n\n```nim\n# foo.nim\n\nlet (options, supplied) = get_options_and_supplied:\n    name          = \"Default Name\"\n    active        = false\n    letter        = 'a'\n    age           = 1\n    big:float64   = 1.1\n    small:float   = 2.2\n    flat:uint     = 2\n    hello:string\n\nif supplied.name and supplied.age:\n    echo options.name \u0026 \" is \" \u0026 options.age.repr \u0026 \" years old!\"\n```\n\n---\n\n## Default command-line syntax\n\nBy default, each named parameter may be set on the command line by the user prefixing it with a `-` or a `/`.  For `bool` fields, this will toggle the field.  For other fields, the next argument on the command line is used to set the field.\n\nAll of these will work:\n\n```bash\nfoo -name \"Joe Random\" -active\nfoo /active /flat 100\nfoo /hello Greetings! -big 100 /small 20\n```\n\n---\n\n## Extra Parameter Info: Pragmas\n\nYou may also add pragmas to the end of any line to modify parameter behaviour.  Each pragma has a more verbose alias, if you prefer that style of code.\n\n* `{. info(\"text\") .}` *or* `{. description(\"text\") .}`\n\n    Description of the parameter which will be shown in help text.\n\n\n* `{. aka(\"a\", \"b\", ...) .}` *or* `{. alias(\"a\", \"b\", ...) .}`\n\n    Aliases for the parameter - user may use these as parameters; they will write to the field.\n\n\n* `{. bare .}` *or* `{. positional .}`\n\n    Accepts a bare, positional argument (an argument which has not been prefixed with a parameter name).  User will not be able to refer to the argument with its parameter name.\n\n\n* `{. need .}` *or* `.{ required .}`\n\n    Parameter must be supplied by user or an error is shown.\n\n\n* `{. len(i) .}` *or* `.{ count(i) .}`\n\n    Place on a `seq` field to require that many values be supplied to it. For example:\n\n    `position:seq[float] {. len(3) .} # x y z`\n\n    Note that this does not set a limit on the total length of the `seq`, only on how many values the user must specify.  Using `len` in conjunction with the `allow_repetition` setting, you can accept multiple batches of values (see `normalize.nim` example)\n\n---\n\n## Settings\n\nYou may tailor the parser with the following calls:\n\n\n* **no_dash()**\n\n    Disable parameter being identified by prefixing with `-`\n\n\n* **no_slash()**\n\n    Disable parameter being identified by prefixing with `/`\n\n\n* **dash_dash_parameters()**\n\n    Require that parameters which have more than one character in their name be prefixed with `--` instead of `-`. Single-character parameters may then be entered grouped together under one `-`\n\n* **dash_dash_separator()**\n\n    `--` on its own in the command line will disable parameter names on every argument after it; they will all be treated as bare\n\n* **value_after_colon()**\n\n    Allow the user to specify parameter \u0026 value together, separated by a `:`\n\n    e.g. `-param:value`\n\n    Note this will not play nicely with quoted string values.\n\n* **value_after_equals()**\n\n    Allow the user to specify parameter \u0026 value together, separated by a `=`\n\n    e.g. `-param=value`\n\n    Note this will not play nicely with quoted string values.\n\n* **allow_repetition()**\n\n    Allow the user to specify the same parameter more than once without reporting an error.\n\n* **allow_errors()**\n\n    Allow program execution to continue after erroneous input.\n\n* **no_implicit_bare()**\n\n    Do not automatically use the last `seq[string]` parameter to gather any bare parameters the user enters (they become erroneous instead)\n\n* **can_name_bare()**\n\n    Allows user to set bare parameters by name.\n\n* **manual_help()**\n\n    Disable automatic generation of help message when user enters `-?`, `-h` or `-help` (when you do not include them as parameters)\n\n\n* **command_name(name: string)**\n\n    Set the name of the executable, for use in the auto-generated\n    help-message when the user enters `-?`, `-h`, or `-help`.\n\n    Note: `command_name` may not be included in a `config:` chain\n\n\n* **help_text(text: string, footer = \"\")**\n\n    Set the text which is included in the auto-generated help-message when the user enters `-?`, `-h`, or `-help`.\n\n    * `text` is displayed at the top, before the parameters.\n    * `footer` is displayed at the bottom, after them.\n\n    Note: `help_text` may not be included in a `config:` chain\n\n* **config:**\n\n    A helper macro which allows you to specify the above options (except `help_text` and `command_name`) as a call chain.  For example:\n\n    `simple_parseopt.config: no_slash.dash_dash_parameters.allow_repetition`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonelivesleft%2Fsimple_parseopt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonelivesleft%2Fsimple_parseopt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonelivesleft%2Fsimple_parseopt/lists"}