ansi_control_codes/control_strings.rs
1//! Control Strings.
2//!
3//! A control string is a string of bit combinations which may occur in the data stream as a logical entity for
4//! control purposes. A control string consists of an opening delimiter, a command string or a character string,
5//! and a terminating delimiter, the STRING TERMINATOR ([`ST`]).
6//!
7//! A command string is a sequence of bit combinations in the range `00/08` to `00/13` and `02/00` to `07/14`.
8//!
9//! A character string is a sequence of any bit combination, except those representing START OF STRING
10//! ([`SOS`]) or STRING TERMINATOR ([`ST`]).
11//!
12//! The low-level ansi control codes for control strings are defined in the module [`c1`][crate::c1].
13//!
14//! - APPLICATION PROGRAM COMMAND ([`APC`])
15//! - DEVICE CONTROL STRING ([`DCS`])
16//! - OPERATING SYSTEM COMMAND ([`OSC`])
17//! - PRIVACY MESSAGE ([`PM`])
18//! - START OF STRING ([`SOS`])
19//! - STRING TERMINATOR ([`ST`])
20//!
21//! This module contains higher level functions to invoke these low-level ansi control codes.
22//!
23//! ## Usage
24//!
25//! Invoke one of the available functions to create new control strings.
26//!
27//! For example, create a new operating system command to halt the operating system (this is operating system specific
28//! and will most likely not work on your operating system).
29//!
30//! ```no_run
31//! use ansi_control_codes::control_strings::operating_system_command;
32//! let halt_command = operating_system_command("HALT");
33//! println!("{}", halt_command);
34//! ```
35
36use crate::c1::{APC, DCS, OSC, PM, SOS, ST};
37
38/// Creates a new Application Program Command.
39///
40/// The given command string will be prefixed with [`APC`] and suffixed with [`ST`].
41///
42/// The interpretation of the command string depends on the relevant application program.
43pub fn application_program_command(command_string: &str) -> String {
44 format!("{}{}{}", APC, command_string, ST)
45}
46
47/// Creates a new Device Control String.
48///
49/// The given control string will be prefixed with [`DCS`] and suffixed with [`ST`].
50///
51/// The command string represents either one or more commands for the receiving device, or one or more status reports
52/// from the sending device. The purpose and the format of the command string are specified by the most recent
53/// occurrence of IDENTIFY DEVICE CONTROL STRING ([`IDCS`][crate::control_sequences::IDCS]), if any, or depend on the
54/// sending and/or the receiving device.
55pub fn device_control_string(control_string: &str) -> String {
56 format!("{}{}{}", DCS, control_string, ST)
57}
58
59/// Creates a new Operating System Command.
60///
61/// The given system command will be prefixed with [`OSC`] and suffixed with [`ST`].
62///
63/// The interpretation of the command string depends on the relevant operating system.
64pub fn operating_system_command(system_command: &str) -> String {
65 format!("{}{}{}", OSC, system_command, ST)
66}
67
68/// Creates a new Privacy Message.
69///
70/// The given message will be prefixed with [`PM`] and suffixed with [`ST`].
71///
72/// The interpretation of the message depends on the relevant privacy discipline.
73pub fn privacy_message(message: &str) -> String {
74 format!("{}{}{}", PM, message, ST)
75}
76
77/// Creates a new Control String.
78///
79/// The given control string will be prefixed with [`SOS`] and suffixed with [`ST`].
80///
81/// The interpretation of the character string depends on the application.
82pub fn control_string(control_string: &str) -> String {
83 format!("{}{}{}", SOS, control_string, ST)
84}