text-block(1)

NAME
text-block - processes text blocks

SYNOPSIS
text-block [-C | - -cat] [OPTIONS]
text-block [-0 | - -discard] [OPTIONS]
text-block [-H | - -highlight] [OPTIONS]
text-block [-E | - -enumerate] [OPTIONS]
text-block [-X | - -extract] [OPTIONS]
text-block [-D | - -delete | - -remove] [OPTIONS]
text-block [-F insert_file | - -insert-front insert_file] [OPTIONS]
text-block [-B insert_file | - -insert-back insert_file] [OPTIONS]
text-block [-R insert_file | - -replace insert_file] [OPTIONS]
text-block [-h | - -help]
text-block [-v | - -version]

OPTIONS: [-b begin_tag | - -begin-tag begin_tag] [-e end_tag | - -end-tag end_tag]
[-i | - -input input_file]
[-o | - -output output_file]
[-a | - -append]
[-p | - -in-place]
[-k | - -keep-broken]
[-m | - -min-actions] [-M | - -max-actions]
[-s | - -select from_line to_line]
[-t | - -tag tag]
[-y | - -include-tags] [-x | - -exclude-tags]
[-f | - -full-tag-lines] [-g | - -tags-only]
[-q | - -suppress-warnings]
[- -enumerate-format format]
[- -enumerate-label1 string] [- -enumerate-label2 string]
[- -highlight-begin string] [- -highlight-end string]
[- -highlight-unmarked1 string] [- -highlight-unmarked2 string]
[- -highlight-marked1 string] [- -highlight-marked2 string]
[- -highlight-param begin_label end_label unmarked1_label unmarked2_label marked1_label marked2_label]

DESCRIPTION
text-block - reads text from standard input or given file, and writes it to standard output or a given file. To the text, various modifications can be applied, according to the operation mode:

•   Cat: copy the input text as-is.

•   Discard: do nothing (i.e. just discard the input).

•   Enumerate: add line numbers. The format of the enumeration is configurable.

•   Extract: only output the text between markers, discarding everything else.

•   Highlight: visually highlight text block between markers. The format of the marking is configurable, e.g. to apply ANSI colouring, etc.

•   Delete: remove text between markers.

•   Insert Front: insert text from a file at the front of marked blocks.

•   Insert Back: insert text from a file at the back of marked blocks.

•   Replace: replace text of marked blocks by text from a file.

The marking used for the operation modes is based on configurable begin and end tags, e.g. <BEGIN-OF-BLOCK> and <END-OF-BLOCK>, or BEGIN and END. The handling of tags is configurable:

•   tags-only: only the text between the marker tags belongs to a block. That is, multiple blocks can appear on the same line. This is the default.

•   full-tag-lines: a marker includes the full line of its begin and end tags. That is, a line containing a begin/end tag is handled like being the begin/end tag. This also means that only the first tag in a line is handled. All further tags in the same line are ignored! Hint: Use Highlight mode to visualise the behaviour.

Furthermore, the handling of begin/end tags is configurable as well:

•   exclude-tags: marked text does not include the begin/end tags. This is the default.

•   include-tags: marked text includes the begin/end tags.

A special case is to have identical begin/end tags, e.g. <MARKER>. The text block "inside" this tag is therefore always empty. A use case for such a marker is e.g. to mark where to insert the contents of a file.

Alternatively to marking by tags, the marking can be based on a line number range selection. Negative line numbers denote counting backwards from the end of the file, which in this case needs to be line-counted first. That is, input from standard input is not possible in this case.

ARGUMENTS
The following options are available:

-C | - -cat
    Run in Cat mode (default).

-0 | - -discard
    Run in Discard mode.

-H | - -highlight
    Run in Highlight mode.

-E | - -enumerate
    Run in Enumerate mode.

-X | - -extract
    Run in Extract mode.

-D | - -delete | - -remove
    Run in Delete mode.

-F insert_file | - -insert-front insert_file
    Run in Insert-Front mode. "-" is placeholder for inserting from standard input. In this case, an input file is required.

