DOCSEARCHbyAlgolia
Submit Docs

Argbash Documentation

repository·master·Indexed 23 days ago

https://github.com/matejak/argbash

Argbash is a code generator for Bash scripts that automates the creation of robust argument parsing interfaces. It reads argument definitions written as comments in a template file and generates standalone, portable Bash or POSIX scripts, Bash completions, manpages, and docopt-compliant usage messages. The toolset includes the main argbash CLI, argbash-init for creating script templates, and argbash-1to2 for migrating templates from version 1 to version 2.

Tokens
9.9K
Snippets
20
Records
56
Agent score
81%

What's inside Argbash

  1. Compare Argbash with other argument parsing utilities

    master

    If you are deciding between Argbash and other tools, consider these comparisons:

    • vs. Python argparse: Argbash is native to bash (unlike argparse which requires Python) and handles boolean options more effectively. Argbash also provides wrapping functionality.
    • vs. shflags: shflags has platform limitations (doesn't work with Windows bash and lacks long option support on OSX), whereas Argbash works consistently across all platforms that have bash.
    • vs. getopts: While getopts is a bash builtin that supports short options, argbash>=2.7.0 can automatically generate code that uses getopts in POSIX mode, removing the need to write manual getopts logic.
    • vs. EasyOptions: Unlike EasyOptions, which requires distributing easyoptions.sh with your script, Argbash offers an option to produce "battery-included" scripts (self-contained). Argbash also provides more advanced features.
    • vs. bash-modules: bash-modules requires the library to be available at runtime, whereas Argbash can produce battery-included scripts. Argbash also provides superior documentation and examples.
    • vs. docopt: Argbash is compatible with the docopt approach. You can use the docopt style of defining interfaces via help messages while using Argbash.

  2. What is Argbash?

    master

    Argbash is a code generator that creates a tailor-made Bash parsing library for your specific script. Instead of being a runtime library that you import, it reads argument definitions (written as comments in your script) and generates the actual Bash parsing code.

    Key benefits include:

    • Portability: The generated code is standalone; you don't need Argbash installed to run the resulting script.
    • Embedded Definitions: Definitions stay inside your script, allowing you to regenerate the parsing logic easily by re-running Argbash on the same file.
    • Multi-platform: Generates scripts that work on any platform with Bash (Linux, OSX, etc.).
    • Versatile Outputs: Can generate Bash scripts, POSIX-compliant scripts (using getopts), Bash completion, docopt-compliant usage messages, and Manpages.

  3. Generate output without parsing code (Excise mode)

    master

    Using --type excised --strip all generates output that contains only your user code and the Argbash template, removing (excising) the generated parsing code. This is useful for:

    • Space saving: Making scripts smaller for easy copy-pasting.
    • Normalization: Storing only definitions in version control and generating the implementation on-the-fly with the latest Argbash version.

  4. Access Parsed Argument Values

    master

    Parsed arguments are stored in shell variables using a specific transliteration of the long argument name:

    1. Convert all letters to lowercase.
    2. Replace dashes (-) with underscores (_).
    3. Prepend _arg_.

    Examples:

    • --include-batteries $\rightarrow$ $_arg_include_batteries
    • --quiet (Boolean) $\rightarrow$ $_arg_quiet (value is on or off)
    • --include (Repeated) $\rightarrow$ stored in a bash array.
    • --count (Incremental) $\rightarrow$ integer value representing occurrences.

  5. Generate POSIX-compliant scripts

    master

    You can generate code that works with POSIX shells using --type posix-script. Because POSIX shells lack features like arrays, the following limitations apply:

    • Short Options Only: All options must have short options; these are the only user-visible interface elements.
    • Argument Ordering: Mixing optional and positional arguments is not supported. All arguments following the first positional argument are treated as positional.
    • Unsupported Arguments: Repeated arguments and multi-valued arguments are not supported.

    Internally, Argbash uses the getopts shell builtin for parsing.

  6. Choose an Argbash code generation strategy

    master

    Argbash is a code generator that produces shell scripts capable of parsing command-line arguments. You can choose from three main integration strategies depending on your preference for code cleanliness and complexity:

    1. Batteries-included (Single file): The parsing code and your script body are in one file. This is the simplest approach but the parsing logic will be embedded directly in your script.
    2. Managed (Two files): The parsing code is in a separate file, and the script body is in another. Both files contain Argbash directives, and Argbash manages the relationship between them. This is recommended for keeping code tidy.
    3. Decoupled (Two files, manual inclusion): The parsing code is in a separate file, and you manually include it in your script (e.g., using source). This is necessary if your script has non-matching square brackets that conflict with Argbash's processing.

  7. Wrap an existing script with new arguments

    master

    You can create a 'wrapper' script that inherits a subset of arguments from an existing script and adds its own. This is achieved by wrapping the parsing component of the target script rather than the script itself.

    To wrap a script that uses a parsing component named simple-parsing, use the ARGBASH_WRAP macro in your new template and specify the component name.

    Example pattern: In your wrapper template (simple-wrapper.m4), you can define new arguments and use ARGBASH_WRAP simple-parsing to inherit the underlying parsing logic. The wrapper script then decides which arguments are passed down to the wrapped component.

  8. Terminology for Argbash arguments

    master

    To write effective templates, understand the following terminology used by argbash:

    • Option (Flag/Switch): The identifier for an optional argument. Can be short (-l) or long (--sort).
    • Value: The string associated with an argument. For optional arguments, it is the string following the option. For positional arguments, it is the string at the expected position.
    • Name: The identifier used in help messages and to access the argument's value in your script. For long options, the name is the part after the double dash (e.g., project-path for --project-path).
    • Argument: The high-level concept encompassing the option and its potential value.
    • Default: A value assigned to positional or boolean arguments if they are not provided by the user.

    Important Note on Detection: You cannot distinguish between an argument that was not passed and an argument passed with an empty string value just by checking the environment variable, as bash treats them similarly.

  9. Re-template a generated script

    master
    Once a script is generated from a .m4 template into a .sh file, the .sh file itself can serve as a template. You can modify the header (the Argbash definitions) directly in the .sh file and re-run argbash on it to update the script. This means you do not strictly need to keep the original .m4 file to perform updates.

  10. Separate parsing code from script logic

    master

    You can decouple your argument parsing logic from your main script body by using the INCLUDE_PARSING_CODE macro. This is useful for reusing parsing logic or maintaining cleaner files.

    1. Create a parsing template (e.g., simple-parsing.m4) containing only the argument definitions.
    2. Create a script template (e.g., simple.m4) that uses the INCLUDE_PARSING_CODE macro.
    3. Run argbash on the script template. It will automatically detect the macro, find the parsing template (looking for simple-parsing.m4 or simple-parsing.sh in the same directory), and interconnect them.

    Example command:

    argbash simple.m4 -o simple.sh
    argbash simple.m4 -o simple.sh

  11. Understand Argbash components

    master

    The Argbash package consists of three main script types:

    • argbash: The main wrapper. It uses the autom4te utility and the source code located in the src directory. During installation, the script is placed in $PREFIX/bin and the source is placed in $PREFIX/lib/argbash.
    • argbash-xtoy: Migration scripts (e.g., argbash-1to2) that help users update their scripts when the Argbash API changes between major versions.
    • argbash-init: A quickstart script used to create a basic template for new scripts.

  12. Understand argument types in Argbash templates

    master

    When writing templates for argbash, you must define the types of arguments your script supports using specific macros. The supported argument types are:

    • Single-value positional arguments: Arguments identified by their position on the command line (can have optional defaults).
    • Single-value optional arguments: Options that require exactly one value (e.g., --sort time).
    • Boolean optional arguments: Flags that are either on or off (e.g., -l).
    • Action optional arguments: Arguments that trigger an action, like --version or --help.
    • Incremental arguments: Arguments that track how many times they are repeated (e.g., --verbose used multiple times).
    • Repeatable arguments: Arguments that store multiple values into an array (e.g., -I value1 -I value2).

    Argbash exposes the values of these arguments as environment variables within your script.