Documentation - FSS Extended Read
Author: Kevin Day
Description: FSS Extended Read program documentation.
Keywords: Kevin Day, Kevux, FLL, Featureless, Linux, Library, FSS, FSS Extended Read, Open-Source

# 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.
`+C` | `++copyright` | Print the copyright.
`+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.