FSS Extended Read Documentation

The fss_extended_read program is a tool for reading and processing strings that follow the FSS-0001 (Extended) standard.

This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read.

This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter.

Standard Parameters

Short	Long	Description
`-h`	`--help`	Print the help message.
`+d`	`++dark`	Output using colors that show up better on dark backgrounds.
`+l`	`++light`	Output using colors that show up better on light backgrounds.
`+n`	`++no_color`	Do not print using color.
`+Q`	`++quiet`	Decrease verbosity, silencing most output.
`+E`	`++error`	Decrease verbosity, using only error output.
`+N`	`++normal`	Set verbosity to normal.
`+V`	`++verbose`	Increase verbosity beyond normal output.
`+D`	`++debug`	Enable debugging, significantly increasing verbosity beyond normal output.
`+v`	`++version`	Print only the version number.

The +Q/++quiet parameter silences all output that is not the intent and purpose of the program. For example, the purpose of the utf8 program is to print the Unicode code point or the UTF-8 byte code. The +Q/++quiet will not suppress this output. The new line printed at the end of the program, is however, not printed. The +Q/++quiet is ideal for using in scripting to help guarantee more consistent and controlled output.

The +N/++no_color simplifies the output to avoid the special color character codes. The special color character codes tend to take up a lot of extra space and may slow down printing performance.

Program Parameters

Short	Long	Description
`-a`	`--at`	Select Object at this numeric index.
`-c`	`--content`	Print the Content (default).
`-C`	`--columns`	Print the total number of columns.
`-D`	`--delimit`	Designate how to handle applying delimits.
`-d`	`--depth`	Select Object at this numeric depth.
`-e`	`--empty`	Include empty Content when processing.
`-l`	`--line`	Print only the Content at the given line.
`-n`	`--name`	Select Object with this name.
`-o`	`--object`	Print the Object.
`-p`	`--pipe`	Print using the special pipe format.
`-O`	`--original`	Print with the original quotes and escapes.
`-s`	`--select`	Select sub-Content at this index.
`-t`	`--total`	Print the total number of lines.
`-T`	`--trim`	Trim Object names on select or print.

All numeric positions (indexes) start at 0 instead of 1.

For example, a file of 17 lines would range from 0 to 16.

When using the --depth option, an order of operations is enforced on the parameters.

When this order of operations is in effect, parameters to the right of a depth parameter are influenced by that depth parameter:

--at: An Object index at the specified depth.
--depth: A new depth within the specified depth, indexed from the root.
--name: An Object name at the specified depth.

The parameter --depth must be in numeric order, but values in between may be skipped.

('-d 0 -a 1 -d 2 -a 2' would specify index 1 at depth 0, any index at depth 1, and index 2 at depth 2.)
('-d 2 -a 1 -d 0 -a 2' would be invalid because depth 2 is before depth 1.)

The parameter --select selects a Content column.

Specify both --object and the --total parameters to get the total objects.

When both --at and --name parameters are specified (at the same depth), the --at parameter value will be treated as a position relative to the specified --name parameter value.

This program may support parameters, such as --depth or --select, even if not supported by the standard.

This is done to help ensure consistency for scripting.

For parameters like --depth, if the standard doesn't support nested Content, then only a depth of 0 would be valid.

For parameters like --select, if the standard doesn't support multiple Content groups, then only a select of 0 would be valid.

The parameter --trim will remove leading and trailing white spaces when selecting objects or when printing objects.

When specifying both the --object parameter and the --content parameter, the entire Object and Content are printed, including the formatting.

Both the Object and Content printed are already escaped.

Both the Object and Content are separated by a space.

The parameter --delimit accepts the following:

none: Do not apply delimits.
all: (default) Apply all delimits.
object: Apply delimits for Objects.
A number, zero or greater: apply delimits for Content at the specified depth.
A number, zero or greater, followed by a +: (such as '1+') apply delimits for Content at the specified depth and any greater depth (numerically).
A number, zero or lesser, followed by a -: (such as '1-') apply delimits for Content at the specified depth and any lesser depth (numerically).

The --delimit parameter may be specified multiple times to customize the delimit behavior.

The --delimit values none and all, overrule all other delimit values.

The parameters --columns and --select refer to a Content column.

The word "column" is being loosely defined to refer to a specific Content.

This is not to be confused with a depth.