FY-TOOL(1)			   libfyaml			    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> ...]

DESCRIPTION
       fy-tool is a general YAML/JSON manipulation tool using libfyaml.	 Its
       operation is different depending on how it's called, either via aliases
       named fy-dump, fy-testsuite, fy-filter, fy-join, or via the --dump,
       --testsuite, --filter, --join, --ypath and --compose options.

       • In dump mode it will parse YAML/JSON input files and output YAML/JSON
	 according to the output format options.

       • In testsuite mode it will parse a single YAML input file and output
	 yaml testsuite reference output.

       • In filter mode it will parse YAML/JSON files and output YAML/JSON
	 output filtered according to the given option.

       • In join mode it will parse YAML/JSON files and join them into a
	 single YAML/JSON document according to the given command line
	 options.

       • In ypath mode it will parse YAML/JSON files and execute a ypath query
	 which will output a document stream according to the results. This is
	 an experimental mode under development, where the syntax is not yet
	 decided completely.

       • In compose mode, it operates similarly to dump, but the document tree
	 is created using the built-in composer API.

OPTIONS
       A number of options are common for all the different modes of operation
       and they are as follows: Common options.INDENT 0.0

       -q, --quiet
	      Quiet operation, does not output informational messages at all.

       -h, --help
	      Display usage information.

       -v, --version
	      Display version information.

       -I DIR, --include=DIR
	      Add the DIR  directory to the search path which will be used to
	      locate a YAML/JSON file.	The default path is set to ""

       -d LEVEL, --debug-level=LEVEL
	      Set the minimum numeric debug level value of the library to
	      LEVEL.  The numeric value must be in the range of 0 to 4 and
	      their meaning is as follows:

	      • 0 (DEBUG)

		Internal library debugging messages. No output is produced
		when the library was compiled with --disable-debug

	      • 1 (INFO)

		Informational messages about the internal operation of the
		library.

	      • 2 (NOTICE)

		Messsages that could require attention.

	      • 3 (WARNING)

		A warning message, something is wrong, but operation can
		continue.  This is the default value.

	      • 4 (ERROR)

		A fatal error occured, it is impossible to continue.

	      The default level is 3 (WARNING), which means that messages with
	      level 3 and higher will be displayed.
       Parser Options.INDENT 0.0

       -j JSONOPT, --json=JSONOPT
	      Marks the input files as JSON or YAML accordingly to:

	      • no

		The input files are always in YAML mode.

	      • force

		The input files are always set to JSON mode.

	      • auto

		The input files are set to JSON mode automatically when the
		file's extension is .json. This is the default.

	      JSON support is complete so all valid JSON files are parsed
	      according to JSON rules, even where those differ with YAML
	      rules.

       --yaml-1.1
	      Force YAML 1.1 rules, when input does not specify a version via
	      a directive.

       --yaml-1.2
	      Force YAML 1.2 rules, when input does not specify a version via
	      a directive.

       --yaml-1.3
	      Force YAML 1.3 rules, when input does not specify a version via
	      a directive.  This option is experimental since the 1.3 spec is
	      not yet released.

       --disable-accel
	      Disable use of acceleration features; use less memory but
	      potentially more CPU.

       --disable-buffering
	      Disable use stdio bufferring, reads will be performed via unix
	      fd reads. This may reduce latency when reading from a network
	      file descriptor, or similar.

       --disable-depth-limit
	      Disable the object depth limit, which is usually set to a value
	      near 60.	Using this option is is possible to process even
	      pathological inputs when using the default non-recursive build
	      mode.

       --prefer-recursive
	      Prefer recursive build methods, instead of iterative. This field
	      is merely here for evaluation purposes and will be removed in a
	      future version.

       --sloppy-flow-indentation
	      Use sloppy flow indentation, where indentation is not taken into
	      account in flow mode, even when the input is invalid YAML
	      according to the spec.

       --ypath-aliases
	      Process aliases using ypaths. Experimental option.

       --streaming
	      Only valid when in dump mode, enables streaming mode. This means
	      that no in-memory graph tree is constructed, so indefinite and
	      arbitrary large YAML input streams can be processed.

	      Note that in streaming mode:

	      • Key duplication checks are disabled.

	      • No reording of key order is possible when emitting (i.e.
		--sort is not available).

	      • Alias resolution is not available (i.e. --resolve).
       Resolver Options.INDENT 0.0

       -r, --resolve
	      Perform anchor and merge key resolution. By default this option
	      is disabled.

       -l, --follow
	      Follow aliases when performing path traversal. By default this
	      option is disabled.
       Testsuite Options.INDENT 0.0

       --disable-flow-markers
	      Do not output flow-markers for the testsuite output.
