metais extract
Write the entries the globs select to a directory.
Reading a package
Usage
metais extract <package> <glob>... --out <dir> [--overwrite] [--dry-run] [--limit <name>=<value>]... [--json]
Examples
metais extract report-1.0.0.metais 'references/**' --out refs- Writes the package's references into the new directory refs.
metais extract report-1.0.0.metais references --out refs --dry-run- Lists the references it would write.
metais extract report-1.0.0.metais 'templates/**' --out . --overwrite- Writes the templates into the current directory, replacing the files already there.
metais extract report-1.0.0.metais 'examples/basic/**' --out basic- Writes the example basic into the new directory basic, to see how the package is tested; its inputs are never a real document's data.
Detail
Writes every entry any glob selects to <dir>/<entry path>, as stored (metais help globs). Every glob must select at least one entry, or nothing is written: a glob that selects nothing is a typo to hear about.
A <dir> that does not exist is created, with its missing parents, and every file is created beneath it, never through a link. A failed write stops extract, which lists the files it wrote and removes none of them.
An existing <dir> with no entry at all is written into. One that holds any entry, a hidden one included, is refused unless --overwrite is given, and then a file at a path extract writes is replaced, and nothing is deleted: every other entry is left as it is. Into an existing <dir>, every file is checked before anything is written, and every refusal is reported together: a link at or above a file's path, which is never followed, a name that differs only in case from one extract writes, and a directory or anything else that is not a regular file where a file goes. An existing file is never read: it is replaced by moving the new file onto its name. The files are prepared beneath a staging directory, .metais-staging, inside <dir>, and moved into place; a failure before then leaves <dir> as it was, and one while moving them lists the files already moved.
--dry-run lists the files extract would write, makes every check, and writes nothing.
The entries under examples/ are the package's examples. An example is the author's illustration of the inputs, and of the outputs a render of them should produce, kept in the package to test it: not your data, and not a preview of what the package produces, which is a render from generated data with metais render --sample. An example's inputs are the author's illustration, never a real document's data: render a real document only from the facts the person supplies, and without them ask the person for them, never taking them from an example.
Operands
<package>- A packed package file, or a source directory; - is refused, since a package is read with random access. Required.
<glob>- A glob selecting entries to write. Required. May be given more than once.
Flags
--out <dir>- The directory to write into: a new one, or an existing one that is empty, or holds entries with --overwrite; required.
--overwrite- Write into a <dir> that holds entries, replacing a file at a path extract writes; nothing is deleted.
--dry-run- List the files extract would write, and write nothing.
--limit <name>=<value>- Lower one resource limit for this run, to a whole number no higher than its default (a size may end in KiB, MiB or GiB). metais limits lists them. May be given more than once.
--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, or that would be, each with its size, relative to <dir>.
--json: metais.extract/1
Refusals
limit.invalid- A --limit names no limit, gives a malformed value, or tries to raise one. Next:
metais limits: Lists every limit with its default; a limit can be lowered and never raised. limit.package- The package breaches one of its limits. Next:
metais limits: Lists every limit with its default; a limit can be lowered and never raised. manifest.additional_property- The manifest breaks one of its rules (additional property). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.const- The manifest breaks one of its rules (const). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.contains- The manifest breaks one of its rules (contains). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.dependent_required- The manifest breaks one of its rules (dependent required). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.enum- The manifest breaks one of its rules (enum). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.file.wrong_name- The manifest breaks one of its rules (file: wrong name). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.forbidden- The manifest breaks one of its rules (forbidden). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.input.duplicate_name- The manifest breaks one of its rules (input: duplicate name). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.json.duplicate_name- The manifest breaks one of its rules (json: duplicate name). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.json.encoding- The manifest breaks one of its rules (json: encoding). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.json.lone_surrogate- The manifest breaks one of its rules (json: lone surrogate). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.json.noncharacter- The manifest breaks one of its rules (json: noncharacter). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.json.syntax- The manifest breaks one of its rules (json: syntax). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.json.trailing_content- The manifest breaks one of its rules (json: trailing content). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.license.expression- The manifest breaks one of its rules (license: expression). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.max_items- The manifest breaks one of its rules (max items). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.max_length- The manifest breaks one of its rules (max length). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.min_items- The manifest breaks one of its rules (min items). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.min_length- The manifest breaks one of its rules (min length). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.not- The manifest breaks one of its rules (not). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.number_out_of_range- The manifest breaks one of its rules (number out of range). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.one_of- The manifest breaks one of its rules (one of). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.output.duplicate_id- The manifest breaks one of its rules (output: duplicate id). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.output.nested_for_each- The manifest breaks one of its rules (output: nested for each). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.path_not_found- The manifest breaks one of its rules (path not found). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.pattern- The manifest breaks one of its rules (pattern). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.required- The manifest breaks one of its rules (required). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.type- The manifest breaks one of its rules (type). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.unique_items- The manifest breaks one of its rules (unique items). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.alias- The manifest breaks one of its rules (yaml: alias). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.anchor- The manifest breaks one of its rules (yaml: anchor). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.bom- The manifest breaks one of its rules (yaml: bom). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.character- The manifest breaks one of its rules (yaml: character). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.directive- The manifest breaks one of its rules (yaml: directive). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.duplicate_key- The manifest breaks one of its rules (yaml: duplicate key). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.encoding- The manifest breaks one of its rules (yaml: encoding). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.key_empty- The manifest breaks one of its rules (yaml: key empty). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.key_not_scalar- The manifest breaks one of its rules (yaml: key not scalar). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.merge_key- The manifest breaks one of its rules (yaml: merge key). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.multi_document- The manifest breaks one of its rules (yaml: multi document). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.root_not_mapping- The manifest breaks one of its rules (yaml: root not mapping). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.scalar_refused- The manifest breaks one of its rules (yaml: scalar refused). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.syntax- The manifest breaks one of its rules (yaml: syntax). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. manifest.yaml.tag- The manifest breaks one of its rules (yaml: tag). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. output.destination.case_variant- In <dir>, an entry's name differs only in case or normalization from a name an entry's path holds. Next:
metais extract <package> <glob> --out <dir>: Extracts again once what stands in the way in <dir> is moved or removed, or into a directory that does not exist yet. output.destination.commit_failed- Moving the files into an existing <dir> failed part way; the files already moved are listed, and nothing else was changed. Next:
metais extract <package> <glob> --out <dir>: Writes into a directory that does not exist yet, or an empty one. output.destination.link- In <dir>, an entry's path runs through, or ends at, a symbolic link, a junction or another reparse point, which is never followed. Next:
metais extract <package> <glob> --out <dir>: Extracts again once what stands in the way in <dir> is moved or removed, or into a directory that does not exist yet. output.destination.not_directory- <dir>, or a directory above it, exists and is not a directory; or, in <dir>, a file stands where an entry's path needs a directory. Next:
metais extract <package> <glob> --out <dir>: Extracts again once what stands in the way in <dir> is moved or removed, or into a directory that does not exist yet. output.destination.not_empty- <dir> holds entries, and --overwrite is not given. Next:
metais extract <package> <glob> --out <dir> --overwrite: Writes into the directory, replacing a file at a path extract writes and deleting nothing. output.destination.not_regular_file- In <dir>, a directory, a named pipe, a socket or a device stands at an entry's path. Next:
metais extract <package> <glob> --out <dir>: Extracts again once what stands in the way in <dir> is moved or removed, or into a directory that does not exist yet. output.destination.nothing_written- A write failed and nothing was left: <dir> could not be created, or, in an existing one, a write failed before the commit, another file system is mounted inside it, or an entry lies beneath the staging name. Next:
metais extract <package> <glob> --out <dir>: Writes into a directory that does not exist yet, or an empty one. output.destination.staging_exists- An existing <dir> holds .metais-staging, left by a killed write or in use by another; nothing is written. Next:
metais extract <package> <glob> --out <dir>: Writes into a directory that does not exist yet, or an empty one. output.destination.write_failed- A write into a new <dir> failed after creating it; the files already written are listed and left in place. Next:
metais extract <package> <glob> --out <dir>: Writes into a directory that does not exist yet, or an empty one. package.compiled.mismatch- The package is refused (compiled: mismatch). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.compiled.missing- The package is refused (compiled: missing). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.compiled.unknown_file- The package is refused (compiled: unknown file). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.archive_comment- The package is refused (container: archive comment). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.crc_mismatch- The package is refused (container: crc mismatch). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.data_descriptor- The package is refused (container: data descriptor). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.deflate_stream- The package is refused (container: deflate stream). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.encrypted- The package is refused (container: encrypted). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.entry_order- The package is refused (container: entry order). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.extra_field- The package is refused (container: extra field). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.field_value- The package is refused (container: field value). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.flags- The package is refused (container: flags). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.header_mismatch- The package is refused (container: header mismatch). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.method- The package is refused (container: method). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.not_zip- The package is refused (container: not zip). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.overlap_or_gap- The package is refused (container: overlap or gap). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.prepended_data- The package is refused (container: prepended data). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.second_end_record- The package is refused (container: second end record). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.size_mismatch- The package is refused (container: size mismatch). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.trailing_data- The package is refused (container: trailing data). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.container.zip64- The package is refused (container: zip64). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.digest.entries_mismatch- The package is refused (digest: entries mismatch). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.digest.mismatch- The package is refused (digest: mismatch). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.digest.not_canonical- The package is refused (digest: not canonical). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.digest.package_mismatch- The package is refused (digest: package mismatch). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.layout.compiled_in_source- The package is refused (layout: compiled in source). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.layout.empty_directory- The package is refused (layout: empty directory). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.layout.missing_manifest- The package is refused (layout: missing manifest). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.layout.non_regular_file- The package is refused (layout: non regular file). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.layout.readme- The package is refused (layout: readme). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.layout.unknown_top_level- The package is refused (layout: unknown top level). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.case_collision- The package is refused (name: case collision). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.character- The package is refused (name: character). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.directory_entry- The package is refused (name: directory entry). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.duplicate- The package is refused (name: duplicate). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.encoding- The package is refused (name: encoding). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.file_directory_conflict- The package is refused (name: file directory conflict). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.not_nfc- The package is refused (name: not nfc). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.not_portable- The package is refused (name: not portable). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.name.shape- The package is refused (name: shape). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.not_found- The package is refused (not found). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.not_readable- The package is refused (not readable). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.version.malformed- The package is refused (version: malformed). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.version.missing- The package is refused (version: missing). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.version.not_string- The package is refused (version: not string). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.version.unsupported_major- The package is refused (version: unsupported major). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. package.version.unsupported_minor- The package is refused (version: unsupported minor). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.dialect- An input schema is refused (dialect). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.format_unsupported- An input schema is refused (format unsupported). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.id_duplicate- An input schema is refused (id duplicate). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.invalid- An input schema is refused (invalid). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.keyword_unknown- An input schema is refused (keyword unknown). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.pattern_unsupported- An input schema is refused (pattern unsupported). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.ref_by_path- An input schema is refused (ref by path). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.ref_escapes- An input schema is refused (ref escapes). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.ref_unresolved- An input schema is refused (ref unresolved). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. schema.syntax- An input schema is refused (syntax). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.amount_currency- An output's path, when or for_each does not parse (amount currency). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.date_format- An output's path, when or for_each does not parse (date format). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.division_by_zero- An output's path, when or for_each does not parse (division by zero). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.duration_format- An output's path, when or for_each does not parse (duration format). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.filter_argument- An output's path, when or for_each does not parse (filter argument). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.include- An output's path, when or for_each does not parse (include). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.number_range- An output's path, when or for_each does not parse (number range). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.safe_position- An output's path, when or for_each does not parse (safe position). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.syntax- An output's path, when or for_each does not parse (syntax). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.tag_context- An output's path, when or for_each does not parse (tag context). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. template.unknown_filter- An output's path, when or for_each does not parse (unknown filter). Next:
metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used. usage.bad_glob- A glob does not satisfy the glob grammar. Next:
metais help globs: Prints the glob grammar. 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 extract --help: Prints the operands and flags metais extract takes. usage.missing_operand- The package operand is not given. Next:
metais extract --help: Prints the operands and flags metais extract takes. usage.no_match- A glob selects no entry; nothing is written. Next:
metais ls <package> -r: Lists every entry, so a glob can be written against them. usage.package_from_stdin- The package operand is -, standard input. Next:
metais extract --help: Prints the operands and flags metais extract takes. usage.repeated_flag- A flag that may be given once is given again. Next:
metais extract --help: Prints the operands and flags metais extract takes. usage.unexpected_operand- An operand the command does not take. Next:
metais extract --help: Prints the operands and flags metais extract 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 extract --help: Prints the operands and flags metais extract takes.