fzechert/ansi-control-codes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Activity

Compare commits

base: fzechert:04e6baf31d636d3d46d8f50c23d8c61f95e90322
Branches Tags
fzechert:master
fzechert:v0.0.2
fzechert:v0.0.1
...
compare: fzechert:138e15c763d75e470c6eca9e26776914af5be049
Branches Tags
fzechert:master
fzechert:v0.0.2
fzechert:v0.0.1

10 Commits
04e6baf31d ... 138e15c763

Author SHA1 Message Date
Frank Zechert
138e15c763 adds git repository to Cargo.toml 2023-04-01 04:36:02 +02:00
Frank Zechert
ad9146075b implements From<ControlFunction> for String 2023-04-01 04:33:45 +02:00
Frank Zechert
59bdca5c50 improves the documentation of module independent_control_functions 2023-04-01 03:57:07 +02:00
Frank Zechert
6e503b96c8 improves documentation in module control_sequences 2023-04-01 03:52:18 +02:00
Frank Zechert
dceb34a9a9 improves documentation in module c1 2023-04-01 02:41:25 +02:00
Frank Zechert
4e4052b74c improves documentation in module c0 2023-04-01 02:15:30 +02:00
Frank Zechert
f297692e64 adds tests to lib.rs 2023-04-01 01:48:15 +02:00
Frank Zechert
30906d2075 adds default traits to ControlFunctionType 2023-04-01 01:48:15 +02:00
Frank Zechert
ef555cbe05 adds more documentation to lib.rs 2023-04-01 01:48:15 +02:00
Frank Zechert
52a2be9a1a implements Debug for ControlFunction 2023-04-01 01:48:07 +02:00
6 changed files with 622 additions and 340 deletions
Show Stats Expand all files Collapse all files

2
Cargo.toml
View File

@ -5,7 +5,7 @@ version = "0.1.0"
edition = "2021"
authors = ["Frank Zechert <rust.frank@zechert.net>"]
repository = ""
repository = "https://git.zechert.net/fzechert/ansi.git"
license = "MIT"
# crates.io

136
src/c0.rs
View File

