{"id":22423333,"url":"https://github.com/prantlf/v-cargs","last_synced_at":"2026-02-15T18:33:35.594Z","repository":{"id":174315280,"uuid":"652057095","full_name":"prantlf/v-cargs","owner":"prantlf","description":"Parses command-line arguments to statically typed options with the help of usage description.","archived":false,"fork":false,"pushed_at":"2025-08-31T17:16:27.000Z","size":190,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-04T19:43:15.552Z","etag":null,"topics":["args","args-parser","getopt","getopt-long","vlang","vlang-package"],"latest_commit_sha":null,"homepage":"","language":"V","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/prantlf.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-06-11T00:19:17.000Z","updated_at":"2025-08-31T17:16:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"ea236474-b2e1-41d4-8f1a-4475f80b4d54","html_url":"https://github.com/prantlf/v-cargs","commit_stats":null,"previous_names":["prantlf/v-cargs"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/prantlf/v-cargs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-cargs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-cargs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-cargs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-cargs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/v-cargs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-cargs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29486541,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T15:33:17.885Z","status":"ssl_error","status_checked_at":"2026-02-15T15:32:53.698Z","response_time":118,"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":["args","args-parser","getopt","getopt-long","vlang","vlang-package"],"created_at":"2024-12-05T18:10:08.352Z","updated_at":"2026-02-15T18:33:35.578Z","avatar_url":"https://github.com/prantlf.png","language":"V","readme":"# Command-line Arguments\n\nParses command-line arguments to statically typed options or a string map with the help of usage description.\n\n* Legible configuration inferred from the usage instructions text.\n* Full control over the usage text.\n* Checks for unknown and required options, invalid value types and arithmetic overflow.\n* Compatibility with the [getopt and getopt_long] standards.\n\n## Synopsis\n\nSpecify usage description and version of the command-line tool. Declare a structure with all command-line options. Import the command-line parser and parse the options and arguments:\n\n```go\nimport prantlf.cargs { parse, Input }\n\n// Describe usage of the command-line tool.\nusage := 'Converts YAML input to JSON output.\n\nUsage: yaml2json [options] [\u003cyaml-file\u003e]\n\n  \u003cyaml-file\u003e         read the YAML input from a file\n\nOptions:\n  -o|--output \u003cfile\u003e   write the JSON output to a file\n  -i|--indent \u003ccount\u003e  write the JSON output to a file\n  -p|--pretty          print the JSON output with line breaks and indented\n  -V|--version         print the version of the executable and exit\n  -h|--help            print the usage information and exit\n\nIf no input file is specified, it will be read from standard input.\n\nExamples:\n  $ yaml2json config.yaml -o config.json -p\n  $ cat config.yaml | yaml2json \u003e config.json'\n\n// Declare a structure with all command-line options.\nstruct Opts {\n  output string\n  indent int\n  pretty bool\n}\n\n// Parse command-line options and arguments.\nopts, args := parse[Opts](usage, Input{ version: '0.0.1' })!\nif args.len \u003e 0 {\n  // Process file names from the args array.\n} else {\n  // Read from the standard input.\n}\n```\n\n## Installation\n\nYou can install this package either from [VPM] or from GitHub:\n\n```txt\nv install prantlf.cargs\nv install --git https://github.com/prantlf/v-cargs\n```\n\n## API\n\nThe following functions and types are exported:\n\n### parse[T](usage string, input Input) !(T, []string)\n\nParses the command line, separating options and other arguments. Options will be set to the statically-typed structure and other arguments returned as an array of strings. The list of options will be inferred from the usage description.\n\n```go\nimport prantlf.cargs { parse, Input }\n\nusage := '...\n\nOptions:\n  -o|--output \u003cfile\u003e  write the JSON output to a file\n  -p|--pretty         print the JSON output with line breaks and indented\n\n...'\n\nstruct Opts {\n  output string\n  pretty bool\n}\n\nopts, args := parse[Opts](usage, Input{ version: '0.0.1' })!\n```\n\n### parse_to[T](usage string, input Input, mut opts T) ![]string\n\nParses the command line, separating options and other arguments, while setting the field values in an already created object. It can be used to override options initially read from configuration file from the command-line or defaults, for example.\n\n```go\nimport prantlf.cargs { parse_to, Input }\n\nusage := '...\n\nOptions:\n  -o|--output \u003cfile\u003e  write the JSON output to a file\n  -p|--pretty         print the JSON output with line breaks and indented\n\n...'\n\nstruct Opts {\n  output string\n  pretty bool\n}\n\nmut opts := Opts{ output: 'out.json' }\nargs := parse_to[Opts](usage, Input{ version: '0.0.1' }, mut opts)!\n```\n\nSee [prantlf.config] for more information.\n\n### scan(usage string, input Input) !Scanned\n\nParses the command line, only analysing the usage description and splitting command-line argument groups. It can be used for splitting the two phases - analysis and command-line argument processing. The argument processing can be finished by `parse_scanned` or `parse_scanned_to`. Before that, a single option can be obtained by `get_val`, for example.\n\n```go\nimport prantlf.cargs { scan, parse_scanned_to, Input }\n\nusage := '...\n\nOptions:\n  -o|--output \u003cfile\u003e  write the JSON output to a file\n  -p|--pretty         print the JSON output with line breaks and indented\n\n...'\n\nstruct Opts {\n  output string\n  pretty bool\n}\n\ninput := Input{ version: '0.0.1' }\nscanned := scan(usage, input)!\n...\nmut opts := Opts{ output: 'out.json' }\nargs := parse_scanned_to[Opts](scanned, input, mut opts)!\n```\n\n### pub fn needs_val(scanned Scanned, arg_name string) !bool\n\nChecks if the specified argument is valid and returns if it needs a value on the command line. This can be used in a generic code together with `get_val` and `get_flag`.\n\n### get_val(scanned Scanned, arg_name string, def_val string) !string\n\nPartially parses the command line to get only the value of one argument. This argument usually decides about default values or other processing before the other command-line arguments will be parsed.\n\n```go\nimport prantlf.cargs { scan, get_val, parse_scanned_to, Input }\nimport prantlf.config { read_config_to }\n\nusage := '...\n\nOptions:\n  -c|--config \u003cname\u003e  name or path to the configuration file\n  -p|--pretty         print the JSON output with line breaks and indented\n\n...'\n\nstruct Opts {\n  pretty bool\n}\n\ninput := Input{ version: '0.0.1' }\nscanned := scan(usage, input)!\nconfig := get_val(scanned, 'config', '')!\nmut opts := Opts{}\nif config != '' {\n  read_config_to(config_name, mut opts)!\n}\nargs := parse_scanned_to(scanned, input, mut opts)!\n```\n\n### get_flag(scanned Scanned, arg_name string) !bool\n\nPartially parses the command line to test only if the argument is present. This argument usually decides about default values or other processing before the other command-line arguments will be parsed.\n\n```go\nimport prantlf.cargs { scan, get_flag, Input }\nimport prantlf.config { write_config }\n\nusage := '...\n\nOptions:\n  -c|--config \u003cname\u003e  name or path to the configuration file\n  -i|--init           create the configuration file with default values\n  -p|--pretty         print the JSON output with line breaks and indented\n\n...'\n\nstruct Opts {\n  pretty bool\n}\n\ninput := Input{ version: '0.0.1' }\nscanned := scan(usage, input)!\nif get_flag(scanned, 'i')! {\n  write_config('config.ini', Opts{})!\n}\n```\n\n### parse_scanned[T](scanned Scanned, input Input) !(T, []string)\n\nFinishes parsing the command line using previously analysed usage instructions. Calling the combination of `scan` and `parse_scanned` is the same as calling `parse`.\n\n```go\nimport prantlf.cargs { scan, parse_scanned, Input }\n\nusage := '...\n\nOptions:\n  -o|--output \u003cfile\u003e  write the JSON output to a file\n  -p|--pretty         print the JSON output with line breaks and indented\n\n...'\n\nstruct Opts {\n  output string\n  pretty bool\n}\n\ninput := Input{ version: '0.0.1' }\nscanned := scan(usage, input)!\n...\nopts, args := parse_scanned[Opts](scanned, input)!\n```\n\n### parse_scanned_to[T](scanned Scanned, input Input, mut opts T) ![]string\n\nFinishes parsing the command line using previously analysed usage instructions. Calling the combination of `scan` and `parse_scanned_to` is the same as calling `parse_to`.\n\n```go\nimport prantlf.cargs { scan, parse_scanned_to, Input }\n\nusage := '...\n\nOptions:\n  -o|--output \u003cfile\u003e  write the JSON output to a file\n  -p|--pretty         print the JSON output with line breaks and indented\n\n...'\n\nstruct Opts {\n  output string\n  pretty bool\n}\n\ninput := Input{ version: '0.0.1' }\nscanned := scan(usage, input)!\n...\nmut opts := Opts{ output: 'out.json' }\nargs := parse_scanned_to[Opts](scanned, input, mut opts)!\n```\n\n### Usage Instructions\n\nThe `usage` parameter is the formatted text to be presented as usage instructions. It's supposed to contain a line Starting with `Options:`, which is followed by links listing the options:\n\n    Options:\n      -o|--output \u003cfile\u003e  write the JSON output to a file\n      -p|--pretty         print the JSON output with line breaks and indented\n\nAn option-line can contain a short (single-letter) option, a long option or both. The option can be either a boolean flag or an variable with a value.\n\n    -p             a boolean flag, short variant only\n    --line-breaks  a boolean flag, long variant only\n    -v|--verbose   a boolean flag, both short and long variants\n    -o \u003cfile\u003e      a variable with a value\n\nShort and long option variants can be delimited either by `|` or by `,`, which can be followed by a space. A value of a variable can be enclose either in `\u003c` and `\u003e`, or in `[` and `]`.\n\nIf a negative option is entered, the field in the options structure has to be still positive - without the `no_` prefix. This is usually used to declare flags, which are enabled by default and can be disabled by the negative option:\n\n    --no-line-breaks  a boolean flag, long variant only\n\n### Options\n\nTwo command-line options will be recognised and processed by the `parse` function itself:\n\n* `-V|--version` - print the version of the executable and exit\n* `-h|--help` - print the usage information and exit\n\nShort (single-letter) options can be condensed together. For example, instead of `-l -p`, you can write `-lp` on the command line.\n\nNames of fields in the options structure are inferred from the command-line option names with several changes to ensure valid V syntax:\n\n* The long variant of an option will be mapped to its field name. The short variant will be used only if the long variant is missing.\n* Upper-case letters will converted to lower-case.\n* Dashes (`-`) in an option name will be converted to underscores (`_`) in its field name.\n* No negative names (starting with `no_`). If you want to specify a negative option (the short one using a capital letter and the long one starting with `--no-`), you can, but the field has to be positive and assigned the default value `true`. Then you can detect the presence of the negative option by a comparison to `false`.\n\nIf you write a short (single-letter) option for a boolean flag in upper-case, it will set the value `false` to the boolean field instead of `true`. If you write a long option for a boolean flag, you can negate its value by prefixing the option with `no-`:\n\n    -P --no-line-breaks\n\nEnum field types can be filled either by an integer or by the (string) name of the enum value.\n\nAssigning boolean flags or variable values to option fields may fail. For example:\n\n* If there's no field with the long name of the option.\n* If the field type is boolean but the option isn't a boolean flag or vice versa.\n* If the field type isn't a string and the field value cannot be converted from the string value.\n* If the numeric field type is too small to accommodate the number converted from the string value.\n\nAn option with a value can be entered multiple times. All values can be stored in an array, for example:\n\n```go\nusage := '...\n\nOptions:\n  -n, --numbers \u003cnumber\u003e  a list of numbers to use\n\n...'\n\nstruct Opts {\n  numbers []int\n}\n```\n\n### Other Arguments\n\nAn option starts with `-` or `--` and has to consist of at least one more letter. A single dash (`-`) isn't an option, but another argument. An argument not starting with a dash (`-`) is a plain argument and not an option.\n\nIf you want to handle some argument as other arguments and not as options, put two dashes (`--`) on the command line and appends such arguments behind it. The two dashes (`--`) will be ignored. If you need the two dashes (`--`) as another argument, append them once more after the first ones to the command line.\n\n### Input Fields\n\nThe following input fields are available:\n\n| Field                    | Type        | Default     | Description                                                  |\n|:-------------------------|:------------|:------------|:-------------------------------------------------------------|\n| `version`                | `string`    | `'unknown'` | version of the tool to print if `-V|--version` is requested  |\n| `args`                   | `?[]string` | `none`      | raw command-line arguments, defaults to `os.args[1..]`       |\n| `disable_short_negative` | `bool`      | `false`     | disables handling uppercase letters as negated options       |\n| `ignore_number_overflow` | `bool`      | `false`     | ignores an overflow when converting numbers to option fields |\n| `options_anywhere`       | `bool`      | `false`     | do not look for options only after the line with `Options:`  |\n| `no_negative_options`    | `bool`      | `false`     | do not recognise options starting with `no-` as negations    |\n\n### Advanced\n\nIf the transformation of options name to field name [described above](#options) is not enough, the argument name can be assigned to a specific field by the attribute `arg`. For example, set the command-line argument `type` to a field `typ`:\n\n```go\nusage := '...\n\nOptions:\n  -t|--type \u003ctype\u003e  file type (text or binary)\n\n...'\n\nstruct Opts {\n  typ string [arg: @type]\n}\n```\n\nIf you don't want to disable the checks for arithmetic overflow globally, but only for one field, it's possible by the attribute `nooverflow`. For example, set the command-line argument `type` to a field `typ`:\n\n```go\nusage := '...\n\nOptions:\n  -r|--random \u003cnumber\u003e  the value to initialize random number generator with\n\n...'\n\nstruct Opts {\n  random i16 [nooverflow]\n}\n```\n\nIf you require an option to be always entered, it's possible by the attribute `required`. For example:\n\n```go\nusage := '...\n\nOptions:\n  -f|--file \u003cname\u003e  the name of the output file\n\n...'\n\nstruct Opts {\n  file string [required]\n}\n```\n\nIf you need to supply multiple values for an option and you want to use more condensed syntax then repeating the option on the command line, you can supply all values only once, if there's a separator, which otherwise cannot be present within a value. For example, you can supply two comma-delimited integers as `-n 1,2` by the attribute `split`:\n\n```go\nusage := '...\n\nOptions:\n  -n, --numbers \u003cnumber\u003e  a list of numbers to use\n\n...'\n\nstruct Opts {\n  numbers []int [split]\n}\n```\n\nThe default separator is `,` (comma). If you need a different one, you can choose the separator by the same attribute. For example, you can supply two semicolon-delimited characters as `-c a;b` by the attribute `split`:\n\n```go\nusage := '...\n\nOptions:\n  -c, --chars \u003cchar\u003e  allowed characters\n\n...'\n\nstruct Opts {\n  numbers []rune [split: ';']\n}\n```\n\n## Contributing\n\nIn lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.\n\n## License\n\nCopyright (c) 2023-2025 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[VPM]: https://vpm.vlang.io/packages/prantlf.cargs\n[getopt and getopt_long]: https://en.wikipedia.org/wiki/Getopt\n[prantlf.config]: https://github.com/prantlf/v-config\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fv-cargs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Fv-cargs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fv-cargs/lists"}