Emitter Options.INDENT 0.0

       -i INDENT, --indent=INDENT
	      Sets the emitter indent (in spaces). Default is 2.

       -w WIDTH, --width=WIDTH
	      Sets the preferred output width of the emitter. It is generally
	      impossible to strictly adhere to this limit so this is treated
	      as a hint at best.  It not valid in any oneline output modes
	      (i.e. flow-oneline or json-oneline).  Default value is 80.

       -m MODE, --mode=MODE
	      Sets the output mode of the YAML emitted. Possible values are:

	      • original

		The original formatting used in the input. This is default
		mode.

	      • block

		The output is forced to be in block mode. All flow constructs
		will be converted to block mode.

	      • flow

		The output is forced to be in flow mode. All block constructs
		will be converted to flow mode.

	      • flow-oneline

		The output is forced to be in flow mode, but no newlines will
		be emitted; the output is going to be a (potentially very)
		long line.

	      • json

		The output is forced to be in JSON mode. Note that it is
		impossible to output an arbitrary YAML file as JSON, so this
		may fail.

	      • json-oneline

		The output is forced to be in JSON mode and in a single line.

	      • dejson

		Output is in block YAML mode but with special care to convert
		JSON quoted strings in as non-idiomatic YAML as possible.  For
		example { foo: "this is a test" } will be emitted as foo: this
		is a test. YAML can handle scalars without using excessive
		quoting.

       -C MODE, --color=MODE
	      It is possible to colorize output using ANSI color escape
	      sequences, and the mode can be one of:

	      • off

		Never colorize output.

	      • on

		Always colorize output.

	      • auto

		Automatically colorize output when the output is a terminal.
		This is the default.

       -V, --visible
	      Make all whitespace (spaces, unicode spaces and linebreaks)
	      visible.	Note that this is performed using UTF8 characters so
	      it will not work on non-UTF8 terminals, or a non-UTF8 complete
	      font.

       -s, --sort
	      Sort keys on output. This option is disabled by default.

       -c, --comment
	      Experimental output comments option. Enabled output while
	      preserving comments.  Disabled by default.

       --strip-labels
	      Strip labels on output. Disabled by default.

       --strip-tags
	      Strip tags on output. Disabled by default.

       --strip-doc
	      Strip document indicators on output. Disabled by default.

       --null-output
	      Do not generate any output, useful for profiling the parser.
       YPATH options.INDENT 0.0

       --dump-pathexpr
	      Dump the produced path expression for debugging.

       --no-exec
	      Do not execute the expression. Useful when used with
	      --dump-pathexpr
       Compose options.INDENT 0.0

       --dump-path
	      Dump the path while composing.
Tool mode select options.INDENT 0.0

       --dump Select dump mode of operation. This is the default.  This mode
	      is also enabled when the called binary is aliased to fy-dump.

	      In this mode, all files provided in the command line will be
	      dumped in one continuous stream, to the standard output, using
	      document start indicators to mark the start of end new file.

	      If the file provided is - then the input is the standard input.

       --testsuite
	      Select testsuite mode of operation.  This mode is also enabled
	      when the called binary is aliased to fy-testsuite.

	      In this mode, a single YAML file is read and an event stream is
	      generated which is the format used for yaml-testsuite
	      compliance.

	      If the file provided is - then the input is the standard input.

       --filter
	      Select filter mode of operation.	This mode is also enabled when
	      the called binary is aliased to fy-filter.

	      In this mode, a single YAML file is read from the standard input
	      for each path that is provided in the command line a document
	      will be produced to the standard output.	To use file instead of
	      standard input use the -f/--file option.

	      If the file provided is - then the input is the standard input.

	      -f FILE, --file=FILE
		     Use the given file as input instead of standard input.

		     If	 first character of FILE is > the the input is the
		     content of the option that follows.  For example --file
		     ">foo: bar" is as --file file.yaml with file.yaml "foo:
		     bar"

       --join Select join mode of operation.  This mode is also enabled when
	      the called binary is aliased to fy-join.

	      In this mode, multiple YAML files are joined into a single
	      document, emitted to the standard output.

	      If the file provided is - then the input is the standard input.

	      -T PATH, --to=PATH
		     The target path of the join. By default this is the root
		     /.

		     If	 first character of FILE is > the the input is the
		     content of the option that follows.

	      -F PATH, --from=PATH
		     The origin path of the join (for each input). By default
		     this is the root /.

		     If	 first character of FILE is > the the input is the
		     content of the option that follows.

	      -t PATH, --trim=PATH
		     Trim path of the output of the join. By default this is
		     the root /.

		     If	 first character of FILE is > the the input is the
		     content of the option that follows.

       --ypath
	      Process files and output query results using ypath.

       --compose
	      Use the composer API to build the document instead of direct
	      events.

