Reference · command

metais init

Write a new package's source directory: a greeting to learn from, or with --minimal one input and one template to replace.

Authoring

Usage

metais init [<dir>] [--name <name>] [--minimal] [--html] [--dry-run] [--json]

Examples

metais init acme-report --minimal
Writes a package called acme-report into the directory acme-report: the layout, one input and one template, to replace with your own.
metais init acme-report
Writes the greeting scaffold instead, with an example, to learn from and edit.
metais init acme-report --minimal --html
Writes the minimal package with an HTML output that escapes for HTML and writes its data into a <script> with json_script.
metais init --name acme-report --minimal
Writes it into the current directory, which must be empty.
metais init acme-report --dry-run --json
Lists the files it would write, as one metais.init/1 document.

Detail

Without --minimal, writes eight files into <dir>: metais.yaml, one input with its schema and meaning document, one template, one example with its inputs and expected output, and a .gitattributes that keeps git from converting line endings. The scaffold is a small package, a greeting, to learn from and edit.

With --minimal, writes five: .gitattributes, metais.yaml, one input, data, with its schema and meaning document, and one template, each a placeholder to replace. It has no example, so test has nothing to compare until you add one.

With --html, the output is an HTML page in place of Markdown: the output declares escape: html, so every value the template writes with {{ }} is HTML-escaped, and the template writes its data into a <script> element with json_script. Either scaffold checks, renders with render --sample and packs as written.

The package's name is --name, or else the last element of <dir> as written. When <dir> is omitted or ends in . or .., --name is required: metais never looks up the working directory's name. The name must satisfy the package name rule.

<dir> is created, with its missing parents, when it does not exist. An existing <dir> must be empty, apart from names beginning with . (such as .git) other than .compiled and .gitattributes, and files ending .metais; init never overwrites, and refuses anything else, listing up to ten of the entries it found. A failed write stops init, which lists the files it wrote and removes none of them.

Operands

<dir>
The directory to write into, created when absent; the current directory when omitted.

Flags

--name <name>
The package's name. It is required when <dir> is omitted or its last element is . or ..; otherwise it defaults to that element.
--minimal
Write the layout, one input and one template to replace, without the greeting and its example.
--html
Make the output an HTML page that declares escape: html, and whose template writes its data into a <script> with json_script.
--dry-run
Report the files init would write, and write nothing.
--fail-on <severity>
With warning, a warning fails the command with exit status 1 as an error does; no finding's severity changes. Values: error, warning. Default: error.
--json
Print the result as one JSON document on standard output.
--color <when>
Colour human output: auto colours a stream that is a terminal when NO_COLOR is unset or empty; always and never override NO_COLOR. Values: auto, always, never. Default: auto.
-h, --help
Print help to standard output and exit 0; nothing else runs.

Prints

The files written, relative to <dir>, in the order written, then what to edit.

--json: metais.init/1

Refusals

output.destination.not_directory
<dir>, or a directory above it, exists and is not a directory. Next: metais init <dir>: Writes the scaffold into a directory that is empty or does not exist yet.
output.destination.not_empty
<dir> holds an entry other than the quiet ones. Next: metais init <dir>: Writes the scaffold into a directory that is empty or does not exist yet.
output.destination.nothing_written
A write failed before init had created anything; nothing was written. Next: metais init <dir>: Writes the scaffold again, into an empty directory, once the cause is fixed.
output.destination.write_failed
A write failed after init had created something; the files already written are listed and left in place. Next: metais init <dir>: Writes the scaffold again, into an empty directory, once the cause is fixed.
usage.bad_value
A flag's value is missing, or is not one the flag accepts, or a flag that takes no value is given one. Next: metais init --help: Prints the operands and flags metais init takes.
usage.name_invalid
The name, from --name or from <dir>, does not satisfy the package name rule. Next: metais init <dir> --name <name>: Gives a name of lower-case letters, digits, single hyphens and dots, which the package name rule accepts.
usage.name_required
<dir> is omitted or ends in . or .., and --name is not given. Next: metais init --name <name>: Gives the package's name, which init takes only from the command line, never from the working directory.
usage.repeated_flag
A flag that may be given once is given again. Next: metais init --help: Prints the operands and flags metais init takes.
usage.unexpected_operand
An operand the command does not take. Next: metais init --help: Prints the operands and flags metais init takes.
usage.unknown_flag
An argument that is not a flag the command accepts, an abbreviated flag, or one-letter aliases written together. Next: metais init --help: Prints the operands and flags metais init takes.