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

adds more documentation to lib.rs

Browse Source
This commit is contained in:
Frank Zechert 2023-04-01 01:45:44 +02:00
parent 52a2be9a1a
commit ef555cbe05
1 changed files with 66 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
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;
//! print!("{}", BEL);
//! ```
//!
//! Or to move the cursor to line 5, column 13:
//!
//! ```
//! use ansi::control_sequences::CUP;
//! print!("{}", CUP(Some(5), Some(13)));
//! ```
//!
//! 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 {
@ -77,7 +105,9 @@ macro_rules! ascii {
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 +115,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 +162,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 +188,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 +199,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 +208,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,