EXAMPLES
       Example input files

       We're going to be using a couple of YAML files in our examples.

       invoice.yaml

	  # invoice.yaml
	  invoice: 34843
	  date	 : !!str 2001-01-23
	  bill-to: &id001
	  given	 : Chris
	  family : Dumars
	  address:
		  lines: |
		  458 Walkman Dr.
		  Suite #292

       simple-anchors.yaml

	  # simple-anchors.yaml
	  foo: &label { bar: frooz }
	  baz: *label

       mergekeyspec.yaml

	  ---
	  - &CENTER { x: 1, y: 2 }
	  - &LEFT { x: 0, y: 2 }
	  - &BIG { r: 10 }
	  - &SMALL { r: 1 }

	  # All the following maps are equal:

	  - # Explicit keys
	    x: 1
	    y: 2
	    r: 10
	    label: center/big

	  - # Merge one map
	    << : *CENTER
	    r: 10
	    label: center/big

	  - # Merge multiple maps
	    << : [ *CENTER, *BIG ]
	    label: center/big

	  - # Override
	    << : [ *BIG, *LEFT, *SMALL ]
	    x: 1
	    label: center/big

       bomb.yaml

	  a: &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol"]
	  b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a]
	  c: &c [*b,*b,*b,*b,*b,*b,*b,*b,*b]
	  d: &d [*c,*c,*c,*c,*c,*c,*c,*c,*c]
	  e: &e [*d,*d,*d,*d,*d,*d,*d,*d,*d]
	  f: &f [*e,*e,*e,*e,*e,*e,*e,*e,*e]
	  g: &g [*f,*f,*f,*f,*f,*f,*f,*f,*f]
       fy-dump examples.

       Parse and dump generated YAML document tree in the original YAML form

	  $ fy-dump invoice.yaml

	  invoice: 34843
	  date: !!str 2001-01-23
	  bill-to: &id001
	  given: Chris
	  family: Dumars
	    address:
	    lines: |
	      458 Walkman Dr.
	      Suite #292

       Parse and dump generated YAML document tree in flow YAML form

	  $ fy-dump -mflow invoice.yaml

	  {
	    invoice: 34843,
	    date: !!str 2001-01-23,
	    bill-to: &id001 {
	      given: Chris,
	      family: Dumars,
	      address: {
		lines: "458 Walkman Dr.\nSuite #292\n"
	      }
	    }
	  }

       Parse and dump generated YAML document from the input string

	  $ fy-dump -mjson ">foo: bar"

	  {
	    "foo": "bar"
	  }

       Using the resolve option on the simple-anchors.yaml

	  $ fy-dump -r simple-anchor.yaml

	  foo: &label {
	      bar: frooz
	    }
	  baz: {
	      bar: frooz
	    }

       Stripping the labels too:

	  $ fy-dump -r --strip-label simple-anchor.yaml

	  foo: {
	      bar: frooz
	    }
	  baz: {
	      bar: frooz
	    }

       Merge key support:

	  $ fy-dump -r --strip-label mergekeyspec.yaml

	  ---
	  - {
	      x: 1,
	      y: 2
	    }
	  - {
	      x: 0,
	      y: 2
	    }
	  - {
	      r: 10
	    }
	  - {
	      r: 1
	    }
	  - x: 1
	    y: 2
	    r: 10
	    label: center/big
	  - y: 2
	    x: 1
	    r: 10
	    label: center/big
	  - r: 10
	    y: 2
	    x: 1
	    label: center/big
	  - y: 2
	    r: 10
	    x: 1
	    label: center/big

       Sorting option:

	  $ fy-dump -s invoice.yaml

	  bill-to: &id001
	    address:
	      lines: |
		458 Walkman Dr.
		Suite #292
	    family: Dumars
	    given: Chris
	  date: !!str 2001-01-23
	  invoice: 34843
       fy-testsuite example.

       An example using the testsuite mode generates the following event
       stream from invoice.yaml

       Parse and dump test-suite event format

	  $ fy-testsuite invoice.yaml
       fy-filter examples.

       Filter out from the /bill-to path of invoice.yaml

	  $ cat invoice.yaml | fy-filter /bill-to

	  &id001
	  given: Chris
	  family: Dumars
	  address:
	    lines: |
	      458 Walkman Dr.
	      Suite #292

       Filter example with arrays (and use the --file option)

	  $ fy-filter --file=mergekeyspec.yaml /5

	  ---
	  <<: *CENTER
	  r: 10
	  label: center/big

       Follow anchors example

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

	  frooz

       Handle YAML bombs (if you can spare the memory and cpu time)

	  $ fy-filter --file=bomb.yaml -r / | wc -l
	  6726047

       You don't have to, you can just follow links to retrieve data.

	  $ fy-filter --file=stuff/bomb.yaml -l --strip-label /g/0/1/2/3/4/5/6

	  "lol"

       Following links works with merge keys too:

	  $ fy-filter --file=mergekeyspec.yaml -l --strip-label /5/x

	  --- 1
       fy-join examples.

       Joining two YAML files that have root mappings.

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

	  foo: &label {
	      bar: frooz
	    }
	  baz: *label
	  invoice: 34843
	  date: !!str 2001-01-23
	  bill-to: &id001
	    given: Chris
	    family: Dumars
	    address:
	      lines: |
		458 Walkman Dr.
		Suite #292

       Join two files with sequences at root:

	  $ fy-join -mblock ">[ foo, bar ]" ">[ baz ]"

	  - foo
	  - bar
	  - baz

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(1)

COPYRIGHT
       2019, Pantelis Antoniou

			       January 14, 2022			    FY-TOOL(1)