NAME

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

SYNOPSIS

DESCRIPTION

text-block — reads text from standard input or given file, and writes it to standard output or a given file. On 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.
• 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 front of marked blocks.
• Insert Back: insert text from a file at 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 is 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 Highlight 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 command-line parameters.

-v | --version

Prints program version.

-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 lower 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.

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/!