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

# IKI Read Documentation

The iki_read program is a tool for processing strings that follow the IKI standard, specifically IKI-0000 (Unrestricted).

This tool is designed to be scriptable and accepts piped input.

Different ways of interpreting and printing strings are available.

The entire string can be printed, replacing all IKI Variables and even allowing for primitive substitution or only the IKI Variables (or their Content) can be printed.

## 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 variable at this numeric index.
`-n` | `--name` | Select variables with this name.
`-s` | `--select` | Select Vocabulay (aka: Object) at this index.
`-c` | `--content` | Print the variable value (aka: content) (default).
`-l` | `--line` | Print only the variables at the given line within the file.
`-L` | `--literal` | Print the entire variable (aka: object, content, and syntax).
`-o` | `--object` | Print the variable name (aka: object).
`-t` | `--total` | Print the total number of variables.
`-w` | `--whole` | Print all of the data instead of just the IKI variable data.
`-R` | `--reassign` | Re-assign the variable for the given name and matching content value with the given string.
`-r` | `--replace` | Simple substitution, replacing the variable for the given name with the given string.
`-s` | `--substitute` | Substitute the variable for the given name and matching content value with the given string.
`-W` | `--wrap` | Prepend and append strings for the given name.

This program will find and print Variables, Vocabularies, or Content following the IKI standard, without focusing on any particular Vocabulary specification.

The `-r/--replace` option requires 2 additional parameters: `<vocabulary> <with>`.

vocabulary
  The name of the Vocabulary whose Content is to be substituted.
with
  The new string to use as the substitute.

The Vocabulary is case-sensitive and must exactly match.

The `-R/--reassign` option and the `-s/--substitute` options require 3 additional parameters:: `<vocabulary> <replace> <with>`.

vocabulary
  The name of the Vocabulary whose Content is to be substituted.
replace
  The Content matching this exact string will be substituted.
with
  The new string to use as the substitute.

The Vocabulary and replacement are case-sensitive and must exactly match.

The `-W/--wrap` option requires 3 additional parameters: `<vocabulary> <before> <after>`.

vocabulary
  The name of the vocabulary whose Content is to be wrapped.
before
  The string to prepend.
after
  The string to append.

The Vocabulary is case-sensitive and must exactly match.

The difference between `-r/--replace` and `-s/--substitute` is that the `-r/--replace` option substitutes all matching Vocabulary names and the `-s/--substitute` option substitutes all matching Vocabulary names that must also have the given matching Content.

The `-s/--reassign` option is identical to the `-s/--substitute` option except that the `-W/--wrap` option is ignored (not applied).

The `-s/--substitute` option takes priority over the `-r/--replace` option when matching the same Variable.

The default behavior is to only display Content portion of the IKI variable.