diff --git a/src/control_strings.rs b/src/control_strings.rs index 43ac0a2..ee3b1c2 100644 --- a/src/control_strings.rs +++ b/src/control_strings.rs @@ -2,9 +2,83 @@ //! //! 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 a character string, -//! and a terminating delimiter, the String Terminator (`ST`). +//! and a terminating delimiter, the STRING TERMINATOR ([`ST`][crate::c1::ST]). //! //! A command string is a sequence of bit combinations in the range `00/08` to `00/13` and `02/00` to `07/14`. //! -//! A character string is a sequence of any bit combination, except those representing Start Of String (`SOS`) or String -//! Terminator (`ST`). +//! A character string is a sequence of any bit combination, except those representing START OF STRING +//! ([`SOS`][crate::c1::SOS]) or STRING TERMINATOR ([`ST`][crate::c1::ST]). +//! +//! The low-level ansi control codes for control strings are defined in the module [`c1`][crate::c1]. +//! +//! - APPLICATION PROGRAM COMMAND ([`APC`][crate::c1::APC]) +//! - DEVICE CONTROL STRING ([`DCS`][crate::c1::DCS]) +//! - OPERATING SYSTEM COMMAND ([`OSC`][crate::c1::OSC]) +//! - PRIVACY MESSAGE ([`PM`][crate::c1::PM]) +//! - START OF STRING ([`SOS`][crate::c1::SOS]) +//! - STRING TERMINATOR ([`ST`][crate::c1::ST]) +//! +//! This module contains higher level functions to invoke these low-level ansi control codes. +//! +//! ## Usage +//! +//! Invoke one of the available functions to create new control strings. +//! +//! For example, create a new operating system command to halt the operating system (this is operating system specific +//! and will most likely not work on your operating system). +//! +//! ```no_run +//! use ansi_control_codes::control_strings::operating_system_command; +//! let halt_command = operating_system_command("HALT"); +//! println!("{}", halt_command); +//! ``` + +use crate::c1::{APC, DCS, OSC, PM, SOS, ST}; + +/// Creates a new Application Program Command. +/// +/// The given command string will be prefixed with [`APC`] and suffixed with [`ST`]. +/// +/// The interpretation of the command string depends on the relevant application program. +pub fn application_program_command(command_string: &str) -> String { + format!("{}{}{}", APC, command_string, ST) +} + +/// Creates a new Device Control String. +/// +/// The given control string will be prefixed with [`DCS`] and suffixed with [`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`][crate::control_sequences::IDCS]), if any, or depend on the +/// sending and/or the receiving device. +pub fn device_control_string(control_string: &str) -> String { + format!("{}{}{}", DCS, control_string, ST) +} + +/// Creates a new Operating System Command. +/// +/// The given system command will be prefixed with [`OSC`] and suffixed with [`ST`]. +/// +/// The interpretation of the command string depends on the relevant operating system. +pub fn operating_system_command(system_command: &str) -> String { + format!("{}{}{}", OSC, system_command, ST) +} + +/// Creates a new Privacy Message. +/// +/// The given message will be prefixed with [`PM`] and suffixed with [`ST`]. +/// +/// The interpretation of the message depends on the relevant privacy discipline. +pub fn privacy_message(message: &str) -> String { + format!("{}{}{}", PM, message, ST) +} + +/// Creates a new Control String. +/// +/// The given control string will be prefixed with [`SOS`] and suffixed with [`ST`]. +/// +/// The interpretation of the character string depends on the application. +pub fn control_string(control_string: &str) -> String { + format!("{}{}{}", SOS, control_string, ST) +} diff --git a/src/lib.rs b/src/lib.rs index 50a521c..d14b199 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -23,7 +23,7 @@ //! ## 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]. +//! in the modules [c0], [c1], [control_sequences], [independent_control_functions] //! //! The control functions can be put into normal strings. For example, to ring the bell: //! @@ -48,6 +48,13 @@ //! print!("{}{}", ANNOUNCER_SEQUENCE, NEL); //! ``` //! +//! ## High-Level Functions +//! +//! For your convenience and ease-of-use of the ansi control codes, some functionality is exposed in wrapper functions. +//! See the following module documentations for a more in-depth introduction to these functions. +//! +//! - Working with control strings in module [control_strings]. +//! //! ## Source Material //! //! The second, and newer, editions of the [ECMA-48 Standard][ecma-48] are based on the text of the