fy-tool

Synopsis

fy-tool [OPTIONS] [<file> …]

fy-dump [OPTIONS] [<file> …]

fy-testsuite [OPTIONS] <file>

fy-filter [OPTIONS] [-f FILE] [<path> …]

fy-join [OPTIONS] [-T PATH] [-F PATH] [-t PATH] [<file> …]

fy-ypath [OPTIONS] <ypath-expression> [<file> …]

fy-compose [OPTIONS] [<file> …]

fy-b3sum [OPTIONS] [<file> …]

Description

fy-tool is the libfyaml command-line front-end for parsing, rewriting, querying, joining, testing, reflecting on, and hashing YAML and JSON data.

The executable changes behaviour either by the invoked program name (fy-dump, fy-testsuite, fy-filter, fy-join, fy-ypath, fy-compose, fy-b3sum) or by an explicit mode-select option such as --dump or --filter.

The default mode is dump.

Options

General options

-h, --help: Display the built-in help message.

-v, --version: Display the libfyaml version.

-q, --quiet: Suppress informational and non-fatal diagnostic output.

-d LEVEL, --debug-level LEVEL: Set the minimum diagnostic severity emitted by the library. The default is 3 (warning level).

-C MODE, --color MODE: Control ANSI color output. Supported values are on, off, and auto. The default is auto.

-V, --visible: Make spaces, tabs, and line breaks visible in text output.

--dry-run: Parse the input but suppress normal output generation.

Diagnostic options

--disable-diag MODULE: Disable diagnostic output for the named module.

--enable-diag MODULE: Enable diagnostic output for the named module.

--show-diag OPTION: Show the named diagnostic field. Supported values are source, position, type, and module.

--hide-diag OPTION: Hide the named diagnostic field.

Parser options

-I DIR, --include DIR: Add DIR to the input include search path.

-j MODE, --json MODE: Select JSON input handling. Supported values are no, force, and auto. The default is auto.

-r, --resolve: Resolve anchors and merge keys while parsing.

--yaml-1.1: Force YAML 1.1 rules when the input does not declare a version.

--yaml-1.2: Force YAML 1.2 rules when the input does not declare a version.

--yaml-1.3: Force YAML 1.3 rules when the input does not declare a version.

-l, --follow: Follow aliases during path traversal and related path-based operations.

--sloppy-flow-indentation: Accept relaxed indentation rules in flow mode.

--prefer-recursive: Prefer recursive algorithms over iterative ones.

--ypath-aliases: Enable alias processing for ypath evaluation.

--allow-duplicate-keys: Allow duplicate mapping keys.

--collect-errors: Collect multiple parsing errors before reporting failure.

--disable-accel: Disable parser/emitter acceleration features.

--disable-buffering: Disable stdio buffering and use direct file-descriptor reads.

--disable-mmap: Disable memory-mapped input.

--disable-depth-limit: Disable the normal nesting-depth limit.

Emitter options

-i INDENT, --indent INDENT: Set the output indentation width. The default is 2.

-w WIDTH, --width WIDTH: Set the preferred output width. Use inf for no width limit. The default is 80.

-m MODE, --mode MODE: Select the output style. Supported values are original, block, flow, flow-oneline, json, json-tp, json-oneline, dejson, pretty, flow-compact, and json-compact.

-s, --sort: Sort mapping keys before emitting output.

-c, --comment: Preserve and emit comments where supported.

--strip-labels: Strip anchors and aliases from emitted output.

--strip-tags: Strip emitted tags.

--strip-doc: Strip document start and end markers.

--strip-empty-kv: Omit keys whose values are empty or null.

--null-output: Suppress normal output generation.

--no-ending-newline: Do not append a final trailing newline.

--preserve-flow-layout: Preserve single-line flow collection layout when possible.

--indented-seq-in-map: Indent block sequences that appear inside block mappings.

--streaming: Use streaming output mode. This is the default.

--no-streaming: Disable streaming output mode.

--recreating: Recreate streaming events instead of passing them through directly.

Testsuite options

--disable-flow-markers: Omit testsuite flow markers.

--disable-doc-markers: Omit testsuite document markers.

--disable-scalar-styles: Omit testsuite scalar-style markers.

--document-event-stream: Build a document first and then generate the event stream from it.

--tsv-format: Emit testsuite output in TSV format.

