FLATML manpage

flatml(1) General Commands Manual

NAME

flatml — A shell filter flattening markup properties of XML, JSON, YAML, INI or PROPERTIES format to a key/value per line format for easy addressing elements in complex data sets.

SYNOPSIS

flatml [ -i <inputFile[…]> ] [ -o <outputFile> ] [ { -f <format> | [ -d <delimiter> ] [ { -k <key> | -p <pattern> | -s } ] [ -n ] } ] [ -t <timeout> ] [ -r ] [ -v ] [ --debug ]
flatml --help | --sysinfo [ -v ]

DESCRIPTION

This manual page documents the flatml command: The flatml command flattens one or multiple markup input file(s) --input-file or <STDIN> of formats XML, JSON or YAML with an optional delimiter --delimiter (defaulting to .) separating the markup hierarchy into a flat path and writes the flattened properties back to an output file --output-file or <STDOUT> optionally converting back the output to a XML, JSON or YAML markup format --format or optionally sorting --sort the output alphabetically as well as of optionally keeping --no-escape the output’s <CR> and line feed <LF> characters (being converted by default to “\r” and “\n” char sequences). In addition a specific value may be retrieved from the flattened input file(s) --input-file or <STDIN> by specifying the according flattened key --key or a subset of the flattened input file(s) --input-file or <STDIN> may be retrieved by specifying the according ANT alike --pattern with * matching a single path element, ** matching multiple path elements and ? matching a single character.

Depending on the executable’s flavor the command might also be named flatml-x.y.z.jar, flatml-bundle-x86_64-x.y.z.elf, flatml-bundle-x86_64-x.y.z.exe, flatml-installer-x86_64-x.y.z.msi, flatml-launcher-x.y.z.sh, flatml-launcher-x86_64-x.y.z.elf, flatml-launcher-x86_64-x.y.z.exe, flatml-native-x86_64-x.y.z.elf where x.y.z stands for the version of the flatml command. The according executable’s name will be referenced to in this manual as flatml.

OPTIONS

--debug: Enables the debug mode with additional (developer readable) informational output.
--help: Shows this help.
--sysinfo: Shows some system information for debugging purposes.
-d --delimiter <delimiter>: The delimiter to be used when separating the markup hierarchy into a flat path. If omitted, then the dot “.” is used.
-f --format <format>: Specifies the output format instead of flattened properties: { JSON, XML, YAML }
-i --input-file <inputFile[…]>: The input markup (XML, JSON, YAML) file(s) from which to read the values (can be used multiple times to merge multiple files). If omitted, then <STDIN> is used.
-k --key <key>: The key (flattened path) of the value to retrieve.
-n --no-escape: Preserves any carriage return <CR> and line feed <LF> characters (omits escaping them with \r and \n char sequences).
-o --output-file <outputFile>: The (flat) output file to which to write the values, if omitted, then <STDOUT> is used.
-p --pattern <pattern>: The ant like pattern (* matching a single path element, ** matching multiple path elements and ? matching a single character) of the keys (flattened paths) which’s lines to retrieve.
-r --remove: Removes an XML document’s root element as it might just serve the purpose of an envelope.
-s --sort: Sorts the keys of the flattened markup.
-t --timeout <timeout>: Specifies the timeout (seconds) to wait for input, a value of -1 disables the dedicated timeout.
-v --verbose: Enables the verbose mode with additional (human readable) informational output.

EXAMPLES

Flattens markup from <STDIN> to <STDOUT>:

  • flatml

Flattens markup from <STDIN> to <STDOUT> with given delimiter:

  • flatml -d <delimiter>

Converts markup from <STDIN> to <STDOUT> using given output format:

  • flatml -f <format>

Converts markup from <STDIN> to <STDOUT> with given delimiter to output format:

  • flatml -d <delimiter> -f <format>

Flattens markup from <STDIN> to output file:

  • flatml -o <outputFile>

Flattens markup from <STDIN> to output file with given delimiter:

  • flatml -o <outputFile> -d <delimiter>

Flattens markup from <STDIN> to output file using a timeout:

  • flatml -o <outputFile> -t <timeout>

Flattens markup from input file to <STDOUT>:

  • flatml -i <inputFile>

Flattens markup from input file to <STDOUT> and alphabetically sorts the result:

  • flatml -i <inputFile> -s

Flattens markup from input file to <STDOUT> removing an XML root envelope:

  • flatml -i <inputFile> -r

Flattens markup from input file to output file:

  • flatml -i <inputFile> -o <outputFile>

Flattens and merges markup from multiple(!) input files to <STDOUT>:

  • flatml -i <inputFile> -i <inputFile> -i <inputFile>

Flattens and merges markup from multiple(!) input files to output file:

  • flatml -i <inputFile> -i <inputFile> -i <inputFile> -o <outputFile>

Prints the value for the given key (flattened path) to <STDOUT>:

  • flatml -i <inputFile> -k <key>

Prints the key’s (flattened paths) lines matching the given pattern to <STDOUT>:

  • flatml -i <inputFile> -p <pattern>

To show the help text:

  • flatml --help

To print the system info:

  • flatml --sysinfo

BUGS

See BitBucket issues at <https://bitbucket.org/funcodez/funcodes-flatml/issues>

AUTHOR

Siegfried Steiner steiner@refcodes.org

SEE ALSO