{"id":19715675,"url":"https://github.com/mickaelblet/bash_args","last_synced_at":"2026-05-14T12:33:03.096Z","repository":{"id":254636631,"uuid":"777968940","full_name":"MickaelBlet/bash_args","owner":"MickaelBlet","description":"Parse and store arguments/options from argv natively on bash","archived":false,"fork":false,"pushed_at":"2026-01-22T22:17:49.000Z","size":291,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-23T12:35:10.314Z","etag":null,"topics":["argparse","argv","bash","bash-library","bash-only"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/MickaelBlet.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-26T20:48:11.000Z","updated_at":"2026-01-22T22:17:53.000Z","dependencies_parsed_at":"2024-08-27T06:28:59.525Z","dependency_job_id":"a1cad87a-117d-459a-ae2f-19e52cfda1c7","html_url":"https://github.com/MickaelBlet/bash_args","commit_stats":null,"previous_names":["mickaelblet/bash_args"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/MickaelBlet/bash_args","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MickaelBlet%2Fbash_args","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MickaelBlet%2Fbash_args/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MickaelBlet%2Fbash_args/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MickaelBlet%2Fbash_args/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MickaelBlet","download_url":"https://codeload.github.com/MickaelBlet/bash_args/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MickaelBlet%2Fbash_args/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33024998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"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","argv","bash","bash-library","bash-only"],"created_at":"2024-11-11T22:39:07.527Z","updated_at":"2026-05-14T12:33:03.090Z","avatar_url":"https://github.com/MickaelBlet.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Args\n\nA powerful and flexible argument parser for **Bash** scripts, inspired by Python's [argparse](https://python.readthedocs.io/en/latest/library/argparse.html).  \nParse command-line arguments and options natively in Bash with automatic help generation, type validation, and more.\n\n**Compatible with Bash version \u003e= 4.2.0**\n\n## Features\n\n- **Positional Arguments** - Define required or optional positional parameters\n- **Optional Arguments** - Support for short (`-f`) and long (`--flag`) options\n- **Option Abbreviation** - Use shortened versions of long options (e.g., `--verb` for `--verbose`)\n- **Multiple Actions** - Store values, booleans, counts, or append to lists\n- **Validation** - Enforce choices, required arguments, and value constraints\n- **Flexible Parsing** - Support for `nargs`, default values, and custom metavar\n- **Auto-Generated Help** - Automatic `-h`/`--help` with formatted usage messages\n- **Destination Variables** - Store parsed values directly to custom variables\n- **Alternative Mode** - Accept single dash for long options (`-option` instead of `--option`)\n- **Strict Mode Compatible** - Fully compatible with `set -euo pipefail` for robust error handling\n\nFor detailed documentation, see [Documentation](#documentation).\n\n## Installation\n\nSimply source the `args.sh` script in your Bash script:\n\n```bash\nsource \"args.sh\"\n```\n\nOr use an absolute/relative path:\n\n```bash\nsource \"/path/to/args.sh\"\n```\n\n## Quickstart\n\nThis example demonstrates the main features of the argument parser:\n\n```bash\n#!/usr/bin/env bash\n\nset -euo pipefail\n\n# Source the args.sh library\nsource \"args.sh\"\n\n# Set description and epilog for help message\nargs_set_description \"example\" \"of\" \"description\"\nargs_set_epilog \"example of epilog\"\n\n# Add a required positional argument\nargs_add_argument \\\n    --help \"take the first argument\" \\\n    --dest \"ARG1_VALUE\" \\\n    --required \\\n    -- \"ARG1\"\n\n# Add a boolean flag (--print-hello or -p)\nargs_add_argument \\\n    --flag=\"-p\" --flag=\"--print-hello\" \\\n    --help=\"print hello\" \\\n    --action=\"store_true\" \\\n    --dest=\"DO_HELLO\"\n\n# Add an optional argument with a default value\nargs_add_argument \\\n    --help=\"help of option\" \\\n    --metavar=\"VALUE\" \\\n    --default=\"24\" \\\n    -- \"--option\"\n\n# Parse the command-line arguments\nargs_parse_arguments \"$@\"\n\n# Access parsed values using destination variables or the ARGS map\necho \"'ARG1' argument from dest ${ARG1_VALUE:-}\"\necho \"'ARG1' argument from map  ${ARGS[ARG1]}\"\necho \"'--option' option from map ${ARGS[option]}\"\nif ${DO_HELLO:-false}; then\n    echo \"Hello world\"\nfi\n```\n\n**Example usage:**\n\n```\n$ ./example/quickstart.sh\nusage: quickstart.sh [-h] [-p] [--option VALUE] -- ARG1\nquickstart.sh: argument 'ARG1' is required\n$ ./example/quickstart.sh -h\nusage: quickstart.sh [-h] [-p] [--option VALUE] -- ARG1\n\nexample of description\n\npositional arguments:\n  ARG1                  take the first argument\n\noptional arguments:\n  -h, --help            print this help message\n  -p, --print-hello     print hello\n  --option VALUE        help of option\n\nexample of epilog\n$ ./example/quickstart.sh 42\n'ARG1' argument from dest 42\n'ARG1' argument from map  42\n'--option' option from map 24\n$ ./example/quickstart.sh 42 -p\n'ARG1' argument from dest 42\n'ARG1' argument from map  42\n'--option' option from map 24\nHello world\n$ ./example/quickstart.sh 42 -p --option 42\n'ARG1' argument from dest 42\n'ARG1' argument from map  42\n'--option' option from map 42\nHello world\n```\n\n## Option Abbreviation\n\nArgs.sh supports automatic abbreviation of long option names, allowing users to type shortened versions as long as they are unambiguous.\n\n### How It Works\n\nWhen parsing a long option (starting with `--`), if an exact match isn't found, args.sh will attempt to match it as an abbreviation. The abbreviation must uniquely identify one option - if multiple options start with the same prefix, an error is reported.\n\n### Examples\n\n```bash\n# Given options: --verbose, --version, --output, --optimize\n\n# Valid abbreviations:\n./script.sh --verb      # matches --verbose\n./script.sh --vers      # matches --version\n./script.sh --out       # matches --output\n./script.sh --opt       # matches --optimize\n\n# Ambiguous abbreviations (will fail with helpful error):\n./script.sh --ver       # Could match: --verbose OR --version\n./script.sh --o         # Could match: --output OR --optimize\n\n# Works with all syntax forms:\n./script.sh --verb              # boolean flag\n./script.sh --out file.txt      # separate value\n./script.sh --out=file.txt      # assignment syntax\n./script.sh --opt 3             # numeric value\n```\n\n### Abbreviation with Alternative Mode\n\nAbbreviations work seamlessly with alternative mode (single dash for long options):\n\n```bash\nargs_set_alternative true\n\n# These all work:\n./script.sh -verbose      # full option name\n./script.sh -verb         # abbreviated\n./script.sh -out=file.txt # abbreviated with assignment\n```\n\n### Error Handling\n\n- **Ambiguous abbreviation**: Lists all matching options\n  ```\n  script.sh: ambiguous option: '--ver' could match: --verbose --version\n  ```\n- **Non-existent abbreviation**: Reports invalid option\n  ```\n  script.sh: invalid option -- '--notfound'\n  ```\n\n### Notes\n\n- Abbreviations only work for **long options** (`--option`), not short options (`-o`)\n- Full option names always work alongside abbreviations\n- Exact matches take precedence over abbreviations\n- Single-character abbreviations work if unambiguous\n\n## Strict Mode Compatibility\n\nArgs.sh is fully compatible with Bash strict mode (`set -euo pipefail`), ensuring robust error handling in production scripts.\n\n```bash\n#!/usr/bin/env bash\n\nset -euo pipefail  # Enable strict mode\n\nsource \"args.sh\"\n\nargs_add_argument --flag=\"--output\" --action=\"store\" --required\nargs_add_argument --flag=\"--verbose\" --action=\"store_true\"\n\n# Errors are handled gracefully with proper usage messages\nargs_parse_arguments \"$@\"\n\n# Access parsed values safely\necho \"Output: ${ARGS[output]}\"\necho \"Verbose: ${ARGS[verbose]:-false}\"\n```\n\n### Error Handling\n\nAll error cases display proper usage information before exiting:\n\n- **Invalid options**: Shows usage line and error message\n- **Missing required options**: Shows usage line and which option is required\n- **Ambiguous abbreviations**: Shows usage line and lists matching options\n- **Invalid choice values**: Shows usage line and valid choices\n\nThis ensures users always get helpful feedback, even with `set -e` enabled.\n\n## Documentation\n\n### Functions\n\n|Function|Description|\n|--:|---|\n|[args_add_argument](docs/functions.md#args_add_argument)|Add a argument.|\n|[args_parse_arguments](docs/functions.md#args_parse_arguments)|Convert argument strings to objects and assign them as attributes on the ARGS map.|\n|[args_clean](docs/functions.md#args_clean)|Clean all map and array for recalled.|\n|[args_count](docs/functions.md#args_count)|Count the number of occurence of argument after parsed.|\n|[args_debug_values](docs/functions.md#args_debug_values)|Show all values of arguments and options.|\n|[args_isexists](docs/functions.md#args_isexists)|Check if argument is exists after parsed.|\n|[args_set_alternative](docs/functions.md#args_set_alternative)|Set if args_parse_arguments can accept a single '-' for a long option.|\n|[args_set_description](docs/functions.md#args_set_description)|Set a usage description.|\n|[args_set_epilog](docs/functions.md#args_set_epilog)|Set a epilog description.|\n|[args_set_program_name](docs/functions.md#args_set_program_name)|Set the program name for usage message.|\n|[args_set_usage_widths](docs/functions.md#args_set_usage_widths)|Set the widths of usage message.|\n|[args_set_usage](docs/functions.md#args_set_usage)|Set a full usage message.|\n|[args_usage](docs/functions.md#args_usage)|Show/Generate usage message.|\n\n### Global Variables\n\nAfter calling `args_parse_arguments`, parsed values are accessible through these global variables:\n\n|Name|Type|Description|\n|--:|:--:|---|\n|`ARGS`|Associative Array|Stores all parsed argument values. Access using `${ARGS[argument_name]}`|\n|`__ARGS`|Associative Array|Internal storage used by args.sh. Do not modify directly.|\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmickaelblet%2Fbash_args","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmickaelblet%2Fbash_args","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmickaelblet%2Fbash_args/lists"}