FY-TOOL(1)

NAME
fy-tool - fy-tool documentation

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 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.

    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.

SEE ALSO

libfyaml(3)

COPYRIGHT
2019-2026, Pantelis Antoniou