@ -5,9 +5,21 @@
//! The 3-character escape sequence designating and invoking this C0 set is `ESC 02/01 04/00`,
//! see [`ANNOUNCER_SEQUENCE`].
//!
//! It is assumed that even with no invoked C0 set, the control character `ESCAPE` (`ESC`) is always available, and is
//! It is assumed that even with no invoked C0 set, the control character `ESCAPE` ([`ESC`]) is always available, and is
//! represented by bit combination `01/00`.
//!
//! ## Usage
//!
//! You can use the Elements of the C0 set inside normal strings, format them with the `format!()` macro, or print
//! them with the `print!()` and `println!()` macros.
//!
//! For example, designate the C0 set, then ring the bell.
//!
//! ```
//! use ansi::c0::{ANNOUNCER_SEQUENCE, BEL};
//! println!("{}{}", ANNOUNCER_SEQUENCE, BEL);
//! ```
//!
//! ## Overview of the C0 Set
//!
//! | Row Number | Column `00` | Column `01` |
@ -36,7 +48,7 @@ macro_rules! c0 {
};
}
/// Announcer Sequence for C0.
/// Announcer Sequence for Control Set C0.
///
/// Designate the C0 set of control functions as the active set of control functions.
///
@ -46,7 +58,7 @@ macro_rules! c0 {
///
/// ## Note 2
///
/// It is assumed that even with no invoked C0 set, the control character `ESCAPE` (`ESC`) is available, and is
/// It is assumed that even with no invoked C0 set, the control character ESCAPE (`ESC`) is available, and is
/// represented by the bit combination `01/11`.
pub const ANNOUNCER_SEQUENCE: &'static str = ascii!(01 / 11, 02 / 01, 04 / 00);
@ -54,7 +66,9 @@ pub const ANNOUNCER_SEQUENCE: &'static str = ascii!(01 / 11, 02 / 01, 04 / 00);
///
/// `ACK` is transmitted by a receiver as an affirmative response to the sender.
///
/// The use of `ACK` is defined in ISO 1745.
/// The use of `ACK` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const ACK: ControlFunction = c0!(00 / 06);
/// Bell.
@ -68,7 +82,7 @@ pub const BEL: ControlFunction = c0!(00 / 07);
/// opposite to that of the implicit movement.
///
/// The direction of the implicit movement depends on the parameter value of Select Implicit Movement Direction
/// (`SIMD`).
/// ([`SIMD`][crate::control_sequences::SIMD]).
pub const BS: ControlFunction = c0!(00 / 08);
/// Cancel.
@ -80,24 +94,30 @@ pub const CAN: ControlFunction = c0!(01 / 08);
/// Carriage Return.
///
/// The effect of `CR` depends on the setting of the DEVICE COMPONENT SELECT MODE (`DCSM`) and on the parameter value of
/// SELECT IMPLICIT MOVEMENT DIRECTION (`SIMD`).
/// The effect of `CR` depends on the setting of the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) and
/// on the parameter value of SELECT IMPLICIT MOVEMENT DIRECTION ([`SIMD`][crate::control_sequences::SIMD]).
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION and with the parameter value of `SIMD` equal to
/// `0`, `CR` causes the active presentation position to be moved to the line home position of the same line in the
/// presentation component. The line home position is established by the parameter value of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION and with the parameter
/// value of [`SIMD`][crate::control_sequences::SIMD] equal to
/// [`Normal`][crate::control_sequences::MovementDirection::Normal], `CR` causes the active presentation position to be
/// moved to the line home position of the same line in the presentation component. The line home position is
/// established by the parameter value of SET LINE HOME ([`SLH`][crate::control_sequences::SLH]).
///
/// With a parameter value of `SIMD` equal to `1`, `CR` causes the active presentation position to be moved to the line
/// limit position of the same line in the presentation component. The line limit position is established by the
/// parameter value of SET LINE LIMIT (`SSL`).
/// With a parameter value of [`SIMD`][crate::control_sequences::SIMD] equal to
/// [`Opposite`][crate::control_sequences::MovementDirection::Opposite], `CR` causes the active presentation position to
/// be moved to the line limit position of the same line in the presentation component. The line limit position is
/// established by the parameter value of SET LINE LIMIT ([`SLL`][crate::control_sequences::SLL]).
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA and with a parameter of `SIMD` equal to `0`, `CR` causes
/// the active data position to be moved to the line home position of the same line in the data component. The line home
/// position is established by the parameter value of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA and with a parameter of
/// [`SIMD`][crate::control_sequences::SIMD] equal to [`Normal`][crate::control_sequences::MovementDirection::Normal],
/// `CR` causes the active data position to be moved to the line home position of the same line in the data component.
/// The line home position is established by the parameter value of SET LINE HOME
/// ([`SLH`][crate::control_sequences::SLH]).
///
/// With a parameter value of `SIMD` equal to `1`, `CR` causes the active data position to be moved to the line limit
/// position of the same line in the data component. The line limit position is established by the parameter value of
/// SET LINE LIMIT (`SSL`).
/// With a parameter value of [`SIMD`][crate::control_sequences::SIMD] equal to
/// [`Opposite`][crate::control_sequences::MovementDirection::Opposite], `CR` causes the active data position to be
/// moved to the line limit position of the same line in the data component. The line limit position is established by
/// the parameter value of SET LINE LIMIT ([`SLL`][crate::control_sequences::SLL]).
pub const CR: ControlFunction = c0!(00 / 13);
/// Device Control One.
@ -135,7 +155,9 @@ pub const DC4: ControlFunction = c0!(01 / 04);
///
/// `DLE` is used exclusively to provide supplementary transmission control functions.
///
/// The use of `DLE` is defined in ISO 1745.
/// The use of `DLE` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const DLE: ControlFunction = c0!(01 / 00);
/// End Of Medium.
@ -148,14 +170,18 @@ pub const EM: ControlFunction = c0!(01 / 09);
///
/// `ENQ` is transmitted by a sender as a request for a response from a receiver.
///
/// The use of `EOT` is defined in ISO 1745.
/// The use of `ENQ` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const ENQ: ControlFunction = c0!(00 / 05);
/// End Of Transmission.
///
/// `EOT` is used to indicate the conclusion of the transmission of one or more texts.
///
/// The use of `EOT` is defined in ISO 1745.
/// The use of `EOT` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const EOT: ControlFunction = c0!(00 / 04);
/// Escape.
@ -163,7 +189,9 @@ pub const EOT: ControlFunction = c0!(00 / 04);
/// `ESC` is used for code extension purposes. It causes the meanings of a limited number of bit combinations following
/// it in the data stream to be changed.
///
/// The use of `ESC` is defined in Standard ECMA-35.
/// The use of `ESC` is defined in Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const ESC: ControlFunction = c0!(01 / 11);
/// End Of Transmission Block.
@ -171,21 +199,25 @@ pub const ESC: ControlFunction = c0!(01 / 11);
/// `ETB` is used to indicate the end of a block of data where the data are divided into such blocks for transmission
/// purposes.
///
/// The use of `ETB` is defined in ISO 1745.
/// The use of `ETB` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const ETB: ControlFunction = c0!(01 / 07);
/// End Of Text.
///
/// `ETX` is used to indicate the end of a text.
///
/// The use of `ETX` is defined in ISO 1745.
/// The use of `ETX` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const ETX: ControlFunction = c0!(00 / 03);
/// Form Feed.
///
/// `FF` causes the active presentation position to be moved to the corresponding character position of the line at the
/// page home position of the next form or page in the presentation component. The page home position is established by
/// the parameter value of SET PAGE HOME (`SPH`).
/// the parameter value of SET PAGE HOME ([`SPH`][crate::control_sequences::SPH]).
pub const FF: ControlFunction = c0!(00 / 12);
/// Character Tabulation.
@ -193,11 +225,12 @@ pub const FF: ControlFunction = c0!(00 / 12);
/// `HT` causes the active presentation position to be moved to the following character tabulation stop in the
/// presentation component.
///
/// In addition, if that following character tabulation stop has been set by TABULATION ALIGN CENTRE (`TAC`), TABULATION
/// ALIGN LEADING EDGE (`TALE`), TABULATION ALIGN TRAILING EDGE (`TATE`) or TABULATION CENTERED ON CHARACTER (`TCC`),
/// `HT` indicates the beginning of a string of text which is to be positioned within a line according to the properties
/// of that tabulation stop. The end of the string is indicated by the next occurrence of `HT` or CARRIAGE RETURN
/// ([`CR`]) or NEXT LINE ([`NEL`][crate::c1::NEL]) in the data stream.
/// In addition, if that following character tabulation stop has been set by TABULATION ALIGN CENTRE
/// ([`TAC`][crate::control_sequences::TAC]), TABULATION ALIGN LEADING EDGE ([`TALE`][crate::control_sequences::TALE]),
/// TABULATION ALIGN TRAILING EDGE ([`TATE`][crate::control_sequences::TATE]) or TABULATION CENTRED ON CHARACTER
/// ([`TCC`][crate::control_sequences::TCC]), `HT` indicates the beginning of a string of text which is to be positioned
/// within a line according to the properties of that tabulation stop. The end of the string is indicated by the next
/// occurrence of `HT` or CARRIAGE RETURN ([`CR`]) or NEXT LINE ([`NEL`][crate::c1::NEL]) in the data stream.
pub const HT: ControlFunction = c0!(00 / 09);
/// Information Separator One (US - Unit Separator).
@ -226,11 +259,12 @@ pub const IS4: ControlFunction = c0!(01 / 12);
/// Line Feed.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `LF` causes the active presentation position
/// to be moved to the corresponding character position of the following line in the presentation component.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `LF` causes the active
/// presentation position to be moved to the corresponding character position of the following line in the presentation
/// component.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `LF` causes the active data position to be moved to the
/// corresponding character position of the following line in the data component.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `LF` causes the active data
/// position to be moved to the corresponding character position of the following line in the data component.
pub const LF: ControlFunction = c0!(00 / 10);
/// Locking-Shift Zero.
@ -250,18 +284,22 @@ pub const LS0: ControlFunction = c0!(00 / 15);
/// `LS1` is used for code extension purposes. It causes the meanings of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `LS1` is defined in Standard ECMA-35.
/// The use of `LS1` is defined in Standard [ECMA-35][ecma-35].
///
/// ## Note
///
/// `LS1` is used in 8-bit environments only; in 7-bit environments SHIFT-OUT ([`SO`]) is used instead.
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const LS1: ControlFunction = c0!(00 / 14);
/// Negative Acknowledge.
///
/// `NAK` is transmitted by a receiver as a negative response to the sender.
///
/// The use of `NAK` is defined in ISO 1745.
/// The use of `NAK` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const NAK: ControlFunction = c0!(01 / 05);
/// Null.
@ -276,11 +314,13 @@ pub const NUL: ControlFunction = c0!(00 / 00);
/// `SI` is used for code extension purposes. It causes the meanings of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `SI` is defined in Standard ECMA-35.
/// The use of `SI` is defined in Standard [ECMA-35][ecma-35].
///
/// ## Note
///
/// `SI` is used in 7-bit environments only; in 8-bit environments LOCKING-SHIFT ZERO (`LS0`) is used instead.
/// `SI` is used in 7-bit environments only; in 8-bit environments LOCKING-SHIFT ZERO ([`LS0`]) is used instead.
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const SI: ControlFunction = c0!(00 / 15);
/// Shift-Out.
@ -288,25 +328,31 @@ pub const SI: ControlFunction = c0!(00 / 15);
/// `SO` is used for code extension purposes. It causes the meanings of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `SI` is defined in Standard ECMA-35.
/// The use of `SI` is defined in Standard [ECMA-35][ecma-35].
///
/// ## Note
///
/// `SO` is used in 7-bit environments only; in 8-bit environments LOCKING-SHIFT ONE (`LS1`) is used instead.
/// `SO` is used in 7-bit environments only; in 8-bit environments LOCKING-SHIFT ONE ([`LS1`]) is used instead.
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const SO: ControlFunction = c0!(00 / 14);
/// Start of Heading.
///
/// `SOH` is used to indicate the beginning of a heading.
///
/// The use of `SOH` is defined in ISO 1745.
/// The use of `SOH` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const SOH: ControlFunction = c0!(00 / 01);
/// Start of Text.
///
/// `STX` is used to indicate the beginning of a text and the ned of a heading.
///
/// The use of `STX` is defined in ISO 1745.
/// The use of `STX` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const STX: ControlFunction = c0!(00 / 02);
/// Substitute.
@ -320,7 +366,9 @@ pub const SUB: ControlFunction = c0!(01 / 10);
/// `SYN` is used by a synchronous transmission system in the absence of any other character (idle condition) to provide
/// a signal from which synchronism may be achieved or retained between data terminal equipment.
///
/// The use of `SYN` is defined in ISO 1745.
/// The use of `SYN` is defined in [ISO 1745][iso-1745].
///
/// [iso-1745]: https://www.ecma-international.org/wp-content/uploads/ECMA-16_2nd_edition_june_1973.pdf
pub const SYN: ControlFunction = c0!(01 / 06);
/// Line Tabulation.

131
src/c1.rs
View File

@ -8,6 +8,18 @@
//! The 3-character escape sequence designating and invoking this c1 set is `ESC 02/06 04/00` and `ESC 02/02 F`.
//! see [`ANNOUNCER_SEQUENCE`], and [`ALTERNATIVE_ANNOUNCER_SEQUENCE`].
//!
//! ## Usage
//!
//! You can use the Elements of the C1 set inside normal strings, format them with the `format!()` macro, or print
//! them with the `print!()` and `println!()` macros.
//!
//! For example, designate the C1 set, then set a character tabulation stop.
//!
//! ```
//! use ansi::c1::{ANNOUNCER_SEQUENCE, HTS};
//! println!("{}{}", ANNOUNCER_SEQUENCE, HTS);
//! ```
//!
//! ## Overview of the C1 Set
//!
//! | Row Number | Column `04` | Column `05` |
@ -43,7 +55,7 @@ macro_rules! c1 {
///
/// ## Note
///
/// The use of this escape sequence implies that all control function of this c1 set must be implemented.
/// The use of this escape sequence implies that all control function of this C1 set must be implemented.
pub const ANNOUNCER_SEQUENCE: &'static str = ascii!(01 / 11, 02 / 06, 04 / 00);
/// Alternative Announcer Sequence for C1.
@ -52,14 +64,14 @@ pub const ANNOUNCER_SEQUENCE: &'static str = ascii!(01 / 11, 02 / 06, 04 / 00);
///
/// ## Note
///
/// The use of this escape sequence implies that all control function of this c1 set must be implemented.
/// The use of this escape sequence implies that all control function of this C1 set must be implemented.
pub const ALTERNATIVE_ANNOUNCER_SEQUENCE: &'static str = ascii!(01 / 11, 02 / 02, 04 / 06);
/// Application Program Command.
///
/// `APC` is used as the opening delimiter of a control string for application program use. The command string following
/// may consist of bit combinations in the range `00/08` to `00/13` and `02/00` to `07/14`. The control string is closed
/// by the terminating delimiter String Terminator (`ST`). The interpretation of the command string depends on the
/// by the terminating delimiter String Terminator ([`ST`]). The interpretation of the command string depends on the
/// relevant application program.
pub const APC: ControlFunction = c1!(05 / 15);
@ -88,25 +100,27 @@ pub const CSI: ControlFunction = c1!(05 / 11);
///
/// `DCS` is used as the opening delimiter of a control string for device control use. The command string following may
/// consist of bit combinations in the range `00/08` to `00/13` and `02/00` to `07/14`. The control string is closed by
/// the terminating delimiter STRING TERMINATOR (`ST`).
/// the terminating delimiter STRING TERMINATOR ([`ST`]).
///
/// The command string represents either one or more commands for the receiving device, or one or more status reports
/// from the sending device. The purpose and the format of the command string are specified by the most recent
/// occurrence of IDENTIFY DEVICE CONTROL STRING (`IDCS`), if any, or depend on the sending and/or the receiving device.
/// occurrence of IDENTIFY DEVICE CONTROL STRING ([`IDCS`][crate::control_sequences::IDCS]), if any, or depend on the
/// sending and/or the receiving device.
pub const DCS: ControlFunction = c1!(05 / 00);
/// End Of Guarded Area.
///
/// `EPA` is used to indicate that the active presentation position is the last of a string of character positions in
/// the presentation component, the contents of which are protected against manual alteration, are guarded against
/// transmission or transfer, depending on the setting of GUARDED AREA TRANSFER MODE (`GATM`), and may be protected
/// against erasure, depending on the setting of the ERASURE MODE (`ERM`). The beginning of this string is indicated
/// by START OF GUARDED AREA ([`SPA`]).
/// transmission or transfer, depending on the setting of GUARDED AREA TRANSFER MODE ([`GATM`][crate::modes::GATM]),
/// and may be protected against erasure, depending on the setting of the ERASURE MODE ([`ERM`][crate::modes::ERM]).
/// The beginning of this string is indicated by START OF GUARDED AREA ([`SPA`]).
///
/// ## Note
///
/// The control functions for area definition ([`DAQ`][crate::control_sequences::DAQ], [`EPA`], [`ESA`], [`SPA`],
/// [`SSA`]) should not be used within an `SRS` string or an `SDS` string.
/// [`SSA`]) should not be used within an [`SRS`][crate::control_sequences::SRS] string or an
/// [`SDS`][crate::control_sequences::SDS] string.
pub const EPA: ControlFunction = c1!(05 / 07);
/// End Of Selected Area.
@ -119,7 +133,8 @@ pub const EPA: ControlFunction = c1!(05 / 07);
/// ## Note
///
/// The control functions for area definition ([`DAQ`][crate::control_sequences::DAQ], [`EPA`], [`ESA`], [`SPA`],
/// [`SSA`]) should not be used within an `SRS` string or an `SDS` string.
/// [`SSA`]) should not be used within an [`SRS`][crate::control_sequences::SRS] string or an
/// [`SDS`][crate::control_sequences::SDS] string.
pub const ESA: ControlFunction = c1!(04 / 07);
/// Character Tabulation With Justification.
@ -135,48 +150,54 @@ pub const HTJ: ControlFunction = c1!(04 / 09);
/// `HTS` causes a character tabulation stop to be set at the active presentation position in the presentation
/// component.
///
/// The number of liens affected depends on the setting of the TABULATION STOP MODE (`TSM`).
/// The number of liens affected depends on the setting of the TABULATION STOP MODE ([`TSM`][crate::modes::TSM]).
pub const HTS: ControlFunction = c1!(04 / 08);
/// Message Waiting.
///
/// `MW` is used to set a message waiting indicator in the receiving device. An appropriate acknowledgement to the
/// receipt of `MW` may be given by using DEVICE STATUS REPORT (`DSR`).
/// receipt of `MW` may be given by using DEVICE STATUS REPORT ([`DSR`][crate::control_sequences::DSR]).
pub const MW: ControlFunction = c1!(05 / 05);
/// No Break Here.
///
/// `NBH` is used to indicate a point where a line break shall not occur when text is formatted. `NBH` may occur between
/// two graphic characters either or both of which may be SPACE.
/// two graphic characters either or both of which may be `SPACE`.
pub const NBH: ControlFunction = c1!(04 / 03);
/// Next Line.
///
/// The effect of `NEL` depends on the setting of the DEVICE COMPONENT SELECT MODE (`DCSM`) and on the parameter value
/// of SELECT IMPLICIT MOVEMENT DIRECTION (`SIMD`).
/// The effect of `NEL` depends on the setting of the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) and on
/// the parameter value of SELECT IMPLICIT MOVEMENT DIRECTION ([`SIMD`][crate::control_sequences::SIMD]).
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION and with a parameter value of `SIMD` equal to
/// `0`, `NEL` causes the active presentation position to be moved to the line home position of the following line in
/// the presentation component. The line home position is established by the parameter value of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION and with a parameter value
/// of [`SIMD`][crate::control_sequences::SIMD] equal to
/// [`Normal`][crate::control_sequences::MovementDirection::Normal], `NEL` causes the active presentation position to be
/// moved to the line home position of the following line in the presentation component. The line home position is
/// established by the parameter value of SET LINE HOME ([`SLH`][crate::control_sequences::SLH]).
///
/// With a parameter value of `SIMD` equal to `1`, `NEL` causes the active presentation position to be moved to the line
/// limit position of the following line in the presentation component. The line limit position is established by the
/// parameter value of SET LINE LIMIT (`SLL`).
/// With a parameter value of [`SIMD`][crate::control_sequences::SIMD] equal to
/// [`Opposite`][crate::control_sequences::MovementDirection::Opposite], `NEL` causes the active presentation position
/// to be moved to the line limit position of the following line in the presentation component. The line limit position
/// is established by the parameter value of SET LINE LIMIT ([`SLL`][crate::control_sequences::SLL]).
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA and with a parameter value of `SIMD` equal to `0`, `NEL`
/// causes the active data position to be moved to the line home position of the following line in the data component.
/// The line home position is established by the parameter value of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA and with a parameter value of
/// [`SIMD`][crate::control_sequences::SIMD] equal to [`Normal`][crate::control_sequences::MovementDirection::Normal],
/// `NEL` causes the active data position to be moved to the line home position of the following line in the data
/// component. The line home position is established by the parameter value of SET LINE HOME
/// ([`SLH`][crate::control_sequences::SLH]).
///
/// With a parameter value of `SIMD` equal to `1`, `NEL` causes the active data position to be moved to the line limit
/// position of the following line in the data component. The line limit position is established by the parameter value
/// of SET LINE LIMIT (`SLL`).
/// With a parameter value of [`SIMD`][crate::control_sequences::SIMD] equal to
/// [`Opposite`][crate::control_sequences::MovementDirection::Opposite], `NEL` causes the active data position to be
/// moved to the line limit position of the following line in the data component. The line limit position is established
/// by the parameter value of SET LINE LIMIT ([`SLL`][crate::control_sequences::SLL]).
pub const NEL: ControlFunction = c1!(04 / 05);
/// Operating System Command
///
/// `OSC` is used as the opening delimiter of a control string for operating system use. The command string following
/// may consist of a sequence of bit combinations in the range `00/08` to `00/13` and `02/00` to `07/14`. The control
/// string is closed by the terminating delimiter STRING TERMINATOR (`ST`). The interpretation of the command string
/// string is closed by the terminating delimiter STRING TERMINATOR ([`ST`]). The interpretation of the command string
/// depends on the relevant operating system.
pub const OSC: ControlFunction = c1!(05 / 13);
@ -185,10 +206,10 @@ pub const OSC: ControlFunction = c1!(05 / 13);
/// `PLD` causes the active presentation position to be moved in the presentation component to the corresponding
/// position of an imaginary line with a partial offset in the direction of the line progression. This offset should be
/// sufficient either to image following characters as subscripts until the first following occurrence of PARTIAL LINE
/// BACKWARD (`PLU`) in the data stream, or, if preceding characters were imaged as superscripts, to restore imaging
/// BACKWARD ([`PLU`]) in the data stream, or, if preceding characters were imaged as superscripts, to restore imaging
/// of following characters to the active line (the line that contains the active presentation position).
///
/// Any interactions between `PLD` and format effectors other than `PLU` are not defined.
/// Any interactions between `PLD` and format effectors other than [`PLU`] are not defined.
pub const PLD: ControlFunction = c1!(04 / 11);
/// Partial Line Backwards.
@ -196,18 +217,18 @@ pub const PLD: ControlFunction = c1!(04 / 11);
/// `PLU` causes the active presentation position to be moved in the presentation component to the corresponding
/// position of an imaginary line with a partial offset in the direction opposite to that of the line progression. This
/// offset should be sufficient either to image following characters as superscripts until the first following
/// occurrence of PARTIAL LINE FORWARD (`PLD`) in the data stream, or, if preceding characters were imaged as
/// occurrence of PARTIAL LINE FORWARD ([`PLD`]) in the data stream, or, if preceding characters were imaged as
/// subscripts, to restore imaging of following characters to the active line (the line that contains the active
/// presentation position).
///
/// Any interactions between `PLU` and format effectors other than `PLD` are not defined.
/// Any interactions between `PLU` and format effectors other than [`PLD`] are not defined.
pub const PLU: ControlFunction = c1!(04 / 12);
/// Privacy Message.
///
/// `PM` is used as the opening delimiter of a control string for privacy message use. The command string following may
/// consist of a sequence of bit combinations in the range `00/08` to `00/13` and `02/00` to `07/14`. The control string
/// is closed by the terminating delimiter STRING TERMINATOR (`ST`). The interpretation of the command string depends
/// is closed by the terminating delimiter STRING TERMINATOR ([`ST`]). The interpretation of the command string depends
/// on the relevant privacy discipline.
pub const PM: ControlFunction = c1!(05 / 14);
@ -225,11 +246,12 @@ pub const PU2: ControlFunction = c1!(05 / 02);
/// Reverse Line Feed.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `RI` causes the active presentation position to
/// be moved in the presentation component to the corresponding character position of the preceding line feed.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `RI` causes the active
/// presentation position to be moved in the presentation component to the corresponding character position of the
/// preceding line feed.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `RI` causes the active data position to be moved in the
/// data component to the corresponding character position of the preceding line.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `RI` causes the active data
/// position to be moved in the data component to the corresponding character position of the preceding line.
pub const RI: ControlFunction = c1!(04 / 13);
/// Single Character Introducer.
@ -242,8 +264,8 @@ pub const SCI: ControlFunction = c1!(05 / 10);
/// Start of String.
///
/// `SOS` is used as the opening delimiter of a control string. The character string following may consist of any bit
/// combination, except those representing `SOS` or STRING TERMINATOR (`ST`). The control string is closed by the
/// terminating delimiter STRING TERMINATOR (`ST`). The interpretation of the character string depends on the
/// combination, except those representing `SOS` or STRING TERMINATOR ([`ST`]). The control string is closed by the
/// terminating delimiter STRING TERMINATOR ([`ST`]). The interpretation of the character string depends on the
/// application.
pub const SOS: ControlFunction = c1!(05 / 08);
@ -251,21 +273,22 @@ pub const SOS: ControlFunction = c1!(05 / 08);
///
/// `SPA` is used to indicate that the active presentation position is the first of a string of character positions in
/// the presentation component, the contents of which are protected against manual alteration, are guarded against
/// transmission or transfer, depending on the setting of the GUARDED AREA TRANSFER MODE (`GATM`) and may be protected
/// against erasure, depending on the setting of the ERASURE MODE (`ERM`). The end of this string is indicated by
/// END OF GUARDED AREA (`EPA`).
/// transmission or transfer, depending on the setting of the GUARDED AREA TRANSFER MODE ([`GATM`][crate::modes::GATM])
/// and may be protected against erasure, depending on the setting of the ERASURE MODE ([`ERM`][crate::modes::ERM]).
/// The end of this string is indicated by END OF GUARDED AREA (`EPA`).
///
/// ## Note
///
/// The control functions for area definition (`DAQ`, `EPA`, `ESA`, `SPA`, `SSA`) should not be used within an `SRS`
/// string or an `SDS` string.
/// The control functions for area definition ([`DAQ`][crate::control_sequences::DAQ], [`EPA`], [`ESA`], [`SPA`],
/// [`SSA`]) should not be used within an [`SRS`][crate::control_sequences::SRS] string or an
/// [`SDS`][crate::control_sequences::SDS] string.
pub const SPA: ControlFunction = c1!(05 / 06);
/// Start of Selected Area.
///
/// `SSA` is used to indicate that the active presentation position is the first of a string of character positions in
/// the presentation component, the contents of which are eligible to be transmitted in the form of a data stream or
/// transferred to an auxilliary input/output device.
/// transferred to an auxiliary input/output device.
///
/// The end of this string is indicated by END OF SELECTED AREA ([`ESA`]). The string of characters actually transmitted
/// or transferred depends on the setting of the GUARDED AREA TRANSFER MODE ([`GATM`][crate::modes::GATM]) and on any
@ -274,8 +297,9 @@ pub const SPA: ControlFunction = c1!(05 / 06);
///
/// ## Note
///
/// The control functions for area definition (`DAQ`, `EPA`, `ESA`, `SPA`, `SSA`) should not be used within an `SRS`
/// string or an `SDS` string.
/// The control functions for area definition ([`DAQ`][crate::control_sequences::DAQ], [`EPA`], [`ESA`], [`SPA`],
/// [`SSA`]) should not be used within an [`SRS`][crate::control_sequences::SRS] string or an
/// [`SDS`][crate::control_sequences::SDS] string.
pub const SSA: ControlFunction = c1!(04 / 06);
/// Single-Shift Two.
@ -283,7 +307,9 @@ pub const SSA: ControlFunction = c1!(04 / 06);
/// `SS2` is used for code extension purposes. It causes the meanings of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `SS2` is defined in Standard ECMA-35.
/// The use of `SS2` is defined in Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const SS2: ControlFunction = c1!(04 / 14);
/// Single-Shift Three.
@ -291,13 +317,16 @@ pub const SS2: ControlFunction = c1!(04 / 14);
/// `SS3` is used for code extension purposes. It causes the meanings of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `SS3` is defined in Standard ECMA-35.
/// The use of `SS3` is defined in Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const SS3: ControlFunction = c1!(04 / 15);
/// String Terminator.
///
/// `ST` is used as the closing delimiter of a control string opened by APPLICATION PROGRAM COMMAND (`APC`), DEVICE
/// CONTROL STRING (`DCS`), OPERATING SYSTEM COMMAND (`OSC`), PRIVACY MESSAGE (`PM`), or START OF STRING (`SOS`).
/// `ST` is used as the closing delimiter of a control string opened by APPLICATION PROGRAM COMMAND ([`APC`]), DEVICE
/// CONTROL STRING ([`DCS`]), OPERATING SYSTEM COMMAND ([`OSC`]), PRIVACY MESSAGE ([`PM`]), or START OF STRING
/// ([`SOS`]).
pub const ST: ControlFunction = c1!(05 / 12);
/// Set Transmit State.

484
src/control_sequences.rs
View File

@ -5,6 +5,18 @@
//! combinations identifying the control function. The control function `CSI` itself is an element of the
//! [C1][crate::c1] set.
//!
//! ## Usage
//!
//! You can use the control sequences inside normal strings, format them with the `format!()` macro, or print
//! them with the `print!()` and `println!()` macros.
//!
//! For example, move the cursor to line 5, character 13:
//!
//! ```
//! use ansi::control_sequences::CUP;
//! print!("{}", CUP(Some(5), Some(13)));
//! ```
//!
//! ## Overview of the Control Sequences
//!
//! ### Without Intermediate Bytes
@ -12,7 +24,7 @@
//! | Row Number | Column `04` | Column `05` | Column `06` |
//! | ---------: | :---------: | :---------: | :---------: |
//! | `00` | [`ICH`] | [`DCH`] | [`HPA`] |
//! | `01` | [`CUU`] | [`SSE`] | [`HPR`] |
//! | `01` | [`CUU`] | [`SEE`] | [`HPR`] |
//! | `02` | [`CUD`] | [`CPR`] | [`REP`] |
//! | `03` | [`CUF`] | [`SU`] | [`DA`] |
//! | `04` | [`CUB`] | [`SD`] | [`VPA`] |
@ -193,15 +205,15 @@ pub fn CPL(n: Option<u32>) -> ControlFunction {
/// Active Position Report.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `CPR` is used to report the active presentation
/// position of the sending device as residing in the presentation component at the `n`-th line position according to
/// the line progression and at the `m`-th character position according to the character path.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `CPR` is used to report
/// the active presentation position of the sending device as residing in the presentation component at the `n`-th line
/// position according to the line progression and at the `m`-th character position according to the character path.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `CPR` is used to report the active data position of the
/// sending device as residing in the data component at the `n`-th line position according to the line progression and
/// at the `m`-th character position according to the character progression.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `CPR` is used to report the
/// active data position of the sending device as residing in the data component at the `n`-th line position according
/// to the line progression and at the `m`-th character position according to the character progression.
///
/// `CPR` may be solicited by a DEVICE STATUS REPORT (`DSR`) or be sent unsolicited.
/// `CPR` may be solicited by a DEVICE STATUS REPORT ([`DSR`]) or be sent unsolicited.
///
/// Default value for `n` and `m` is `1`.
pub fn CPR(n: Option<u32>, m: Option<u32>) -> ControlFunction {
@ -382,9 +394,9 @@ pub enum AreaQualification {
/// position of a qualified area. The last character position of the qualified area is the character position in the
/// presentation component immediately preceding the first character position of the following qualified area.
///
/// The control function operates independently of the setting of the TABULATION STOP MODE (`TSM`). The character
/// tabulation stop set by parameter value [`AreaQualification::SetCharacterTabulationStop`] applies to the active line
/// only.
/// The control function operates independently of the setting of the TABULATION STOP MODE ([`TSM`][crate::modes::TSM]).
/// The character tabulation stop set by parameter value [`AreaQualification::SetCharacterTabulationStop`] applies to
/// the active line only.
///
/// The default value for `s` is [`AreaQualification::UnprotectedUnguarded].
///
@ -398,22 +410,23 @@ pub fn DAQ(s: Option<AreaQualification>) -> ControlFunction {
/// Delete Character.
///
/// If the DEVICE COMPONENT SELECT MODE (`DSCM`) is set to PRESENTATION, `DCH` causes the contents of the active
/// presentation position and, depending on the setting of the CHARACTER EDITING MODE (`HEM`), the contents of the `n-1`
/// preceding or following character positions to be removed from the presentation component. The resulting gap is
/// closed by shifting the contents of the adjacent character positions towards the active presentation position. At the
/// other end of the shifted part, `n` character positions are put into the erased state.
/// If the DEVICE COMPONENT SELECT MODE ([`DSCM`][crate::modes::DCSM]) is set to PRESENTATION, `DCH` causes the contents
/// of the active presentation position and, depending on the setting of the CHARACTER EDITING MODE
/// ([`HEM`][crate::modes::HEM]), the contents of the `n-1` preceding or following character positions to be removed
/// from the presentation component. The resulting gap is closed by shifting the contents of the adjacent character
/// positions towards the active presentation position. At the other end of the shifted part, `n` character positions
/// are put into the erased state.
///
/// The extent of the shifted part is established by SELECT EDITING EXTEND (`SEE`).
/// The extent of the shifted part is established by SELECT EDITING EXTEND ([`SEE`]).
///
/// The effect of `CDH` on the start or end of a selected area, the start or end of a qualified area, or a tabulation
/// The effect of `DCH` on the start or end of a selected area, the start or end of a qualified area, or a tabulation
/// stop in the shifted part is undefined.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `DCH` causes the contents of the active data position
/// and, depending on the setting of the CHARACTER EDITING MODE (`HEM`), the contents of the `n-1` preceding or
/// following character positions to be removed from the data component. The resulting gap is closed by shifting the
/// contents of the adjacent character positions towards the active data position. At the other end of the shifted part,
/// `n` character positions are put into the erased state.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `DCH` causes the contents of the
/// active data position and, depending on the setting of the CHARACTER EDITING MODE ([`HEM`][crate::modes::HEM]), the
/// contents of the `n-1` preceding or following character positions to be removed from the data component. The
/// resulting gap is closed by shifting the contents of the adjacent character positions towards the active data
/// position. At the other end of the shifted part, `n` character positions are put into the erased state.
///
/// Default value for `n` is `1`.
pub fn DCH(n: Option<u32>) -> ControlFunction {
@ -422,27 +435,29 @@ pub fn DCH(n: Option<u32>) -> ControlFunction {
/// Delete Line.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `DL` causes the contents of the active line
/// (the line that contains the active presentation position) and, depending on the setting of the LINE EDITING MODE
/// (`VEM`), the contents of the `n-1` preceding or following lines to be removed from the presentation component. The
/// resulting gap is closed by shifting the contents of a number of adjacent lines towards the active line. At the other
/// end of the shifted part, `n` lines are put into the erased state.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `DL` causes the contents
/// of the active line (the line that contains the active presentation position) and, depending on the setting of the
/// LINE EDITING MODE ([`VEM`][crate::modes::VEM]), the contents of the `n-1` preceding or following lines to be removed
/// from the presentation component. The resulting gap is closed by shifting the contents of a number of adjacent lines
/// towards the active line. At the other end of the shifted part, `n` lines are put into the erased state.
///
/// The active presentation position is moved to the line home position in the active line. The line home position is
/// established by the parameter value of SET LINE HOME (`SLH`). If the TABULATION STOP MODE (`TSM`) is set to SINGLE,
/// character tabulation stops are cleared in the lines that are put into the erased state.
/// established by the parameter value of SET LINE HOME ([`SLH`]). If the TABULATION STOP MODE
/// ([`TSM`][crate::modes::TSM]) is set to SINGLE, character tabulation stops are cleared in the lines that are put into
/// the erased state.
///
/// The extent of the shifted part is established by SELECT EDITING EXTEND (`SEE`).
/// The extent of the shifted part is established by SELECT EDITING EXTEND ([`SEE`]).
///
/// Any occurrences of the start or end of a selected area, the start or end of a qualified area, or a tabulation stop
/// in the shifted part, are also shifted.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `DL` causes the contents of the active line (the line
/// that contains the active data position) and, depending on the setting of the LINE EDITING MODE (`VEM`), the contents
/// of the `n-1` preceding or following lines to be removed from the data component. The resulting gap is closed by
/// shifting the contents of a number of adjacent lines towards the active line. At the other end of the shifted part,
/// `n` lines are put into the erased state. The active data position is moved to the lines home position in the active
/// line. The line home position is established by the parameter value of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `DL` causes the contents of the
/// active line (the line that contains the active data position) and, depending on the setting of the LINE EDITING MODE
/// ([`VEM`][crate::modes::VEM]), the contents of the `n-1` preceding or following lines to be removed from the data
/// component. The resulting gap is closed by shifting the contents of a number of adjacent lines towards the active
/// line. At the other end of the shifted part, `n` lines are put into the erased state. The active data position is
/// moved to the lines home position in the active line. The line home position is established by the parameter value of
/// SET LINE HOME ([`SLH`]).
///
/// The default value for `n` is `1`.
pub fn DL(n: Option<u32>) -> ControlFunction {
@ -456,23 +471,23 @@ pub enum DeviceStatusReport {
#[default]
Ready = 0,
/// The device is busy, another `DSR` must be requested later.
/// The device is busy, another [`DSR`] must be requested later.
BusyRepeat,
/// The device is busy, another `DSR` will be sent later.
/// The device is busy, another [`DSR`] will be sent later.
BusyLater,
/// Some malfunction detected, another `DSR` must be requested later.
/// Some malfunction detected, another [`DSR`] must be requested later.
MalfunctionRepeat,
/// Some malfunction detected, another `DSR` will be sent later.
/// Some malfunction detected, another [`DSR`] will be sent later.
MalfunctionLater,
/// A device status report is requested.
RequestDeviceStatusReport,
/// A report of the active presentation position or of the active data position in the form of ACTIVE POSITION
/// REPORT (`CPR`) is requested.
/// REPORT ([`CPR`]) is requested.
RequestActivePositionReport,
}
@ -523,16 +538,16 @@ pub enum EraseArea {
/// Erase in Area.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `EA` causes some or all character positions in
/// the active qualified area (the qualified area in the presentation component which contains the active presentation
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `EA` causes some or all
/// character positions in the active qualified area (the qualified area in the presentation component which contains
/// the active presentation position) to be put into the erased state, depending on the parameter value.
///
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `EA` causes some or all character
/// positions in the active qualified area (the qualified area in the data component which contains the active data
/// position) to be put into the erased state, depending ont he parameter value.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `EA` causes some or all character positions in the
/// active qualified area (the qualified area in the data component which contains the active data position) to be put
/// into the erased state, depending ont he parameter value.
///
/// Whether the character positions of protected areas are put into the erased state, or the character positions of
/// unprotected areas only, depends on the setting of ERASURE MODE (`ERM`).
/// unprotected areas only, depends on the setting of ERASURE MODE ([`ERM`][crate::modes::ERM]).
///
/// The default value of `s` is [`EraseArea::ActivePositionToEnd`].
pub fn EA(s: Option<EraseArea>) -> ControlFunction {
@ -541,14 +556,15 @@ pub fn EA(s: Option<EraseArea>) -> ControlFunction {
/// Erase Character.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `ECH` causes the active presentation position
/// and the `n-1` following character positions in the presentation component to be put into the erased state.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `ECH` causes the active
/// presentation position and the `n-1` following character positions in the presentation component to be put into the
/// erased state.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `ECH` causes the active data position and the `n-1`
/// following character positions in the data component to be put into the erased state.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `ECH` causes the active data
/// position and the `n-1` following character positions in the data component to be put into the erased state.
///
/// Whether the character positions of protected areas are put into the erased state, or the character positions of
/// unprotected areas only, depends on the setting of the ERASURE MODE (`ERM`).
/// unprotected areas only, depends on the setting of the ERASURE MODE ([`ERM`][crate::modes::ERM]).
///
/// The default value for `n` is `1´.
pub fn ECH(n: Option<u32>) -> ControlFunction {
@ -571,16 +587,16 @@ pub enum ErasePage {
/// Erase In Page.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `ED` causes some or all character positions
/// of the active page (the page which contains the active presentation position in the presentation component) to be
/// put into the erased state, depending on the parameter value.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `ED` causes some or all
/// character positions of the active page (the page which contains the active presentation position in the presentation
/// component) to be/ put into the erased state, depending on the parameter value.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `ED` causes some or all character positions of the
/// active page (the page which contains the active data position in the data component) to be put into the erased
/// state, depending on the parameter value.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `ED` causes some or all character
/// positions of the active page (the page which contains the active data position in the data component) to be put into
/// the erased state, depending on the parameter value.
///
/// Whether the character positions of protected areas are put into the erased state, or the character positions of
/// unprotected areas only, depends on the setting of the ERASURE MODE (`ERM`).
/// unprotected areas only, depends on the setting of the ERASURE MODE ([`ERM`][crate::modes::ERM]).
///
/// The default value of `s` is [`ErasePage::ActivePositionToEnd`].
pub fn ED(s: Option<ErasePage>) -> ControlFunction {
@ -603,16 +619,16 @@ pub enum EraseField {
/// Erase In Field.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `EF` causes some or all character positions of
/// the active field (the field which contains the active presentation position in the presentatio component) to be put
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `EF` causes some or all
/// character positions of the active field (the field which contains the active presentation position in the
/// presentation component) to be put into the erased state, depending on the parameter value.
///
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `EF` causes some or all character
/// positions of the active field (the field which contains the active data position in the data component) to be put
/// into the erased state, depending on the parameter value.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `EF` causes some or all character positions of the
/// active field (the field which contains the active data position in the data component) to be put into the erased
/// state, depending on the parameter value.
///
/// Whether the character positions of protected areas are put into the erased state, or the character positions of
/// unprotected areas only, depends on the setting of the ERASURE MODE (`ERM`).
/// unprotected areas only, depends on the setting of the ERASURE MODE ([`ERM`][crate::modes::ERM]).
///
/// The default value for `s` is [`EraseField::ActivePositionToEnd`].
pub fn EF(s: Option<EraseField>) -> ControlFunction {
@ -635,16 +651,16 @@ pub enum EraseLine {
/// Erase In Line.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `EL` causes some or all character positions of
/// the active line (the line which contains the active presentation position in the presentation component) to be put
/// into the erased state, depending on the parameter value.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `EL` causes some or all
/// character positions of the active line (the line which contains the active presentation position in the presentation
/// component) to be put into the erased state, depending on the parameter value.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `EL` causes some or all character positions of the
/// active line (the line which contains the active data position in the data component) to be put into the erased
/// state, depending on the parameter value.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `EL` causes some or all character
/// positions of the active line (the line which contains the active data position in the data component) to be put into
/// the erased state, depending on the parameter value.
///
/// Whether the character positions of protected areas are put into the erased state, or the character positions of
/// unprotected areas only, depends on the setting of the ERASURE MODE (`ERM`).
/// unprotected areas only, depends on the setting of the ERASURE MODE ([`ERM`][crate::modes::ERM]).
///
/// The default value for `s` is [`EraseLine::ActivePositionToEnd`].
pub fn EL(s: Option<EraseLine>) -> ControlFunction {
@ -696,7 +712,7 @@ pub enum Font {
/// Font Selection.
///
/// `FNT` is used to identify the character font to be selected as primary or alternative font by subsequent occurrences
/// of SELECT GRAPHIC RENDITION (`SGR`) in the data stream.
/// of SELECT GRAPHIC RENDITION ([`SGR`]) in the data stream.
///
/// - `s` specifies the primary or alternative font concerned.
/// - `t` identifies the character font according to a register which is to be established.
@ -745,7 +761,7 @@ pub fn GCC(s: Option<GraphicCharacterCombination>) -> ControlFunction {
/// Graphic Size Modification.
///
/// `GSM` is used to modify for subsequent text the height and / or the width of all primary and alternative fonts
/// identified by FONT SELECT ([`FNT`]) and established by GRAPHIC SIZE SELECTION (`GSS`). The established values
/// identified by FONT SELECT ([`FNT`]) and established by GRAPHIC SIZE SELECTION ([`GSS`]). The established values
/// remain in effect until the next occurrence of `GSM` or [`GSS`] in the data stream.
///
/// - `h` specifies the height as a percentage of the height established by [`GSS`].
@ -759,13 +775,13 @@ pub fn GSM(h: Option<u32>, w: Option<u32>) -> ControlFunction {
/// Graphic Size Selection.
///
/// `GSS` is used to establish for subsequent texts the height and the width of all primary and alternative fonts
/// identified by FONT SELECT (`FNT`). The established values remain in effect until the next occurrence of `GSS` in the
/// identified by FONT SELECT ([`FNT`]). The established values remain in effect until the next occurrence of `GSS` in the
/// data stream.
///
/// - `n` specifies the height, the width is implicitly defined by the height.
///
/// The unit in which the parameter value is expressed is that established by the parameter value of SELECT SIZE UNIT
/// (`SSU`).
/// ([`SSU`]).
pub fn GSS(n: u32) -> ControlFunction {
sequence!(02 / 00, 04/03, numeric n)
}
@ -812,26 +828,27 @@ pub fn HVP(n: Option<u32>, m: Option<u32>) -> ControlFunction {
/// Insert Character.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `ICH` is used to prepare the insertion of `n`
/// characters, by putting into the erased state the active presentation position and, depending on the setting of the
/// CHARACTER EDITING MODE (`HEM`), the `n-1` preceding or following character positions in the presentation component.
/// The previous contents of the active presentation position and an adjacent string of character positions are shifted
/// away from the active presentation position. The contents of `n` character positions at the other end of the shifted
/// part are removed. The active presentation position is moved to the line home position in the active line. The line
/// home position is established by the parameter value of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `ICH` is used to prepare
/// the insertion of `n` characters, by putting into the erased state the active presentation position and, depending on
/// the setting of the CHARACTER EDITING MODE ([`HEM`][crate::modes::HEM]), the `n-1` preceding or following character
/// positions in the presentation component. The previous contents of the active presentation position and an adjacent
/// string of character positions are shifted away from the active presentation position. The contents of `n` character
/// positions at the other end of the shifted part are removed. The active presentation position is moved to the line
/// home position in the active line. The line home position is established by the parameter value of SET LINE HOME
/// ([`SLH`]).
///
/// The extent of the shifted part is established by SELECT EDITING EXTENT (`SEE`).
/// The extent of the shifted part is established by SELECT EDITING EXTENT ([`SEE`]).
///
/// The effect of `ICH` on the start or end of a selected area, the start or end of a qualified area, or a tabulation
/// stop in the shifted part is undefined.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `ICH` is used to prepare the insertion of `n`
/// characters, by putting into the erased state the active data position and, depending on the setting of the
/// CHARACTER EDITING MODE (`HEM`), the `n-1` preceding or following character positions in the data component. The
/// previous contents of the active data position and and adjacent string of character positions are shifted away from
/// the active data position. The contents of `n` character positions at the other end of the shifted part are removed.
/// The active data position is moved to the line home position in the active line. The line home position is
/// established by the parameter value of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `ICH` is used to prepare the
/// insertion of `n` characters, by putting into the erased state the active data position and, depending on the setting
/// of the CHARACTER EDITING MODE ([`HEM`][crate::modes::HEM]), the `n-1` preceding or following character positions in
/// the data component. The previous contents of the active data position and and adjacent string of character positions
/// are shifted away from the active data position. The contents of `n` character positions at the other end of the
/// shifted part are removed. The active data position is moved to the line home position in the active line. The line
/// home position is/ established by the parameter value of SET LINE HOME ([`SLH`]).
///
/// The default value for `n` is `1`.
pub fn ICH(n: Option<u32>) -> ControlFunction {
@ -844,7 +861,9 @@ pub enum IdentifyDeviceControlString {
/// Reserved for use with the DIAGNOSTIC state of the STATUS REPORT TRANSFER MODE.
Diagnostic,
/// Reserved for Dynamically Redefinable Character Sets (`DRCS`) according to Standard ECMA-35.
/// Reserved for Dynamically Redefinable Character Sets according to Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
DynamicallyRedefinableCharacterSet,
/// Private command string.
@ -853,8 +872,9 @@ pub enum IdentifyDeviceControlString {
/// Identify Device Control String.
///
/// `IDCS` is used to specify the purpose and format of the command string of subsequent DEVICE CONTROL STRINGS (`DCS`).
/// The specified purpose and format remain in effect until the next occurrence of `IDCS` in the data stream.
/// `IDCS` is used to specify the purpose and format of the command string of subsequent DEVICE CONTROL STRINGS
/// ([`DCS`][crate::c1::DCS]). The specified purpose and format remain in effect until the next occurrence of `IDCS`
/// in the data stream.
///
/// The format and interpretation of the command string corresponding to the parameter `s` are to be defined in
/// appropriate standards. If this control function is used to identify a private command string, a private parameter
@ -881,28 +901,29 @@ pub fn IGS(n: u32) -> ControlFunction {
/// Insert Line.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to PRESENTATION, `IL` is used to prepare the insertion of `n`
/// lines, by putting into the erased state in the presentation component the active line (the line that contains the
/// active presentation position) and, depending on the setting of the LINE EDITING MODE (`VEM`), the `n-1` preceding
/// or following lines. The previous contents of the active line and of adjacent lines are shifted away from the active
/// line. The contents of `n` lines at the other end of the shifted part are removed. The active presentation position
/// is moved to the line home position in the active line. The line home position is established by the parameter value
/// of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `IL` is used to prepare
/// the insertion of `n` lines, by putting into the erased state in the presentation component the active line
/// (the line that contains the active presentation position) and, depending on the setting of the LINE EDITING MODE
/// ([`VEM`][crate::modes::VEM]), the `n-1` preceding or following lines. The previous contents of the active line and
/// of adjacent lines are shifted away from the active line. The contents of `n` lines at the other end of the shifted
/// part are removed. The active presentation position is moved to the line home position in the active line. The line
/// home position is established by the parameter value of SET LINE HOME ([`SLH`]).
///
/// The extent of the shifted part is established by SELECT EDITING EXTENT (`SEE`).
/// The extent of the shifted part is established by SELECT EDITING EXTENT ([`SEE`]).
///
/// Any occurrence of the start or end of a selected area, the start or end of a qualified area, or a tabulation stop in
/// the shifted part, are also shifted.
///
/// If the TABULATION STOP MODE (`TSM`) is set to SINGLE, character tabulation stops are cleared in the lines that are
/// put into the erased state.
/// If the TABULATION STOP MODE ([`TSM`][crate::modes::TSM]) is set to SINGLE, character tabulation stops are cleared in
/// the lines that are put into the erased state.
///
/// If the DEVICE COMPONENT SELECT MODE (`DCSM`) is set to DATA, `IL` is used to prepare the insertion of `n` lines, by
/// putting into the erased state in the data component the active line (the line that contains the active data
/// position) and, depending on the setting of the LINE EDITING MODE (`VEM`), the `n-1` preceding or following lines.
/// The previous contents of the active line and of adjacent lines are shifted away from the active line. The contents
/// of `n` lines at the other end of the shifted part are removed. The active data position is moved to the line home
/// position in the active line. The line home position is established by the parameter value of SET LINE HOME (`SLH`).
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `IL` is used to prepare the
/// insertion of `n` lines, by putting into the erased state in the data component the active line (the line that
/// contains the active data position) and, depending on the setting of the LINE EDITING MODE
/// ([`VEM`][crate::modes::VEM]), the `n-1` preceding or following lines. The previous contents of the active line and
/// of adjacent lines are shifted away from the active line. The contents of `n` lines at the other end of the shifted
/// part are removed. The active data position is moved to the line home position in the active line. The line home
/// position is established by the parameter value of SET LINE HOME ([`SLH`]).
///
/// The default value for `n` is `1`.
pub fn IL(n: Option<u32>) -> ControlFunction {
@ -948,8 +969,8 @@ pub enum Justification {
///
/// The end of the string to be justified is indicated by the next occurrence of `JFY` in the data stream.
///
/// The line home position is established by the parameter value of SET LINE HOME (`SLH`). The line limit position is
/// established by the parameter value of SET LINE LIMIT (`SLL`).
/// The line home position is established by the parameter value of SET LINE HOME ([`SLH`]). The line limit position is
/// established by the parameter value of SET LINE LIMIT ([`SLL`]).
///
/// The default value of `s` is [`Justification::None`].
pub fn JFY(s: Option<Justification>) -> ControlFunction {
@ -1009,7 +1030,7 @@ pub fn NP(n: Option<u32>) -> ControlFunction {
/// Valid parameter values to the function [`PEC`].
#[derive(Clone, Copy, PartialEq, Eq, Default)]
pub enum PresentationExpandContract {
/// Normal, as specified by `SCS`, `SHS` or `SPI`.
/// Normal, as specified by [`SCS`], [`SHS`] or [`SPI`].
#[default]
Normal = 0,
@ -1024,9 +1045,9 @@ pub enum PresentationExpandContract {
///
/// `PEC` is used to establish the spacing and the extent of the graphic characters for subsequent text. The spacing is
/// specified in the line as multiples of the spacing established by the most recent occurrence of SET CHARACTER SPACING
/// (`SCS`) or of SELECT CHARACTER SPACING (`SHS`) or of SPACING INCREMENT (`SPI`) in the data stream. The extent of the
/// characters is implicitly established by these control functions. The established spacing and the extent remain in
/// effect until the next occurrence of `PEC`, of `SCS`, of `SHS` or of `SPI` in the data stream.
/// ([`SCS`]) or of SELECT CHARACTER SPACING ([`SHS`]) or of SPACING INCREMENT ([`SPI`]) in the data stream. The extent
/// of the characters is implicitly established by these control functions. The established spacing and the extent
/// remain in effect until the next occurrence of `PEC`, of [`SCS`], of [`SHS`] or of [`SPI`] in the data stream.
///
/// The default value for `s` is [`PresentationExpandContract::Normal`].
pub fn PEC(s: Option<PresentationExpandContract>) -> ControlFunction {
@ -1089,12 +1110,12 @@ pub enum PageFormat {
/// Page Format Selection
///
/// `PFS` is used to establish the available area for the imaging of pages of text based on paper size. The pages are
/// introduced by the subsequent occurrence of FORM FEED (`FF`) in the data stream.
/// introduced by the subsequent occurrence of FORM FEED ([`FF`][crate::c0::FF]) in the data stream.
///
/// The established image area remains in effect until the next occurrence of `PFS` in the data stream.
///
/// The page home position is established by the parameter value of SET PAGE HOME (`SPH`), the page limit position is
/// established by the parameter value of SET PAGE LIMIT (`SPL`).
/// The page home position is established by the parameter value of SET PAGE HOME ([`SPH`]), the page limit position is
/// established by the parameter value of SET PAGE LIMIT ([`SPL`]).
///
/// The default value for `s` is [`PageFormat::TallBasicText`].
pub fn PFS(s: Option<PageFormat>) -> ControlFunction {
@ -1182,7 +1203,7 @@ pub enum ParallelText {
/// `PTX` with a parameter value of [`ParallelText::End`] indicates the end of the strings of text intended to be
/// presented in parallel with one another.
///
/// The default value for `s` is [`ParallelText::End]`.
/// The default value for `s` is [`ParallelText::End`].
///
/// ## Note
///
@ -1241,13 +1262,14 @@ pub enum Alignment {
/// according to the layout specified by the parameter value, see [`Alignment`].
///
/// The beginning of the string to be positioned is indicated by the preceding occurrence in the data stream of either
/// `QUAD` or one of the following formator functions: FORM FEED (`FF`), CHARACTER AND LINE POSITION (`HVP`), LINE FEED
/// (`LF`), NEXT LINE (`NEL`), PAGE POSITION ABSOLUTE (`PPA`), PAGE POSITION BACKWARD (`PPB`), PAGE POSITION FORWARD
/// (`PPR`), REVERSE LINE FEED (`RI`), LINE POSITION ABSOLUTE (`VPA`), LINE POSITION BACKWARD (`VPB`), LINE POSITION
/// FORWARD (`VPR`), or LINE TABULATION (`VT`).
/// `QUAD` or one of the following formator functions: FORM FEED ([`FF`][crate::c0::FF]), CHARACTER AND LINE POSITION
/// ([`HVP`]), LINE FEED ([`LF`][crate::c0::LF]), NEXT LINE ([`NEL`][crate::c1::NEL]), PAGE POSITION ABSOLUTE
/// ([`PPA`]), PAGE POSITION BACKWARD ([`PPB`]), PAGE POSITION FORWARD ([`PPR`]), REVERSE LINE FEED
/// ([`RI`][crate::c1::RI]), LINE POSITION ABSOLUTE ([`VPA`]), LINE POSITION BACKWARD ([`VPB`]), LINE POSITION
/// FORWARD ([`VPR`]), or LINE TABULATION ([`VT`][crate::c0::VT]).
///
/// The line home position is established by the parameter value of SET LINE HOME (`SLH`). The line limit position is
/// established by the parameter value of SET LINE LIMIT (`SLL`).
/// The line home position is established by the parameter value of SET LINE HOME ([`SLH`]). The line limit position is
/// established by the parameter value of SET LINE LIMIT ([`SLL`]).
///
/// The default value for `s` is [`Alignment::LineHome`].
pub fn QUAD(s: Option<Alignment>) -> ControlFunction {
@ -1275,14 +1297,14 @@ pub fn RM(v: Vec<Mode>) -> ControlFunction {
/// Set Additional Character Representation.
///
/// `SACS` is used to establish extra inter-character escapement for subsequent text. The established extra escapement
/// remains in effect until the next occurrence of `SACS` or of SET REDUCED CHARACTER SEPARATION (`SRCS`) in the data
/// stream or until it is reset to the default value by a subsequent occurrence of CARRIAGE RETURN LINE FEED (`CR LF`)
/// or of NEXT LINE (`NEL`) in the data stream.
/// remains in effect until the next occurrence of `SACS` or of SET REDUCED CHARACTER SEPARATION ([`SRCS`]) in the data
/// stream or until it is reset to the default value by a subsequent occurrence of CARRIAGE RETURN LINE FEED
/// ([`CR`][crate::c0::CR] [`LF`][crate::c0::LF]) or of NEXT LINE ([`NEL`][crate::c1::NEL]) in the data stream.
///
/// `n` specifies the number of units by which the inter-character escapement is enlarged.
///
/// The unit in which the parameter value is expressed is that established by the parameter value of SELECT SIZE UNIT
/// (`SSU`).
/// ([`SSU`]).
///
/// The default value for `n` is 0.
pub fn SACS(n: Option<u32>) -> ControlFunction {
@ -1292,7 +1314,7 @@ pub fn SACS(n: Option<u32>) -> ControlFunction {
/// Valid parameter values to the function [`SAPV`].
#[derive(Clone, Copy, PartialEq, Eq, Default)]
pub enum PresentationVariant {
/// Default presentation (implementation-defined); cancels the effect of any preceding occurrence of `SAPV` in the
/// Default presentation (implementation-defined); cancels the effect of any preceding occurrence of [`SAPV`] in the
/// data stream.
#[default]
Default = 0,
@ -1364,7 +1386,7 @@ pub enum PresentationVariant {
NoContextualShapeArabicScript,
/// Contextual shape determination of Arabic scripts i not used, the graphic characters - excluding the digits -
/// are presented in the form thye are stored (pass-through).
/// are presented in the form they are stored (pass-through).
NoContextualShapeArabicScriptExceptDigits,
/// The graphic symbols used to present the decimal digits are device dependent.
@ -1451,8 +1473,9 @@ pub enum CharacterPathScope {
///
/// ## Note
///
/// This may also permit the effect to take place after the next occurrence of `CR`, `NEL` or any control function
/// which initiates an absolute movement of the active presentation position or the active data position.
/// This may also permit the effect to take place after the next occurrence of [`CR`][crate::c0::CR],
/// [`NEL`][crate::c1::NEL] or any control function which initiates an absolute movement of the active presentation
/// position or the active data position.
Undefined = 0,
/// The content of the active line in the presentation component (the line that contains the active presentation
@ -1472,7 +1495,7 @@ pub enum CharacterPathScope {
/// Select Character Path.
///
/// `SCP` is used to select the character paht, relative to the line orientation, for the active line (the line that
/// `SCP` is used to select the character path, relative to the line orientation, for the active line (the line that
/// contains the active presentation position) and subsequent lines in the presentation component. It is also used to
/// update the content of the active line in the presentation component and the content of the active line (the line
/// that contains the active data position) in the data component. This takes effect immediately.
@ -1484,13 +1507,13 @@ pub fn SCP(s: CharacterPath, t: CharacterPathScope) -> ControlFunction {
/// Set Character Spacing.
///
/// `SCS` is used to establish the character spacing for subsequent text. The established spacing remains in effect
/// until the next occurrence of `SCS`, or of SELECT CHARACTER SPACING (`SHS`) or of SPACING INCREMENT (`SPI`) in the
/// data stream.
/// until the next occurrence of `SCS`, or of SELECT CHARACTER SPACING ([`SHS`]) or of SPACING INCREMENT ([`SPI`]) in
/// the data stream.
///
/// `n` specifies the character spacing.
///
/// The unit in which the parameter value is expressed is that established by the parameter value of SELECT SIZE UNIT
/// (`SSU`).
/// ([`SSU`]).
pub fn SCS(n: u32) -> ControlFunction {
sequence!(02 / 00, 06 / 07, numeric n)
}
@ -1531,7 +1554,7 @@ pub enum StringDirection {
/// The beginning of a directed string is indicated by `SDS` with a parameter value not equal to
/// [`StringDirection::End`]. A directed string may contain one or more nested strings. These nested strings may be
/// directed strings the beginning of which are indicated by `SDS` with a parameter value not equal to
/// [`StringDirection::End`], or reversed stings the beginning of which are indicated by START REVERSED STRING (`SRS`)
/// [`StringDirection::End`], or reversed stings the beginning of which are indicated by START REVERSED STRING ([`SRS`])
/// with a parameter value of [`ReversedString::Start`]. Every beginning of such a string invokes the next deeper level
/// of nesting.
///
@ -1546,19 +1569,21 @@ pub enum StringDirection {
///
/// ## Note 1
///
/// The effect of receiving a `CVT`, `HT`, `SCP`, `SPD`, or `VT` control function within an `SDS` string is not defined.
/// The effect of receiving a [`CVT`], [`HT`][crate::c0::HT], [`SCP`], [`SPD`], or [`VT`][crate::c0::VT] control
/// function within an `SDS` string is not defined.
///
/// ## Note 2
///
/// The control functions for area definitions (`DAQ, `EPA`, `SPA`, `SSA`) should not be used within an `SDS` string.
/// The control functions for area definitions ([`DAQ`], [`EPA`][crate::c1::EPA], [`SPA`][crate::c1::SPA],
/// [`SSA`][crate::c1::SPA]) should not be used within an `SDS` string.
pub fn SDS(s: Option<StringDirection>) -> ControlFunction {
sequence!(05 / 13, selective default s)
}
/// Valid parameter values to the function [`SSE`].
/// Valid parameter values to the function [`SEE`].
#[derive(Clone, Copy, PartialEq, Eq, Default)]
pub enum EditingExtend {
/// The shifted part is limitied to the active page in the presentation component.
/// The shifted part is limited to the active page in the presentation component.
#[default]
ActivePage = 0,
@ -1582,7 +1607,7 @@ pub enum EditingExtend {
/// depends on the parameter value.
///
/// The default value for `s` is [`EditingExtend::ActivePage`].
pub fn SSE(s: Option<EditingExtend>) -> ControlFunction {
pub fn SEE(s: Option<EditingExtend>) -> ControlFunction {
sequence!(05 / 01, selective default s)
}
@ -1630,8 +1655,8 @@ pub fn SEF(l: Option<Load>, s: Option<Stack>) -> ControlFunction {
/// Valid parameter values to the function [`SGR`].
#[derive(Clone, Copy, PartialEq, Eq, Default)]
pub enum GraphicRendition {
/// Default rendition (implementation-defined), cancels the effect of any preceding occurrence of `SGR` in the data
/// stream regardless of the setting of the GRAPHIC RENDITION COMBINATION MODE (`GRCM`).
/// Default rendition (implementation-defined), cancels the effect of any preceding occurrence of [`SGR`] in the
/// data stream regardless of the setting of the GRAPHIC RENDITION COMBINATION MODE ([`GRCM`][crate::modes::GRCM]).
#[default]
Default = 0,
@ -1805,7 +1830,8 @@ pub enum GraphicRendition {
///
/// `SGR` is used to establish one or more graphic rendition aspects for subsequent text. The established aspects remain
/// in effect until the next occurrence of `SGR` in the data stream, depending on the setting of the GRAPHIC RENDITION
/// COMBINATION MODE (`GRCM`). Each graphic rendition aspect is specified by a parameter value of [`GraphicRendition`].
/// COMBINATION MODE ([`GRCM`][crate::modes::GRCM]). Each graphic rendition aspect is specified by a parameter value of
/// [`GraphicRendition`].
///
/// The default value for `s` is [`GraphicRendition::Default`].
///
@ -1846,8 +1872,8 @@ pub enum CharacterSpacing {
/// Select Character Spacing.
///
/// `SHS` is used to establish the character spacing for subsequent text. The established spacing remains in effect
/// until the next occurrence of `SHS` or of SET CHARACTER SPACING (`SPS`) or of SPACING INCREMENT (`SPI`) in the data
/// stream.
/// until the next occurrence of `SHS` or of SET CHARACTER SPACING ([`SCS`]) or of SPACING INCREMENT ([`SPI`]) in the
/// data stream.
///
/// The default value for `s` is [`CharacterSpacing::TenCharacters`].
pub fn SHS(s: Option<CharacterSpacing>) -> ControlFunction {
@ -1868,7 +1894,7 @@ pub enum MovementDirection {
/// Select Implicit Movement Direction.
///
/// `SIMD` is used to select the direction of implicit movement of the data position relative to the character
/// progression. The direction selected remains in effect until the next occurrence of `SIMD`.
/// progression. The direction selected remains in effect until the next occurrence of [`SIMD`].
///
/// The default value of `s` is [`MovementDirection::Normal`].
pub fn SIMD(s: Option<MovementDirection>) -> ControlFunction {
@ -1890,18 +1916,19 @@ pub fn SL(n: Option<u32>) -> ControlFunction {
/// Set Line Home.
///
/// If the DEVICE COMPONENT SELECT MODE is set to PRESENTATION, `SLH` is used to establish at character position `n` in
/// the active line (the line that contains the active presentation position) and lines of subsequent text in the
/// presentation component the position to which the active presentation position will be moved by subsequent
/// occurrences of CARRIAGE RETURN (`CR`), DELETE LINE (`DL`), INSERT LINE (`IL`) or NEXT LINE (`NEL`) in the data
/// stream. In the case of a device without data component, it is also the position ahead of which no implicit movement
/// of the active presentation position shall occur.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `SLH` is used to
/// establish at character position `n` in the active line (the line that contains the active presentation position) and
/// lines of subsequent text in the presentation component the position to which the active presentation position will
/// be moved by subsequent occurrences of CARRIAGE RETURN ([`CR`][crate::c0::CR]), DELETE LINE ([`DL`]), INSERT LINE
/// ([`IL`]) or NEXT LINE ([`NEL`][crate::c1::NEL]) in the data stream. In the case of a device without data component,
/// it is also the position ahead of which no implicit movement of the active presentation position shall occur.
///
/// If the DEVICE COMPONENT SELECT MODE is set to DATA, `SLH` is used to establish at character position `n` in the
/// active line (the line that contains the active data position) and lines of subsequent text in the data component
/// the position to which the active data position will be moved by subsequent occurrences of CARRIAGE RETURN (`CR`),
/// DELETE LINE (`DL`), INSERT LINE (`IL`) or NEXT LINE (`NEL`) in the data stream. It is also the position ahead of
/// which no implicit movement of the active data position shall occur.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `SLH` is used to establish at
/// character position `n` in the active line (the line that contains the active data position) and lines of subsequent
/// text in the data component the position to which the active data position will be moved by subsequent occurrences of
/// CARRIAGE RETURN ([`CR`][crate::c0::CR]), DELETE LINE ([`DL`]), INSERT LINE ([`IL`]) or NEXT LINE
/// ([`NEL`][crate::c1::NEL]) in the data stream. It is also the position ahead of which no implicit movement of the
/// active data position shall occur.
///
/// The established position is called the line home position and remains in effect until the next occurrence of `SLH`
/// in the data stream.
@ -1911,20 +1938,20 @@ pub fn SLH(n: u32) -> ControlFunction {
/// Set Line Limit.
///
/// If the DEVICE COMPONENT SELECT MODE is set to PRESENTATION, `SLL` is used to establish at character position `n` in
/// the active line (the line that contains the active presentation position) and lines of subsequent text in the
/// presentation component the position to which the active presentation position will be moved by subsequent
/// occurrences of CARRIAGE RETURN (`CR`), or NEXT LINE (`NEL`) in the data stream if the parameter value of SELECT
/// IMPLICIT MOVEMENT DIRECTION (`SIMD`) is equal to [`MovementDirection::Opposite`]. In the case of a device without
/// data component, it is also the position beyond which no implicit movement of the active presentation position shall
/// occur.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `SLL` is used to
/// establish at character position `n` in the active line (the line that contains the active presentation position) and
/// lines of subsequent text in the presentation component the position to which the active presentation position will
/// be moved by subsequent occurrences of CARRIAGE RETURN ([`CR`][crate::c0::CR]), or NEXT LINE
/// ([`NEL`][crate::c1::NEL]) in the data stream if the parameter value of SELECT IMPLICIT MOVEMENT DIRECTION ([`SIMD`])
/// is equal to [`MovementDirection::Opposite`]. In the case of a device without data component, it is also the position
/// beyond which no implicit movement of the active presentation position shall occur.
///
/// If the DEVICE COMPONENT SELECT MODE is set to DATA, `SLL` is used to establish at character position `n` in the
/// active line (the line that contains the active data position) and lines of subsequent text in the data component the
/// position beyond which no implicit movement of the active data position shall occur. It is also the position in the
/// data component to which the active data position will be moved by subsequent occurrences of `CR` or `NEL` in the
/// data stream, if the parameter value of SELECT IMPLICIT MOVEMENT DIRECTION (SIMD) is equal to
/// [`MovementDirection::Opposite`].
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `SLL` is used to establish at
/// character position `n` in the active line (the line that contains the active data position) and lines of subsequent
/// text in the data component the position beyond which no implicit movement of the active data position shall occur.
/// It is also the position in the data component to which the active data position will be moved by subsequent
/// occurrences of [`CR`][crate::c0::CR] or [`NEL`][crate::c1::NEL] in the data stream, if the parameter value of
/// SELECT IMPLICIT MOVEMENT DIRECTION ([`SIMD`]) is equal to [`MovementDirection::Opposite`].
///
/// The established position is called the line limit position and remains in effect until the next occurrence of `SLL`
/// in the data stream.
@ -1935,12 +1962,12 @@ pub fn SLL(n: u32) -> ControlFunction {
/// Set Line Spacing.
///
/// `SLS` is used to establish the line spacing for subsequent text. The established spacing remains in effect until the
/// next occurrence of `SLS` or of SELECT LINE SPACING (`SVS`) or of SPACING INCREMENT (`SPI`) in the data stream.
/// next occurrence of `SLS` or of SELECT LINE SPACING ([`SVS`]) or of SPACING INCREMENT ([`SPI`]) in the data stream.
///
/// `n` specifies the line spacing.
///
/// The unit in which the parameter value is epxressed is that established by the paramaeter value of SELECT SIZE UNIT
/// (`SSU`).
/// The unit in which the parameter value is expressed is that established by the parameter value of SELECT SIZE UNIT
/// ([`SSU`]).
pub fn SLS(n: u32) -> ControlFunction {
sequence!(02 / 00, 06 / 08, numeric n)
}
@ -1988,8 +2015,9 @@ pub enum PresentationDirectionScope {
///
/// ## Note
///
/// This may also permit the effect to take place after the next occurrence of `CR`, `NEL` or any control function
/// which initiates an absolute movement of the active presentation position or the active data position.
/// This may also permit the effect to take place after the next occurrence of [`CR`][crate::c0::CR],
/// [`NEL`][crate::c1::NEL] or any control function which initiates an absolute movement of the active presentation
/// position or the active data position.
#[default]
Undefined = 0,
@ -2026,16 +2054,18 @@ pub fn SPD(
/// Set Page Home.
///
/// If the DEVICE COMPONENT SELECT MODE is set to PRESENTATION, `SPH` is used to establish at line position `n` in the
/// active page (the page that contains the active presentation position) and subsequent pages in the presentation
/// component the position to which the active presentation position will be moved by subsequent occurrences of FORM
/// FEED (`FF`) in the data stream. In the case of a device without data component, it is also the position ahead of
/// which no implicit movement of the active presentation position shall occur.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `SPH` is used to
/// establish at line position `n` in the active page (the page that contains the active presentation position) and
/// subsequent pages in the presentation component the position to which the active presentation position will be moved
/// by subsequent occurrences of FORM FEED ([`FF`][crate::c0::FF]) in the data stream. In the case of a device without
/// data component, it is also the position ahead of which no implicit movement of the active presentation position
/// shall occur.
///
/// If the DEVICE COMPONENT SELECT MODE is set to DATA, `SPH` is used to establish at line position `n´ in the active page
/// (the page that contains the active data position) and subsequent pages in the data component the position to which
/// the active data position will be moved by subsequent occurrences of FORM FEED (`FF`) in the data stream. It is also
/// the position ahead of which no implicit movement of the active presentation position shall occur.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `SPH` is used to establish at
/// line position `n´ in the active page (the page that contains the active data position) and subsequent pages in the
/// data component the position to which the active data position will be moved by subsequent occurrences of FORM FEED
/// ([`FF`][crate::c0::FF]) in the data stream. It is also the position ahead of which no implicit movement of the
/// active presentation position shall occur.
///
/// The established position is called the page home position and remains in effect until the next occurrence of ´SPH`
/// in the data stream.
@ -2046,30 +2076,30 @@ pub fn SPH(n: u32) -> ControlFunction {
/// Spacing Increment.
///
/// `SPI` is used to establish the line spacing and the character spacing for subsequent text. The established line
/// spacing remains in effect until the next occurrence of `SPI` or of SET LINE SPACING (`SLS`) or of SELECT LINE
/// SPACING (`SVS`) in the data stream. The established character spacing remains in effect until the next occurrence
/// of SET CHARACTER SPACING (`SCS`) or of SELECT CHARACTER SPACING (`SHS`) in the data stream.
/// spacing remains in effect until the next occurrence of `SPI` or of SET LINE SPACING ([`SLS`]) or of SELECT LINE
/// SPACING ([`SVS`]) in the data stream. The established character spacing remains in effect until the next occurrence
/// of SET CHARACTER SPACING ([`SCS`]) or of SELECT CHARACTER SPACING ([`SHS`]) in the data stream.
///
/// `l` specifies the line spacing.
/// `c` specifies the character spacing.
///
/// The unit in which the parameter values are expressed is that established by the parameter value of SELECT SIZE UNIT
/// (`SSU`).
/// ([`SSU`]).
pub fn SPI(l: u32, c: u32) -> ControlFunction {
sequence!(02 / 00, 04 / 07, numeric l, numeric c)
}
/// Set Page Limit.
///
/// If the DEVICE COMPONENT SELECT MODE is set to PRESENTATION, `SPL` is used to establish at line position `n` in the
/// active page (the page that contains the active presentation position) and pages of subsequent text in the
/// presentation component the position beyond which the active presentation position can normally not be moved. In the
/// case of a device without data component, it is also the position beyond which no implicit movement of the active
/// presentation position shall occur.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to PRESENTATION, `SPL` is used to
/// establish at line position `n` in the active page (the page that contains the active presentation position) and
/// pages of subsequent text in the presentation component the position beyond which the active presentation position
/// can normally not be moved. In the case of a device without data component, it is also the position beyond which no
/// implicit movement of the active presentation position shall occur.
///
/// If the DEVICE COMPONENT SELECT MODE is set to DATA, `SPL` is used to establish at line position `n` in the active
/// page (the page that contains the active data position) and pages of subsequent text in the data component the
/// position beyond which no implicit movement of the active data position shall occur.
/// If the DEVICE COMPONENT SELECT MODE ([`DCSM`][crate::modes::DCSM]) is set to DATA, `SPL` is used to establish at
/// line position `n` in the active page (the page that contains the active data position) and pages of subsequent text
/// in the data component the position beyond which no implicit movement of the active data position shall occur.
///
/// The established position is called the page limit position and remains in effect until the next occurrence of `SPL`
/// in the data stream.
@ -2118,14 +2148,15 @@ pub fn SR(n: Option<u32>) -> ControlFunction {
/// Set Reduced Character Separation.
///
/// `SRCS` is used to establish reduced inter-character escapement for subsequent text. The established reduced
/// escapement remains in effect until the next occurrence of `SRCS` or of SET ADDITIONAL CHARACTER SEPARATION (`SACS`)
/// in the data stream or until it is reset to the default value by a subsequent occurrence of CARRIAGE RETURN/LINE FEED
/// (`CR/LF`) or of NEXT LINE (`NEL`) in the data stream.
/// escapement remains in effect until the next occurrence of `SRCS` or of SET ADDITIONAL CHARACTER SEPARATION
/// ([`SACS`]) in the data stream or until it is reset to the default value by a subsequent occurrence of
/// CARRIAGE RETURN/LINE FEED ([`CR`][crate::c0::CR]/[`LF`][crate::c0::LF]) or of NEXT LINE ([`NEL`][crate::c1::NEL])
/// in the data stream.
///
/// `n` specifies the number of units by which the inter-character escapement is reduced.
///
/// The unit in which the parameter values are expressed is that established by the parameter value of SELECT SIZE UNIT
/// (`SSU`).
/// ([`SSU`]).
///
/// The default value of `n` is `0`.
pub fn SRCS(n: Option<u32>) -> ControlFunction {
@ -2152,7 +2183,7 @@ pub enum ReversedString {
/// The beginning of a reversed string is indicated by `SRS` with a parameter value of [`ReversedString::Start`].
/// A reversed string may contain one or more nested strings. These nested strings may be reversed strings the
/// beginnings of which are indicated by `SRS` with a parameter value of [`ReversedString::Start`], or directed strings
/// the beginnings of which are indicated by START DIRECTED STRING (`SDS`) with a parameter value not equal to
/// the beginnings of which are indicated by START DIRECTED STRING ([`SDS`]) with a parameter value not equal to
/// [`StringDirection::End`]. Every beginning of such a string invokes the next deeper level of nesting.
///
/// This Standard does not define the location of the active data position within any such nested string.
@ -2166,12 +2197,13 @@ pub enum ReversedString {
///
/// ## Note 1
///
/// The effect of receiving a `CVT`, `HT`, `SCP`, `SPD`, or `VT` control function within an `SRS` string is not defined.
/// The effect of receiving a [`CVT`], [`HT`][crate::c0::HT], [`SCP`], [`SPD`], or [`VT`][crate::c0::VT] control
/// function within an `SRS` string is not defined.
///
/// ## Note 2
///
/// The control functions for area definition (`DAQ`, `EPA`, `ESA`, `SPA`, `SSA`) should not be used within an `SRS`
/// string.
/// The control functions for area definition ([`DAQ`], [`EPA`][crate::c1::EPA], [`ESA`][crate::c1::ESA],
/// [`SPA`][crate::c1::SPA], [`SSA`][crate::c1::SSA]) should not be used within an `SRS` string.
pub fn SRS(s: Option<ReversedString>) -> ControlFunction {
sequence!(05 / 11, selective default s)
}
@ -2220,20 +2252,21 @@ pub fn SSU(s: Option<SizeUnit>) -> ControlFunction {
/// Set Space Width.
///
/// `SSW` is used to establish for subsequent text the character escapement associated with the character SPACE. The
/// `SSW` is used to establish for subsequent text the character escapement associated with the character `SPACE`. The
/// established escapement remains in effect until the next occurrence of `SSW` in the data stream or until it is reset
/// to the default value by a subsequent occurrence of CARRIAGE RETURN/LINE FEED (`CR/LF`), CARRIAGE RETURN/FORM FEED
/// (`CR/FF`), or of NEXT LINE (`NEL`) in the data stream.
/// to the default value by a subsequent occurrence of CARRIAGE RETURN/LINE FEED
/// ([`CR`][crate::c0::CR]/[`LF`][crate::c0::LF]), CARRIAGE RETURN/FORM FEED
/// ([`CR`][crate::c0::CR]/[`FF`][crate::c0::FF]), or of NEXT LINE ([`NEL`][crate::c1::NEL]) in the data stream.
///
/// `n` specifies the escapement.
///
/// The unit in which the parameter value is expressed is that established by the parameter value of SELECT SIZE UNIT
/// (`SSU`).
/// ([`SSU`]).
///
/// The default character escapement of SPACE is specified by the most recent occurrence of SET CHARACTER SPACING
/// (`SCS`) or of SELECT CHARACTER SPACING (`SHS`) or of SELECT SPACING INCREMENT (`SPI`) in the data stream if the
/// current font has constant spacing, or is specified by the nominal width of the character SPACE in the current font
/// if that font has proportional spacing.
/// ([`SCS`]) or of SELECT CHARACTER SPACING ([`SHS`]) or of SELECT SPACING INCREMENT ([`SPI`]) in the data stream if
/// the current font has constant spacing, or is specified by the nominal width of the character `SPACE` in the current
/// font if that font has proportional spacing.
pub fn SSW(n: u32) -> ControlFunction {
sequence!(02 / 00, 05 / 11, numeric n)
}
@ -2300,7 +2333,7 @@ pub enum LineSpacing {
/// Select Line Spacing.
///
/// `SVS` is used to establish the line spacing for subsequent text. The established spacing remains in effect until the
/// next occurrence of `SVS` or of SET LINE SPACING (`SLS`) or of SPACING INCREMENT (`SPI`) in the data stream.
/// next occurrence of `SVS` or of SET LINE SPACING ([`SLS`]) or of SPACING INCREMENT ([`SPI`]) in the data stream.
///
/// The default value for `s` is [`LineSpacing::SixLinesPer25`].
pub fn SVS(s: Option<LineSpacing>) -> ControlFunction {
@ -2350,12 +2383,23 @@ pub fn TATE(n: u32) -> ControlFunction {
/// Valid parameter values to the function [`TBC`].
#[derive(Clone, Copy, PartialEq, Eq, Default)]
pub enum ClearTabulation {
/// Clear the character tabulation stop at the active presentation position.
#[default]
CharacterTabulationStopActivePosition = 0,
/// Clear the line tabulation stop at the active line.
LineTabulationStopActiveLine,
/// Clear all character tabulation stops at the active line.
AllCharacterTabulationStopsActiveLine,
/// Clear all character tabulation stops.
AllCharacterTabulationStops,
/// Clear all line tabulation stops.
AllLineTabulationStops,
/// Clear all tabulation stops.
AllTabulationStops,
}
@ -2386,7 +2430,7 @@ pub fn TBC(s: Option<ClearTabulation>) -> ControlFunction {
/// code. For a 7-bit code, the permissible range of values is `32` to `127`; for an 8-bit code, the permissible range
/// of values is `32` to `127` and `160` to `255`.
///
/// The default value ofr `m` is `32`.
/// The default value of `m` is `32`.
pub fn TCC(n: u32, m: Option<u32>) -> ControlFunction {
let k = m.unwrap_or(32);
sequence!(02 / 00, 06 / 03, numeric n, numeric k)

32
src/independent_control_functions.rs
View File

@ -4,6 +4,18 @@
//! `ESC` is represented by bit combination `01/11` and `Fs` is represented by a bit combination from `06/00` to
//! `07/14`.
//!
//! ## Usage
//!
//! You can use the independent control functions inside normal strings, format them with the `format!()` macro, or
//! print them with the `print!()` and `println!()` macros.
//!
//! For example, to disable manual input:
//!
//! ```
//! use ansi::independent_control_functions::DMI;
//! println!("{}", DMI);
//! ```
//!
//! ## Overview of the Independent Control Functions
//!
//! | Row Number | Column `06` | Column `07` |
@ -68,7 +80,9 @@ pub const INT: ControlFunction = independent!(06 / 01);
/// `LS1R` is used for code extension purposes. It causes the meaning of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `LS1R` is defined in Standard ECMA-35.
/// The use of `LS1R` is defined in Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const LS1R: ControlFunction = independent!(07 / 14);
/// Locking-Shift Two.
@ -76,7 +90,9 @@ pub const LS1R: ControlFunction = independent!(07 / 14);
/// `LS2` is used for code extension purposes. It causes the meaning of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `LS2` is defined in Standard ECMA-35.
/// The use of `LS2` is defined in Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const LS2: ControlFunction = independent!(06 / 14);
/// Locking-Shift Two Right.
@ -84,7 +100,9 @@ pub const LS2: ControlFunction = independent!(06 / 14);
/// `LS2R` is used for code extension purposes. It causes the meaning of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `LS2R` is defined in Standard ECMA-35.
/// The use of `LS2R` is defined in Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const LS2R: ControlFunction = independent!(07 / 13);
/// Locking-Shift Three.
@ -92,7 +110,9 @@ pub const LS2R: ControlFunction = independent!(07 / 13);
/// `LS3` is used for code extension purposes. It causes the meaning of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `LS3` is defined in Standard ECMA-35.
/// The use of `LS3` is defined in Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const LS3: ControlFunction = independent!(06 / 15);
/// Locking-Shift Three Right.
@ -100,7 +120,9 @@ pub const LS3: ControlFunction = independent!(06 / 15);
/// `LS3R` is used for code extension purposes. It causes the meaning of the bit combinations following it in the data
/// stream to be changed.
///
/// The use of `LS3R` is defined in Standard ECMA-35.
/// The use of `LS3R` is defined in Standard [ECMA-35][ecma-35].
///
/// [ecma-35]: https://www.ecma-international.org/wp-content/uploads/ECMA-35_6th_edition_december_1994.pdf
pub const LS3R: ControlFunction = independent!(07 / 12);
/// Reset to Initial State.

175
src/lib.rs
View File

@ -12,7 +12,7 @@
//! In the [ECMA-48 Standard][ecma-48] 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`.
//! to avoid confusion, for example, between the concept "space", and the character `SPACE`.
//!
//! As is intended by the [ECMA-48 Standard][ecma-48], this convention and all acronyms of modes, and control functions
//! are retained in this library, where rust permits.
@ -20,6 +20,34 @@
//! A character from the [ASCII table][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`.
//!
//! ## 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], and [control_strings].
//!
//! The control functions can be put into normal strings. For example, to ring the bell:
//!
//! ```
//! use ansi::c0::BEL;
//! println!("Let's ring the bell {}", BEL);
//! ```
//!
//! Or to move the cursor to line 5, column 13:
//!
//! ```
//! use ansi::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::c1::{ANNOUNCER_SEQUENCE, NEL};
//! // announce the C1 control function set, then move to the next line.
//! print!("{}{}", ANNOUNCER_SEQUENCE, NEL);
//! ```
//!
//! ## Source Material
//!
//! The second, and newer, editions of the [ECMA-48 Standard][ecma-48] are based on the text of the
@ -39,21 +67,21 @@
//! [wikipedia-ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code
#![allow(dead_code)]
use std::str;
use std::{fmt, str};
/// Convert the ascii table notation `xx/yy` into a rust string.
/// Converts the ascii table notation `xx/yy` into a rust string.
///
/// A character from the [ASCII table][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`.
///
/// The macro can be used to convert a single code point into a str, or to convert a sequence of them.
///
/// ```
/// ```ignore
/// let a: &'static str = ascii!(06 / 01);
/// let abc: &'static str = ascii!(06 / 01, 06 / 02, 06 / 03);
/// ```
///
/// ## Safeness
/// ## Safety
///
/// This macro converts the given `xx/yy` combination into a ascii code by the formula `(xx << 4) + yy`.
/// The result is passed to the unsafe function std::str::from_utf8_unchecked.
@ -64,7 +92,7 @@ use std::str;
/// - `yy: [0,15]`
///
/// Since this macro is not public and only used by the library itself, it is assumed to be used only within safe
/// bounds.
/// bounds, and therefore considered safe.
///
/// [ascii-table]: https://en.wikipedia.org/wiki/ASCII#/media/File:USASCII_code_chart.png
macro_rules! ascii {
@ -74,10 +102,14 @@ macro_rules! ascii {
}
/// The different types of control functions.
///
#[derive(Clone, Copy, PartialEq, Eq)]
enum ControlFunctionType {
/// Elements of the C0 set.
///
/// C0 control functions are represented in 7-bit codes by bit combinations from 00/00 to 01/15.
/// C0 control functions are represented in 7-bit codes by bit combinations from `00/00` to `01/15`.
///
/// The control functions of the C0 set are defined in the module [c0].
C0,
/// Elements of the C1 set.
@ -85,27 +117,36 @@ enum ControlFunctionType {
/// C1 control functions are represented in 7-bit codes by 2-character escape sequences of the form `ESC Fe`,
/// where `ESC` is represented by bit combination `01/11`, and `Fe` is represented by a bit combination from
/// `04/00` to `05/15`.
///
/// The control functions of the C1 set are defined in the module [c1].
C1,
/// Control Sequences.
///
/// Control sequences are strings of bit combinations starting with the control function Control Function Introducer
/// (`CSI`), followed by one or more bit combinations representing parameters, if any, and by one ore more bit
/// combinations identifying the control function. The control function `CSI` itself is an element of the independent_control_function set.
/// Control sequences are strings of bit combinations starting with the control function
/// `CONTROL SEQUENCE INTRODUCER` ([`CSI`][c1::CSI]), followed by one or more bit combinations representing
/// parameters, if any, and by one ore more bit combinations identifying the control function. The control function
/// `CSI` itself is an element of the [c1] set.
///
/// The control sequences are defined in the module [control_sequences].
ControlSequence,
/// Independent Control Functions.
///
/// Independent control functions are represented in 7-bit codes by 2-character escape sequences of the form
/// `ESC Fs`, where `ESC` is represented by bit combination `01/11`, and `Fs` is represented by a bit combination
/// from `06/00` to `07/14`
/// from `06/00` to `07/14`.
///
/// The independent control functions are defined in the module [independent_control_functions].
IndependentControlFunction,
/// Control Strings.
///
/// A control string is a string of bit combinations which may occur in the data stream as a logical entity for
/// control purposes. A control string consists of an opening delimiter, a command string or character string, and
/// a terminating delimiter, the String Terminator (`ST`).
/// a terminating delimiter, the String Terminator ([`ST`][c1::ST]).
///
/// The control strings are defined in the module [control_strings].
ControlString,
}
@ -123,16 +164,24 @@ impl fmt::Debug for ControlFunctionType {
}
}
/// An ansi control function defined in [ECMA-48][ecma-48].
///
/// [ecma-48]: https://www.ecma-international.org/publications-and-standards/standards/ecma-48/
pub struct ControlFunction {
/// The type of the control function.
function_type: ControlFunctionType,
/// The byte or byte combination identifying the control function.
value: &'static str,
/// An arbitrary number of arguments for this control function.
parameters: Vec<String>,
}
impl ControlFunction {
/// Creates a new control function of type [C0][ControlFunctionType::C0].
/// Creates a new control function of type [`C0`][ControlFunctionType::C0].
///
/// C0 control functions do not accept any parameters.
/// `C0` control functions do not accept any parameters.
const fn new_c0(value: &'static str) -> Self {
ControlFunction {
function_type: ControlFunctionType::C0,
@ -141,9 +190,9 @@ impl ControlFunction {
}
}
/// Creates a new control function of type [C1][ControlFunctionType::C1].
/// Creates a new control function of type [`C1`][ControlFunctionType::C1].
///
/// independent_control_function control functions do not accept any parameters.
/// `C1` control functions do not accept any parameters.
const fn new_c1(value: &'static str) -> Self {
ControlFunction {
function_type: ControlFunctionType::C1,
@ -152,7 +201,7 @@ impl ControlFunction {
}
}
/// Creates a new control function of type [ControlSequence][ControlFunctionType::ControlSequence].
/// Creates a new control function of type [`ControlSequence`][ControlFunctionType::ControlSequence].
const fn new_sequence(value: &'static str, parameters: Vec<String>) -> Self {
ControlFunction {
function_type: ControlFunctionType::ControlSequence,
@ -161,7 +210,8 @@ impl ControlFunction {
}
}
/// Creates a new control function of type [IndependentControlFunction][ControlFunctionType::IndependentControlFunction].
/// Creates a new control function of type
/// [`IndependentControlFunction`][ControlFunctionType::IndependentControlFunction].
const fn new_independent_control_function(value: &'static str) -> Self {
ControlFunction {
function_type: ControlFunctionType::IndependentControlFunction,
@ -169,6 +219,56 @@ impl ControlFunction {
parameters: vec![],
}
}
fn format_parameters(&self) -> String {
self.parameters.join(ascii!(03 / 11))
}
}
impl fmt::Display for ControlFunction {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self.function_type {
ControlFunctionType::C0 => {
write!(f, "{}", self.value)
}
ControlFunctionType::C1 => {
write!(f, "{}{}", c0::ESC, self.value)
}
ControlFunctionType::ControlSequence => {
let parameters = self.format_parameters();
write!(f, "{}{}{}", c1::CSI, parameters, self.value)
}
ControlFunctionType::IndependentControlFunction => {
write!(f, "{}{}", c0::ESC, self.value)
}
ControlFunctionType::ControlString => {
write!(f, "{}", self.value)
}
}
}
}
impl fmt::Debug for ControlFunction {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
let function: String = self
.value
.as_bytes()
.into_iter()
.map(|b| format!("{:02}/{:02}", b >> 4, (b & 0xF)))
.collect();
f.debug_struct("ControlFunction")
.field("function_type", &self.function_type)
.field("function", &function)
.field("parameters", &self.parameters)
.finish()
}
}
impl From<ControlFunction> for String {
fn from(control_function: ControlFunction) -> Self {
format!("{}", control_function)
}
}
pub mod c0;
@ -177,3 +277,42 @@ pub mod control_sequences;
pub mod control_strings;
pub mod independent_control_functions;
pub mod modes;
#[cfg(test)]
mod tests {
use crate::c0::BEL;
use crate::ControlFunctionType;
/// Test the debug format of [`ControlFunctionType`].
#[test]
fn debug_control_function_type() {
assert_eq!(format!("{:?}", ControlFunctionType::C0), "C0");
assert_eq!(format!("{:?}", ControlFunctionType::C1), "C1");
assert_eq!(
format!("{:?}", ControlFunctionType::ControlSequence),
"Control Sequence"
);
assert_eq!(
format!("{:?}", ControlFunctionType::IndependentControlFunction),
"Independent Control Function"
);
assert_eq!(
format!("{:?}", ControlFunctionType::ControlString),
"Control String"
);
}
/// Test the debug format of [`ControlFunction`][crate::ControlFunction].
#[test]
fn debug_control_function() {
assert_eq!(
format!("{:?}", BEL),
"ControlFunction { function_type: C0, function: \"00/07\", parameters: [] }"
);
assert_eq!(
format!("{:?}", crate::control_sequences::CUP(None, Some(10))),
"ControlFunction { function_type: Control Sequence, function: \"04/08\", parameters: [\"1\", \"10\"] }"
);
}
}