|| |
  

orfile

Or get it from a file!

Orfile is a standard for loading CLI parameters from different sources.

where and using

Orfile allows the developer to program where and using subcommand variants are tied into the same logic, but accept different parameters.

Note

A helpful pattern is to check command requirements with where and then develop with using.

• where: Explicitly requires parameters to be passed in as args. This is best for when you're learning to use a given command, or want to see what is necessary to run a command.
• using: Allows parameters to be passed in a hierarchy from environment variables, to config files, to command line args in order of override. This is useful for production settings. The subcommand will still validate the config.

Tip

To see how to implement such a CLI tool using the orfile::Orfile macro, see tool::cli::add.

Example The below is and example command supported from this directory by building the tool binary.

tool add where --left 1 --right 2 
ADD_LEFT=1 tool add using --args-path ./examples/config.json -- --right 4

select

The orfile repo also houses the select API which used for chosing one of many subcommand as Selections.

Warning

The task of prefixing flattend args in clap has long been unresolved, owing to abstractions on the parser and their availability in different contexts.

select works around these limitations at the expense of direct --help support--essentially extending the parsing into extra_args with prefix handling.

See, for more information about complications associated with clap prefixing:

• clap-rs/clap#3117
• clap-rs/clap#5374

Tip

To see how to implement such a CLI tool using the select::Select macro, see select_tool::cli.

Example

Select everything:

select-tool --add --multiply --divide -- --add.left 2 --add.right 2 --multiply.left 2 --multiply.right 3 --divide.left 3 --divide.right 2
Add { left: 2, right: 2 }
4
Multiply { left: 2, right: 3 }
6
Divide { left: 3, right: 2 }
1

Select one:

select-tool --add -- --add.left 2 --add.right 2
Add { left: 2, right: 2 }
4

Select multiple but fail to fulfill one:

select-tool --add --multiply --divide -- --add.left 2 --add.right 2 --multiply.left 2 --multiply.right 3 --divide.left 3
Error: Failed to parse subcommand: error: the following required arguments were not provided:
  --right <RIGHT>

Usage: divide --left <LEFT> --right <RIGHT>

For more information, try '--help'.

Get some help with selections:

select-tool --help                                                   
A wrapper struct that adds selection flags to the original struct

Usage: select-tool [OPTIONS] [-- <EXTRA_ARGS>...]

Arguments:
  [EXTRA_ARGS]...  Extra arguments to be passed to selections

Options:
      --add           Enable the add selection
      --multiply      Enable the multiply selection
      --divide        Enable the divide selection
      --kebab-divide  Enable the kebab-divide selection
  -h, --help          Print help

Selection (1/4): add
The arguments for the add command

Usage: --add.* --left <LEFT> --right <RIGHT>

Options:
      --left <LEFT>    The left number
      --right <RIGHT>  The right number
  -h, --help           Print help (see more with '--help')

Selection (2/4): multiply
The arguments for the multiply command

Usage: --multiply.* --left <LEFT> --right <RIGHT>

Options:
      --left <LEFT>    The left number
      --right <RIGHT>  The right number
  -h, --help           Print help (see more with '--help')

Selection (3/4): divide
The arguments for the divide command

Usage: --divide.* --left <LEFT> --right <RIGHT>

Options:
      --left <LEFT>    The left number
      --right <RIGHT>  The right number
  -h, --help           Print help (see more with '--help')

Selection (4/4): kebab-divide
The arguments for the kebabdivide command

Usage: --kebab-divide.* --left <LEFT> --right <RIGHT>

Options:
      --left <LEFT>    The left number
      --right <RIGHT>  The right number
  -h, --help           Print help (see more with '--help')

With extended prefixes:

select-tool --kebab-divide -- --kebab-divide.left 2 --kebab-divide.right 2
KebabDivide { left: 2, right: 2 }
1

Contributing and getting started

Task	Description
Upcoming Events	High-priority event issues with planned completion dates.
Release Candidates	Feature-complete versions linked to events.
Features & Bugs	High-priority feature and bug issues.

Please see the CONTRIBUTING.md file for additional contribution guidelines.

Organization

There are five subdirectories which progressively build on one another for node logic.

1. orfile: contains all core orfile logic.