Skip to content

Latest commit

 

History

History
325 lines (244 loc) · 8.4 KB

specification.md

File metadata and controls

325 lines (244 loc) · 8.4 KB
Raw

Specification

Comment Tags

@describe

Sets the description for the command.

Syntax
@describe description

# @describe A demo CLI

@cmd

Defines a subcommand.

Syntax
@cmd description?

# @cmd Upload a file
upload() {
  echo Run upload
}

# @cmd Download a file
download() {
  echo Run download
}
USAGE: prog <COMMAND>

COMMANDS:
  upload    Upload a file
  download  Download a file

@alias

Sets aliases for the subcommand.

Syntax
name (, name)*

# @cmd Run tests
# @alias t,tst
test() {
  echo Run test
}
USAGE: prog <COMMAND>

COMMANDS:
  test  Run tests [aliases: t, tst]

@arg

Defines a positional argument.

Syntax
@arg name modifier? param-value? bind-env? notation? description?

# @arg va
# @arg vb!                        required
# @arg vc*                        multi-values
# @arg vd+                        multi-values + required
# @arg vna <PATH>                 value notation
# @arg vda=a                      default
# @arg vdb=`_default_fn`          default from fn
# @arg vca[a|b]                   choices
# @arg vcb[=a|b]                  choices + default
# @arg vcc*[a|b]                  multi-values + choice
# @arg vcd+[a|b]                  required + multi-values + choice
# @arg vfa[`_choice_fn`]          choice from fn
# @arg vfb[?`_choice_fn`]         choice from fn + no validation
# @arg vfc*[`_choice_fn`]         multi-values + choice from fn
# @arg vfd*,[`_choice_fn`]        multi-values + choice from fn + comma-separated list
# @arg vxa~                       capture all remaining args
# @arg vea $$                     bind-env
# @arg veb $BE <PATH>             bind-named-env

@option

Defines an option argument.

Syntax
@option short? long modifier? param-value? bind-env? notations? description?

# @option    --oa                   
# @option -b --ob                   short
# @option -c                        short only
# @option    --oc!                  required
# @option    --od*                  multi-occurs
# @option    --oe+                  required + multi-occurs
# @option    --of*,                 multi-occurs + comma-separated list
# @option    --ona <PATH>           value notation
# @option    --onb <FILE> <FILE>    two-args value notations
# @option    --onc <CMD> <FILE+>    unlimited-args value notations
# @option    --oda=a                default
# @option    --odb=`_default_fn`    default from fn
# @option    --oca[a|b]             choice
# @option    --ocb[=a|b]            choice + default
# @option    --occ*[a|b]            multi-occurs + choice
# @option    --ocd+[a|b]            required + multi-occurs + choice
# @option    --ofa[`_choice_fn`]    choice from fn
# @option    --ofb[?`_choice_fn`]   choice from fn + no validation
# @option    --ofc*[`_choice_fn`]   multi-occurs + choice from fn
# @option    --ofd*,[`_choice_fn`]  multi-occurs + choice from fn + comma-separated list
# @option    --oxa~                 capture all remaining args
# @option    --oea $$               bind-env
# @option    --oeb $BE <PATH>       bind-named-env

@flag

Defines a flag argument. Flag is a special option that does not accept any value.

Syntax
@flag short? long*? bind-env? description?

# @flag     --fa 
# @flag  -b --fb         short
# @flag  -c              short only
# @flag     --fd*        multi-occurs
# @flag     --ea $$      bind-env
# @flag     --eb $BE     bind-named-env

@env

Defines an environment variable.

Syntax
@arg NAME!?param-value? notation? description?

# @env EA                 optional
# @env EB!                required
# @env EC=true            default
# @env EDA[dev|prod]      choices
# @env EDB[=dev|prod]     choices + default

@meta

Adds metadata.

Syntax
@meta name value?

syntax scope description
@meta version <value> any Set the version for the command.
@meta author <value> any Set the author for the command.
@meta dotenv [<path>] root Load a dotenv file from a custom path, if persent.
@meta default-subcommand subcmd Set the current subcommand as the default.
@meta require-tools <tool>,... any Require certain tools to be available on the system.
@meta man-section <1-8> root Override the section for the man page, defaulting to 1.
@meta inherit-flag-options root Subcommands will inherit the flags/options from their parent.
@meta combine-shorts root Short flags/options can be combined, e.g. prog -xf => prog -x -f .
@meta symbol <param> any Define a symbolic parameter, e.g. +toolchain, @argument-file. 
# @meta version 1.0.0
# @meta author nobody <nobody@example.com>
# @meta dotenv
# @meta dotenv .env.local
# @meta require-tools git,yq
# @meta man-section 8
# @meta symbol +toolchain[`_choice_fn`]

Syntax parts

short

A single character abbreviation for a flag/option.

Syntax
   -short-char
| +short-char

long

A descriptive name for a flag/option.

Syntax
  -- long-name
| -long-name
| +long-name

modifier

Symbols used to modify param behavior:

Syntax
  !
| * separated-char?
| + separated-char?

  • !: The option is required and must be provided.
  • *: multi-occurs for @option; multi-values for @arg;
  • +: The option is required and can be used multiple times.

param-value

Ways to specify values for params:

Syntax
  =value
| =`fn-name`
| [choices]
| [=choices]
| [`fn-name`]
| [?`fn-name`]

choices

Define a set of acceptable values for an param

Syntax
value (| value)*

notations

Placeholders in help messages and usage instructions:

Syntax
(notation )* notation-last

notation

Syntax
< value >

  • FILE/PATH: complete files
  • DIR: complete directories

notation-last

Syntax
< value notation-modifier? >

notation-modifier

Symbols used within the last notation to specify value requirements

Syntax
  *
| +
| ?

  • *: Zero or more values are allowed.
  • +: One or more values are allowed.
  • ?: Zero or one value is allowed.

short-char

A-Z a-z 0-9 ! # $ % * + , . / : = ? @ [ ] ^ _ { } ~

separated-char

, : @ | /

bind-env

Link environment variables to params:

  • $$: Automatically use the param's name for the environment variable.
  • $NAME: Use a specific environment variable name.

description

Plain text for documentation and usage information

# @describe Can be multiline 
#
# Extra lines after the comment tag accepts description, which don't start with an `@`,
# are treated as the long description. A line which is not a comment ends the block.