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.