added functions for control strings

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)
+}

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