Crate ansi_control_codes

Source
Expand description

§ANSI Escape Code Library

ANSI escape sequences are a standard for in-band signalling to control cursor location, color, font styling, and other options on video text terminals and terminal emulators.

This library contains all ANSI Escape Codes that are defined in the ISO 6429 Standard. ISO 6429 is the international standard that followed from the efforts of aligning the european ECMA-48 Standard and the american ANSI X3.64 Standard.

§Notation

In the ECMA-48 Standard a convention has been adopted to assist the reader of the Standard.

Capital letters are used to refer to a specific control function, mode, mode setting, or graphic character in order to avoid confusion, for example, between the concept “space”, and the character SPACE.

As is intended by the ECMA-48 Standard, this convention and all acronyms of modes, and control functions are retained in this library, where rust permits.

A character from the ASCII table is represented in the form xx/yy, where xx represents the column number 00 to 07 in a 7-bit code table, and yy represents the row number 00 to 15.

§Parsing ansi-control-codes

The module parser contains a parser that can be used to parse strings and extract any ansi-control-codes that are present within. To use the parser module, enable the feature parser.

cargo add ansi-control-codes --features parser

Refer to the parser’s module documentation for more details.

§Explaining ansi-control-codes

The module explain contains additional functionality to explain ansi-control-codes. Enable this module to get the additional functions short_name, long_name, short_description, long_description to inspect and explain control functions.

cargo add ansi-control-codes --features explain

Refer to the explain’s module documentation for more details.

§Low-Level Control Functions

The control functions of this library are sorted into several modules. You will find the low-level control functions in the modules c0, c1, control_sequences, independent_control_functions

The control functions can be put into normal strings. For example, to ring the bell:

use ansi_control_codes::c0::BEL;
println!("Let's ring the bell {}", BEL);

Or to move the cursor to line 5, column 13:

use ansi_control_codes::control_sequences::CUP;
print!("{}", CUP(5.into(), 13.into()));

It might be necessary in some circumstances to announce the active set of control sequences before they can be used. This is possible by invoking one of the announcer sequences.

use ansi_control_codes::c1::{ANNOUNCER_SEQUENCE, NEL};
// announce the C1 control function set, then move to the next line.
print!("{}{}", ANNOUNCER_SEQUENCE, NEL);

§Categories of control functions

Most control functions are categorized into different groups. They can be accessed from the module categories.

use ansi_control_codes::categories::format_effectors::{CR, LF};
println!("line1{}{}line2", CR, LF);

§High-Level Functions

For your convenience and ease-of-use of the ansi control codes, some functionality is exposed in wrapper functions. See the following module documentations for a more in-depth introduction to these functions.

§Source Material

The second, and newer, editions of the ECMA-48 Standard are based on the text of the ISO 6429 Standard and are technically identical with it. Since the ISO 6429 Standard is not freely available on the internet, this implementation is based on the publicly available documents of the ECMA-48 Standard. In particular on edition 5 of the ECMA-48 Standard, which is identical to the third edition of ISO-6429.

The ANSI X3.64 Standard has been withdrawn by ANSI in 1994 in favour of the international standard.

You can read more about the history of the standards on Wikipedia: ANSI escape code.

Modules§

c0
Elements of the C0 set.
c1
Elements of the C1 set.
categories
This module re-exports categories of control functions.
control_sequences
Control Sequences.
control_strings
Control Strings.
explain
Explanations of ansi-control-codes
independent_control_functions
Independent Control Functions.
modes
Modes.
parser
Parser for ansi-control-codes

Structs§

ControlFunction
An ansi control function defined in ECMA-48.

Enums§

InvalidControlFunction
Possible errors when specifying a custom control function.