Input options

-f FILE, --file FILE: Read from FILE instead of standard input where the selected mode uses a single input source. If FILE begins with >, the remaining text is treated as literal input content.

Join options

-T PATH, --to PATH: Join into PATH. The default is /.

-F PATH, --from PATH: Take joined input from PATH. The default is /.

-t PATH, --trim PATH: Emit only PATH from the joined result. The default is /.

YPATH options

-F PATH, --from PATH: Start evaluation from PATH. The default is /.

--dump-pathexpr: Dump the parsed path expression before evaluation.

--noexec: Parse the expression but do not execute it.

Compose options

--dump-path: Dump the path while composing a document.

B3SUM options

--b3sum: Enable BLAKE3 hashing mode.

--derive-key CONTEXT: Use key-derivation mode with CONTEXT.

--no-names: Omit file names from checksum output.

--raw: Emit raw digest bytes.

--length N: Emit only N output bytes, up to the BLAKE3 maximum.

--check: Verify checksums read from input files.

--keyed: Use keyed hashing, reading the secret key from standard input.

--backend BACKEND: Select the BLAKE3 backend implementation.

--list-backends: List available BLAKE3 backends.

--num-threads N: Set the worker-thread count. 0 means automatic selection and -1 disables threaded hashing.

--file-buffer N: Set the per-file I/O buffer size.

--mmap-min-chunk N: Set the minimum chunk size used for memory-mapped hashing input.

--mmap-max-chunk N: Set the maximum chunk size used for memory-mapped hashing input.

Reflection options

--reflect: Enable reflection mode.

--generate-c: Generate C definitions from reflection input.

--generate-blob BLOB: Generate a packed reflection blob and write it to BLOB.

--import-blob BLOB: Import reflection metadata from BLOB.

--import-c-file FILE: Import reflection metadata from FILE.

--cflags FLAGS: Pass compiler flags to reflection imports of C source files.

--entry-type TYPE: Select the reflection entry-point type.

--packed-roundtrip: Round-trip reflection data through the packed representation.

--no-prune-system: Keep system types in the reflection database.

--type-include REGEX: Include only reflected types matching REGEX.

--type-exclude REGEX: Exclude reflected types matching REGEX.

--dump-reflection: Dump reflection structures for debugging.

--debug-reflection: Enable verbose reflection debug output.

Generic options

--generic: Enable generic data-structure dumping mode.

--generic-testsuite: Enable generic testsuite mode.

--builder-policy: Select the generic builder policy.

--generic-parse-dump: Parse and dump using the generic layer.

--dedup: Enable generic deduplication.

--no-dedup: Disable generic deduplication.

--dump-primitives: Dump generic primitive values explicitly.

--create-markers: Create source markers in generated generic data.

--pyyaml-compat: Enable PyYAML compatibility mode.

--keep-style: Preserve style information in generic data.

Modes

--dump: Select dump mode. This is the default and also the mode used by fy-dump.

--testsuite: Select testsuite mode. This is also the mode used by fy-testsuite.

--filter: Select filter mode. This is also the mode used by fy-filter.

--join: Select join mode. This is also the mode used by fy-join.

--ypath: Select ypath query mode. This is also the mode used by fy-ypath.

--scan-dump: Select the internal scan-dump mode.

--parse-dump: Select the internal parse-dump mode.

--compose: Select composer-driver dump mode. This is also the mode used by fy-compose.

--yaml-version-dump: Print YAML version information.

Examples

Dump a YAML file back out using the default emitter mode:

$ fy-dump invoice.yaml

Resolve anchors and strip labels from the result:

$ fy-dump -r --strip-labels simple-anchors.yaml

Read literal input text via --file:

$ fy-filter --file \">foo: bar\" /

Select data from a file using a path expression:

$ fy-filter --file simple-anchors.yaml /baz/bar

Join two root mappings into a single document:

$ fy-join simple-anchors.yaml invoice.yaml

Generate testsuite event output:

$ fy-testsuite invoice.yaml

List available BLAKE3 backends:

$ fy-b3sum --list-backends

Author

Pantelis Antoniou <pantelis.antoniou@konsulko.com>

Bugs

The only supported input and output character encoding is UTF8.
Sorting does not respect language settings.
There is no way for the user to specific a different coloring scheme.