dot-api-sgr: Low-level API to manipulate ANSI sequences of SGR parameters

In jeanmathieupotvin/nanocli: Create command-line interfaces easily

Description

Create sequences of SGR parameters, assess their validity, and manipulate their components.

These functions are collectively considered to be a CRUD (Create, Read, Update, Delete) interface to ANSI sequences holding SGR parameters. They are meant to be used as building blocks of higher-order functions.

Usage

.sgrCreateSequence(...)

.sgrSimplifySequence(string = character(1L))

.sgrGetParameters(string = character(1L))

.sgrPushParameters(string = character(1L), ...)

.sgrPopParameters(string = character(1L), ...)

.sgrIsValidStrictSequence(string = character(1L))

.sgrIsValidSequence(string = character(1L))

Arguments

...	[integer() | list()] Any number of R structures containing integer values (possibly) representing SGR parameters. No coercion is done.
string	[character(1)] An ANSI sequence of SGR parameters.

Details

A valid ANSI sequence can be strict or non-strict.

Strict sequences

A string is a strictly valid ANSI sequence if these threee criteria are met.

1. It begins by the CSI (Control Sequence Introducer) string \033[, where \033 is the octal representation of the ASCII ESC character.

2. It ends with a single m character.

3. It encloses an arbitrary number of unquoted SGR parameters (integer values) all followed by a single ; character (except for the last one who is followed by the terminating character m).

Examples of strictly valid sequences are strings like \033[0m and \033[1;2;33m.

Non-strict sequences

A string is a non-strictly valid ANSI sequence if it is composed of one or multiple strictly valid sequences concatenated together. Examples of such sequences are strings like \033[1m\033[2;3m and \033[0m\033[5;66m.

Value

This depends on the function used.

• .sgrCreateSequence(), .sgrSimplifySequence(), .sgrPushParameters(), and .sgrPopParameters() return a character(1) representing a strictly valid ANSI sequence of SGR parameters.

• .sgrGetParameters() returns an integer() holding valid SGR parameters extracted from an ANSI sequence. This sequence needs not to be either valid or strict.

• .sgrIsValidStrictSequence() and .sgrIsValidSequence() return a logical(1). See section Details for the difference between strict and non-strict sequences.

Note

All these functions perform no input validation at runtime. Failing to pass valid parameters leads to undefined behavior. Because of that, they should always be wrapped into higher-order functions.

jeanmathieupotvin/nanocli documentation built on Feb. 2, 2022, 11:30 p.m.