diff --git a/src/c1.rs b/src/c1.rs index b0f38c9..6f4bca5 100644 --- a/src/c1.rs +++ b/src/c1.rs @@ -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.