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

improves documentation in module c1

Browse Source
This commit is contained in:
Frank Zechert 2023-04-01 02:41:25 +02:00
parent 4e4052b74c
commit dceb34a9a9
1 changed files with 80 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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.