Reference · command

metais grep

Search a package's entries for a regular expression, with context.

Reading a package

Usage

metais grep <package> <pattern> [<glob>]... [--context <n> | -C <n>] [--ignore-case | -i] [--max-results <n>] [--limit <name>=<value>]... [--json]

Examples

metais grep report-1.0.0.metais 'alt text' references/
Searches the references.
metais grep report-1.0.0.metais -i -C 2 '^## ' '**/*.md'
Lists every level-2 heading of the Markdown entries, with two lines around each.
metais grep report-1.0.0.metais schema .compiled/** --json
Searches the compiled files, as one metais.grep/1 document.

Detail

The pattern is RE2 syntax, as Go's regexp defines it, and is matched against each line without its line ending, so ^ and $ anchor the line; a CR before the LF is part of the ending. --ignore-case prepends (?i). The pattern is bounded by the pattern-length, regex-program and regex-work limits.

Globs select the entries searched (metais help globs); with none, every entry is searched but those beneath a segment that begins with a dot, so .compiled/ is searched only when a glob names it. Entries are searched in path order, lines in order. Binary entries are skipped and listed.

--max-results bounds the matching lines reported, from 1 to the grep-matches limit; the search still runs to the end, and counts every matching line. A line longer than 1024 bytes is shown cut, and read --lines gives it whole. No match is not a failure: grep exits 0.

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.
<pattern>
A regular expression in RE2 syntax; write -- before one that begins with -. Required.
<glob>
A glob selecting the entries to search; every entry when none is given. May be given more than once.

Flags

-C, --context <n>
Show n lines before and after each matching line, from 0 to the grep-context limit. Default: 0.
-i, --ignore-case
Match letters regardless of case.
--max-results <n>
Report at most n matching lines, from 1 to the grep-matches limit; by default 100, or the limit when it is lower. Default: 100.
--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

Each matching line as path:line:text and each line of context as path-line-text, with -- between groups that are not adjacent; a truncation notice and the binary entries skipped go to standard error.

--json: metais.grep/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.
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_pattern
The pattern is not RE2 syntax, or breaches pattern-length, regex-program or regex-work. Next: metais limits: Lists the limits a grep pattern is held to: pattern-length, regex-program and regex-work.
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 grep --help: Prints the operands and flags metais grep takes.
usage.missing_operand
The package operand is not given. Next: metais grep --help: Prints the operands and flags metais grep takes.
usage.package_from_stdin
The package operand is -, standard input. Next: metais grep --help: Prints the operands and flags metais grep takes.
usage.repeated_flag
A flag that may be given once is given again. Next: metais grep --help: Prints the operands and flags metais grep takes.
usage.unexpected_operand
An operand the command does not take. Next: metais grep --help: Prints the operands and flags metais grep 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 grep --help: Prints the operands and flags metais grep takes.