-B insert_file | - -insert-back insert_file
    Run in Insert-Back mode. "-" is placeholder for inserting from standard input. In this case, an input file is required.

-R insert_file | - -replace insert_file
    Run in Replace mode. "-" is placeholder for replacing from standard input. In this case, an input file is required.

-h | - -help
    Prints the program's command-line parameters and exits.

-v | - -version
    Prints the program version and exits.

-s | - -select from_line to_line
    Select a line range, ranging from line from_line to line to_line. A from_line of one (1) denotes marking from start of the file. A to_line of zero (0) denotes marking until end of the file. If a line number is negative, it is counted backwards from the end of the file. This requires an input file (--input|-i), which is line-counted first. Line range selection is mutually exclusive with tags (--begin-tag|-b|--end-tag|--tag|-t).

-b begin_tag | - -begin-tag begin_tag
    Sets the begin tag. Tags are mutually exclusive with line selection (--select|-s).

-e end_tag | - -end-tag end_tag
    Sets the end tag. Tags are mutually exclusive with line selection (--select|-s).

-t tag | - -tag tag
    Sets a combined begin/end tag, i.e. the tag marks begin and end. Tags are mutually exclusive with line selection (--select|-s).

-i | - -input input_file
    Sets the input file. "-" is placeholder for reading from standard input (default).

-o | - -output output_file
    Sets the output file. By default, an existing output file will be overwritten. "-" is placeholder for writing to standard output (default)

-a | - -append
    Opens the output file in append mode, appending new output instead of overwriting an existing file.

-p | - -in-place
    In-place update into the input file. The output is written to a temporary file with extension "~" first, which replaces the input file on success.

-k | - -keep-broken
    Keep broken output in case of error (default: off).

-m | - -min-actions
    Set lower limit for number of marking actions. If the number of applied markings falls below this limit, an error is returned.

-M | - -max-actions
    Set upper limit for number of marking actions. If the number of applied markings exceeds this limit, an error is returned.

-y | - -include-tags
    Include the marker tags in the marking. Hint: Use Highlight mode to visualise the behaviour.

-x | - -exclude-tags
    Exclude the marker tags from the marking. Hint: Use Highlight mode to visualise the behaviour.

-f | - -full-tag-lines
    Include full marker tag lines in the marking. Hint: Use Highlight mode to visualise the behaviour.

-g | - -tags-only
    Exclude the marker tag lines from the marking. Hint: Use Highlight mode to visualise the behaviour.

-q | - -suppress-warnings
    Suppress warnings on useless input parameters. Useful for debugging.

- -enumerate-format format
    In Enumerate mode, sets the format of the line number output according to printf formatting. However, only the number format specification is allowed here. Examples:

    •   06 -> add leading zero to get a 6-digit output (e.g. "000001", etc.). This is the default.

    •   4 -> 4-digit line numbers, prepended with space when necessary (e.g. " 2", etc.).

    •   -4 -> left-adjusted 4-digit number (e.g. "3 ").

- -enumerate-label1 string
    For Enumerate mode: prepends the given string before the line number output. Default: $'\x1b[36m' (enables cyan colour output).

- -enumerate-label2 string
    For Enumerate mode: appends the given string before the line number output. Default: $'\x1b[0m ' (disables colour output, and add a space).

- -highlight-begin string
    For Highlight mode: Sets string to visualise the begin of a marked block. Default: ⭐.

- -highlight-end string
    For Highlight mode: Sets string to visualise the end of a marked block. Default: 🛑.

- -highlight-unmarked1 string
    For Highlight mode: Sets string to visualise the begin of an unmarked text fragment. Default: $'\x1b[34m' (enables blue colour output).

- -highlight-unmarked2 string
    For Highlight mode: Sets string to visualise the end of an unmarked text fragment. Default: $'\x1b[0m ' (disables colour output).

- -highlight-marked1 string
    For Highlight mode: Sets string to visualise the begin of a marked text fragment. Default: $'\x1b[31m' (enables red colour output).

