{"id":21586726,"url":"https://github.com/behringer24/argumentative","last_synced_at":"2025-07-10T11:14:26.058Z","repository":{"id":143571426,"uuid":"616187556","full_name":"behringer24/argumentative","owner":"behringer24","description":"Go command line argument parser fast and simple","archived":false,"fork":false,"pushed_at":"2023-04-01T15:43:51.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T09:17:09.553Z","etag":null,"topics":["argparse","argument-parser","cli-parser","command","command-line","go","golang","golang-package","library","lin","package"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/behringer24.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2023-03-19T21:13:45.000Z","updated_at":"2023-03-21T21:15:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"e75d608f-c863-4d95-bc1b-76d032b6be09","html_url":"https://github.com/behringer24/argumentative","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/behringer24/argumentative","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behringer24%2Fargumentative","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behringer24%2Fargumentative/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behringer24%2Fargumentative/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behringer24%2Fargumentative/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/behringer24","download_url":"https://codeload.github.com/behringer24/argumentative/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/behringer24%2Fargumentative/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264569492,"owners_count":23629605,"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":["argparse","argument-parser","cli-parser","command","command-line","go","golang","golang-package","library","lin","package"],"created_at":"2024-11-24T15:14:30.060Z","updated_at":"2025-07-10T11:14:26.042Z","avatar_url":"https://github.com/behringer24.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# argumentative\nGo argument parser fast and simple\n\n[![Build + Test](https://github.com/behringer24/argumentative/actions/workflows/go.yml/badge.svg)](https://github.com/behringer24/argumentative/actions/workflows/go.yml) \n[![Go Reference](https://pkg.go.dev/badge/github.com/behringer24/argumentative.svg)](https://pkg.go.dev/github.com/behringer24/argumentative)\n\nhttps://pkg.go.dev/github.com/behringer24/argumentative\n\n\n## Why\nI experimented with a lot of Go command line argument parsers to build simple but powerful cli applications. I like the way that pythons _argparse_ module works, but did not find a suitable replacemant for my current Go projects. Some seem to be abandoned and even the big framework-like tools did not handle positional arguments like I would like them to work. So this is because and because: Why not?\n\n## Installation\n```\ngo get -u -v github.com/behringer24/argumentative\n```\n\n### Dependencies\nThere are no dependencies beside the \"fmt\", so thats a \"no dependencies\".\n\n## Usage\nThe simple structure of the argumentative package, that is required to get your parameters is:\n\n* init a flags object from the package\n* define you flags\n* call the Parse method to get the values\n* handle the errors or override flags and display the usage instructions\n\n_Overriding flags_ are flags that should work even when other errors where happening. The most popular examples are `--help|-h` or `--version|-v` that should display results and make a clean exit even if required arguments are missing (The user wants to learn about these by calling `-h` for example)\n\nExample 'argtest.go' file\n``` Golang\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/behringer24/argumentative\"\n)\n\nconst (\n\ttitle       = \"argtest\"\n\tdescription = \"A small demonstration\"\n\tversion     = \"v0.0.1\"\n)\n\nvar (\n\ttest1       *string\n\ttest2       *string\n\tinFileName  *string\n\toutFileName *string\n\tshowHelp    *bool\n\tshowVer     *bool\n)\n\nfunc parseArgs() {\n\tflags := \u0026argumentative.Flags{}\n\ttest1 = flags.Flags().AddString(\"test\", \"t\", true, \"\", \"A small description of the test string flag\")\n\ttest2 = flags.Flags().AddString(\"norequired\", \"n\", false, \"norequireddefault\", \"Another description\")\n\tshowHelp = flags.Flags().AddBool(\"help\", \"h\", \"Show this help text\")\n\tshowVer = flags.Flags().AddBool(\"version\", \"\", \"Show version information\")\n\tinFileName = flags.Flags().AddPositional(\"infile\", true, \"\", \"File to read from\")\n\toutFileName = flags.Flags().AddPositional(\"outfile\", false, \"\", \"File to write to\")\n\n\terr := flags.Parse(os.Args)\n\tif *showHelp {\n\t\tflags.Usage(title, description, nil)\n\t\tos.Exit(0)\n\t} else if *showVer {\n\t\tfmt.Print(title, \"version\", version)\n\t\tos.Exit(0)\n\t} else if err != nil {\n\t\tflags.Usage(title, description, err)\n\t\tos.Exit(1)\n\t}\n}\n\nfunc main() {\n\tparseArgs()\n\n\tfmt.Println(\"\\nResult:\", *test1, *test2, *inFileName, *outFileName, *showHelp, *showVer)\n}\n```\n\nIn the var block all the parameter holders are defined. argumentative returns pointers to the internal value fields and fills them after the ``flags.Parse(os.Args)`` call.\n\nParsing of the parameters has been move out of ``main()`` into its own 'parseArgs' function.\n\nThere are also the definitions of all available parameters and arguments for this demo app.\n\n```\ngo run .\\argtest.go -h\n```\nresult in the output:\n```\nargtest\nA small demonstration\n\nUsage: argtest [-h] [--version] [-n] -t infile [outfile]\n\nFlags:\n-h, --help               Show this help text\n--version                Show version information\n\nOptions:\n-t, --test               A small description of the test string flag\n-n, --norequired         Another description (Default: norequireddefault)\n\nPositional arguments:\ninfile                   File to read from\noutfile                  File to write to\n```\nomitting a required parameter results in an error message. In this case as an example we omit the required `-t` parameter:\n```\ngo run .\\argtest.go foo\n```\nresults in the output:\n```\nError: required flag --test missing\n\nUsage: argtest [-h] [--version] -t [-n] infile [outfile]\n\nFlags:\n-h, --help               Show this help text\n--version                Show version information\n\nOptions:\n-t, --test               A small description of the test string flag\n-n, --norequired         Another description (Default: norequireddefault)\n\nPositional arguments:\ninfile                   File to read from\noutfile                  File to write to\nexit status 1\n```\nNotice that we satisfied the required parameter `infile` with `foo` in the above example.\n\nIf we add a parameter `--version` or `--help` the output of the errors of the missing parameters is supressed. This behavior has to be handled in the application code and is _not_ part of the argumentative lib.\n\n## Add Parameters to your cli app\n### Add boolean parameter\nBoolean parameters are simple switches that return true if they are present and false if they are omitted. They do not support a default value or a required flag.\n\n``` Golang\nvar result *bool\n\nflags := \u0026argumentative.Flags{}\nresult = flags.Flags().AddBool(\"longname\", \"short\", \"Descriptive help text\")\n```\n\n`longname` is the long version of the parameter and must not contain space chars. On the commandline the long parameter will be preceeded by two dashes '--'\n\n`short` the one character short version of the parameter, like the `-h` for `--help`. This can only be one character. The short version is optional (see the above example vor `--version`). The short version is preceeded with one dash '-'.\n\n`Descriptive help text` A brief description of the parameter. Keep it short and simple, may be omitted but why should you?\n\n`.Flags{}.` in the above call makes sure, that the internal flags storages are initialized and is simply chained.\n\n### Add string parameter\nString parameters are like boolean parameters but always contain an additional value after the parameter seperated with a space char from the short or long parameter name. They return a string, can be optional or required and may contain a default value (which makes switching to 'required' obsolete).\n\n``` Golang\nvar result *string\n\nflags := \u0026argumentative.Flags{}\nresult = flags.Flags().AddString(\"longname\", \"short\", required, \"default\", \"Descriptive help text\")\n```\n\n`longname` is the long version of the parameter and must not contain space chars. On the commandline the long parameter will be preceeded by two dashes '--'\n\n`short` the one character short version of the parameter, like the `-h` for `--help`. This can only be one character. The short version is optional (see the above example vor `--version`). The short version is preceeded with one dash '-'.\n\n`required` a boolean _true_ or _false_ if this parameter is required (true). If this parameter is omitted it will stop execution and display an error text and the usage instructions.\n\n`default` The default value of the parameter (if not present in the cli call). If there is a default value it makes no sense to set the parameter to required, too. \n\n`Descriptive help text` A brief description of the parameter. Keep it short and simple, may be omitted but why should you?\n\n### Positional arguments\nPositional arguments are parameters without a short or long name and come in a specific order, the order you defined them in. They can be required or have a default value. They return a string. For displaying the arguments in the help text, they require a `longname`.\n\n``` Golang\nvar result *string\n\nflags := \u0026argumentative.Flags{}\nresult = flags.Flags().AddPositional(\"longname\", required, \"default\", \"Descriptive help text\")\n```\n\n`longname` is the name of the parameter and must not contain space chars. The name will be shown on the Usage instruction line and in the brief description section of the help text.\n\n`required` a boolean _true_ or _false_ if this parameter is required (true). If this parameter is omitted it will stop execution and display an error text and the usage instructions. \n\n`default` The default value of the parameter (if not present in the cli call). If there is a default value it makes no sense to set the parameter to required, too.\n\n`Descriptive help text` A brief description of the parameter. Keep it short and simple, may be omitted but why should you?\n\nConsider the order of positional arguments in your command line. Optional arguments must come last as they would be confused with other arguments. Required arguments must come first. If you are struggling consider to use named string flags.\n\n## License\n\nArgumentative is released under the GNU GENERAL PUBLIC LICENSE Version 3. See [LICENSE](https://github.com/behringer24/argumentative/blob/main/LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbehringer24%2Fargumentative","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbehringer24%2Fargumentative","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbehringer24%2Fargumentative/lists"}