6.14. Directive reference

Every docstring directive that affects the generated interface, grouped by where it may be written. A directive written in the wrong place is not an error; it is kept as prose and the build warns, so check this table when one appears to do nothing.

Table 6. On the module docstring — the --' lines directly above module
Directive Effect

@epilogue

Open a block. Every following docstring line, until the docstring ends, is printed verbatim below the options from -hh up. Use it for an "Examples:" section.
Table 7. On a term’s signature preamble — the --' lines directly above name ::
Directive Effect

@name <name>

Name the subcommand something other than the Morloc term.

@with <flags>=<term>

Attach an output action whose result stays typed. See Output actions.

@render <flags>=<term>

Attach an output action whose result is written as final bytes.

@return <text>

Describe the return value. The same as a docstring on the signature’s last type.

@epilogue

Open a block printed verbatim at the foot of this subcommand’s help, after its argument and return blocks. Use it for the command’s own "Examples:" section. The top-level help shows only the module’s block.
Table 8. On an argument — the --' lines directly above a type inside a signature
Directive Effect

@arg <flags>

Make this argument an option rather than a positional. Requires @default. Not allowed on Bool.

@default <json>

The value used when an option is omitted, written as JSON.

@true <flags>

On a Bool: the flag that sets it true. The default becomes false.

@false <flags>

On a Bool: the flag that sets it false. The default becomes true. See the warning in Arguments.

@metavar <NAME>

Name the argument. Becomes the placeholder in help for an option, and the property name in the machine-readable views.

@many

Accept several argv tokens and assemble them into a list. The argument type must be a list; as a positional it must be the last one.

@stdin

Make a Str positional optional and read standard input when it is omitted. See Reading a stream from standard input.

@source inline / file

Where the bytes come from. See Input shape.

@form list / bytes / bytes-only / packet

How the bytes are read.

@check.path r / w / x / rw

Require the argument to be a path satisfying the mode.

@list.source, @list.form, @list.check.<kind>

The same three, applied to each element of a @form list argument.

@unroll

On a record argument: split it into one flag per field. @unroll false opts one use out.
Table 9. On a type, record, or record field definition
Directive Effect

@metavar <NAME>

On a type or a record in either form: the metavar inherited by every argument of that type.

@mime <type/subtype>

Attach a media type to a type. See Output actions.

@arg, @default, @true, @false

On a record field: the same meaning as on an argument, applied when the record is unrolled.

@arg <flags>

On a record definition: declare the group flag that accepts the whole record at once.
Table 10. Modifiers and value references, written inside another directive
Token Meaning

@default

On a @with / @render directive: this action fires when no action flag and no -f is given. At most one per command.

@stream

On a @with / @render directive of a @collect command: apply the handler to each batch instead of the gathered stream.

@offset

As a handler argument under @stream: the number of elements already written.

@value

As a handler argument: the value being formatted. Appended last if not written explicitly.

$1, $2, …​

As a handler argument: the command’s own Nth argument.

One more directive is a deprecated spelling rather than a feature: literal: true means @source inline. It still works, and the build warns when you use it.