- -highlight-marked2 string
    For Highlight mode: Sets string to visualise the end of a marked text fragment. Default: $'\x1b[0m ' (disables colour output).

- -highlight-param begin_label end_label unmarked1_label unmarked2_label marked1_label marked2_label
    A shortcut to set all 6 highlight parameters at once.

EXIT STATUS
The text-block tool exits with 0 on success, and >0 in case of an error.

EXAMPLES
Note: the example input files example1.txt, example2.txt, insert.txt, and numbers.txt, referred to in the following command-line examples, are usually installed under /usr/share/text-block or /usr/local/share/text-block/

  Cat Mode

•   text-block -i example1.txt --cat

•   text-block -i /etc/system-info.d/01-example

•   text-block -i /etc/system-info.d/01-example -C

  Enumerate Mode

•   text-block -i example1.txt --enumerate

•   figlet "Test!" | text-block -E

•   text-block -i /etc/system-info.d/01-example -E

•   text-block -i /etc/system-info.d/01-example --enumerate --enumerate-format "6" --enumerate-label1 $'\x1b[37m<' --enumerate-label2 $'>\x1b[0m '

  Highlight Mode

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' --highlight

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -H --exclude-tags --tags-only

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -H --include-tags --tags-only

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -H --include-tags --full-tag-lines

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -H --exclude-tags --full-tag-lines

•   text-block -i example2.txt -b '<MARKER>' -H --exclude-tags --tags-only

•   text-block -i example2.txt -b '<MARKER>' -H --include-tags --tags-only

•   text-block -i example2.txt -b '<MARKER>' -H --include-tags --full-tag-lines

•   text-block -i example2.txt -b '<MARKER>' -H --exclude-tags --full-tag-lines

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' --highlight --highlight-param "☀" "🌙" $'\[32m' $'\[0m' $'\[31;5m' $'\[0m'

•   text-block -i numbers.txt --select 1 3 -H

•   text-block -i numbers.txt --select -3 -1 -H

•   text-block -i numbers.txt --select -5 0 -H

  Delete Mode

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' --delete

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -D

•   text-block -i numbers.txt --select 2 4 -D

•   text-block -i numbers.txt --select -4 -2 -D

•   text-block -i numbers.txt -s -7 0 -D

  Insert Front Mode

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' --insert-front insert.txt

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -F insert.txt

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -F insert.txt -f

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -F insert.txt --min-actions 1 --max-actions 1

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -F insert.txt -m 1 -M 1

•   text-block -i numbers.txt -F insert.txt --select 4 7

•   text-block -i numbers.txt -F insert.txt --select -4 -2

•   text-block -i numbers.txt -F insert.txt -s 4 0

  Insert Back Mode

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' --insert-back insert.txt

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -B insert.txt

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -B insert.txt -f

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -B insert.txt --min-actions 1 --max-actions 1

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -B insert.txt -m 1 -M 1

•   text-block -i numbers.txt -B insert.txt --select 4 7

•   text-block -i numbers.txt -B insert.txt --select -4 -2

•   text-block -i numbers.txt -B insert.txt -s 4 0

  Replace Mode

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' --replace insert.txt

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' --replace insert.txt --include-tags

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' --replace insert.txt --include-tags --full-tag-lines

•   text-block -i example1.txt -b '<BEGIN-BLOCK>' -e '<END-BLOCK>' -R insert.txt -gy

•   text-block -i numbers.txt -R insert.txt --select 4 7

•   text-block -i numbers.txt -R insert.txt --select -4 -2

•   text-block -i numbers.txt -R insert.txt -s 4 0

  Other Examples

•   text-block --help

•   text-block --version

•   text-block -v

SEE ALSO
print-utf8(1,) System-Info(1)

NOTES
This program is part of System-Tools. The latest version of System-Tools can be found on the System-Tools Homepage at System-Tools Homepage: https://www.nntb.no/~dreibh/system-tools/.

AUTHORS
Thomas Dreibholz, Homepage: https://www.nntb.no/~dreibh