coded_chars/lib.rs
1
2//! This crate implements the ECMA-48 standard for coded characters in rust.
3//!
4//! Various constructions are provided to easily add control character and sequences inside text.
5//!
6//! This crate is compatible with "ANSI terminals".
7//!
8//! # Standard implemented
9//! - [ecma-48](https://ecma-international.org/publications-and-standards/standards/ecma-48/) - Control Functions for Coded Character Sets
10//!
11//! ## An example : format a text printed in an ECMA/ANSI terminal
12//! ```
13//! use coded_chars::clear_screen;
14//! use coded_chars::cursor::set_position;
15//! use coded_chars::presentation::{format_str, select_graphic};
16//!
17//! // Direct format
18//! println!("Hello {}World{} !", select_graphic().fg_red().bold().underline(), select_graphic().default());
19//!
20//! // Clear screen
21//! clear_screen();
22//!
23//! // Using format_str
24//! let formatted = format_str(
25//! "World",
26//! select_graphic().fg_red().bold().underline()
27//! );
28//! println!("Hello {} !", formatted);
29//!
30//! set_position(5, 1).exec();
31//! println!("This line is printed on the fifth line.");
32//! ```
33//!
34//! ## All ECMA-48 control functions
35//!
36//! - Delimiters
37//! - APC : [delimiters::APC]
38//! - CMD : [delimiters::CMD]
39//! - DCS : [delimiters::DCS]
40//! - OSC : [delimiters::OSC]
41//! - PM : [delimiters::PM]
42//! - SOS : [delimiters::SOS]
43//! - ST : [delimiters::ST]
44//! - Introducers
45//! - CSI : [introducers::CSI] (see [control::ControlSequence])
46//! - ESC : [introducers::ESC]
47//! - SCI : [introducers::SCI]
48//! - Shifts
49//! - LS0 : [shifts::LS0]
50//! - LS1 : [shifts::LS1]
51//! - LS1R : [shifts::LS1R]
52//! - LS2 : [shifts::LS2]
53//! - LS2R : [shifts::LS2R]
54//! - LS3 : [shifts::LS3]
55//! - LS3R : [shifts::LS3R]
56//! - SI : [shifts::SI]
57//! - SO : [shifts::SO]
58//! - SS2 : [shifts::SS2]
59//! - SS3 : [shifts::SS3]
60//! - Format
61//! - BS : [format::BS]
62//! - CR : [format::CR]
63//! - FF : [format::FF]
64//! - HPA : [format::character_absolute]
65//! - HPB : [format::character_backward]
66//! - HPR : [format::character_forward]
67//! - HT : [format::HT]
68//! - HTJ : [format::HTJ]
69//! - HTS : [format::HTS]
70//! - HVP : [format::character_and_line_position]
71//! - LF : [format::LF]
72//! - NEL : [format::NEL]
73//! - PLD : [format::PLD]
74//! - PLU : [format::PLU]
75//! - PPA : [format::page_position]
76//! - PPB : [format::page_backward]
77//! - PPR : [format::page_forward]
78//! - RI : [format::RI]
79//! - TBC : [format::clear_tabulation]
80//! - TSR : [format::remove_tabulation_stop]
81//! - VPA : [format::line_position]
82//! - VPB : [format::line_backward]
83//! - VPR : [format::line_forward]
84//! - VT : [format::VT]
85//! - VTS : [format::VTS]
86//! - Presentation
87//! - BPH : [presentation::BPH]
88//! - DTA : [presentation::dimension_text]
89//! - FNT : [presentation::select_font] (see [presentation::Font])
90//! - GCC : [presentation::character_combination] (see [presentation::Combination])
91//! - GSM : [presentation::modify_size]
92//! - GSS : [presentation::select_size]
93//! - JFY : [presentation::justify] (see [presentation::JustifyMode])
94//! - PEC : [presentation::expand_or_condense] (see [presentation::Expansion])
95//! - PFS : [presentation::select_page_format] (see [presentation::PageFormat])
96//! - PTX : [presentation::parallel_texts] (see [presentation::TextDelimiter])
97//! - QUAD : [presentation::quad] (see [presentation::Layout])
98//! - REP : [presentation::repeat]
99//! - SACS : [presentation::add_separation]
100//! - SAPV : [presentation::select_alternative] (see [presentation::PresentationVariant])
101//! - SCO : [presentation::character_orientation] (see [presentation::Orientation])
102//! - SCP : [presentation::character_path] (see [presentation::CharacterPath] & [presentation::PathEffect])
103//! - SDS : [presentation::directed] (see [presentation::StringDirection])
104//! - SGR : [presentation::select_graphic] (see [presentation::GraphicSelection])
105//! - SHS : [presentation::select_spacing] (see [presentation::CharacterSpacing])
106//! - SIMD : [presentation::select_implicit] (see [presentation::MovementDirection])
107//! - SLH : [presentation::line_home]
108//! - SLL : [presentation::line_limit]
109//! - SLS : [presentation::line_spacing]
110//! - SPD : [presentation::select_directions] (see [presentation::LineOrientation], [presentation::CharacterPath] and [presentation::PathEffect])
111//! - SPH : [presentation::page_home]
112//! - SPI : [presentation::spacing_increment]
113//! - SPL : [presentation::page_limit]
114//! - SPQR : [presentation::print_quality]
115//! - SRCS : [presentation::reduce_separation]
116//! - SRS : [presentation::reversed] (see [presentation::StringReversion])
117//! - SSU : [presentation::select_size_unit] (see [presentation::SizeUnit])
118//! - SSW : [presentation::space_width]
119//! - STAB : [presentation::select_tabulation]
120//! - SVS : [presentation::select_line_spacing]
121//! - TAC : [presentation::align_center]
122//! - TALE : [presentation::align_trailing]
123//! - TATE : [presentation::align_trailing]
124//! - TCC : [presentation::tabulation_center_on_char]
125//! - TSS : [presentation::specify_thin_space]
126//! - Editor
127//! - DCH : [editor::delete_char]
128//! - DL : [editor::delete_line]
129//! - EA : [editor::erase]
130//! - ECH : [editor::erase_char]
131//! - ED : [editor::erase_in_page]
132//! - EF : [editor::erase_in_field]
133//! - EL : [editor::erase_in_line]
134//! - ICH : [editor::insert_char]
135//! - IL : [editor::insert_line]
136//! - SEE : [editor::select_extent] (see [editor::EditingExtent])
137//! - Cursor
138//! - CBT : [cursor::tabulation_backward]
139//! - CHT : [cursor::tabulation_forward]
140//! - CNL : [cursor::Direction::NextLine] (see [cursor::move_cursor])
141//! - CPL : [cursor::Direction::PreviousLine] (see [cursor::move_cursor])
142//! - CPR : [cursor::position_report]
143//! - CTC : [cursor::tabulation_control]
144//! - CUB : [cursor::Direction::Backward] (see [cursor::move_cursor])
145//! - CUD : [cursor::Direction::Down] (see [cursor::move_cursor])
146//! - CUF : [cursor::Direction::Forward] (see [cursor::move_cursor])
147//! - CUP : [cursor::set_position]
148//! - CUU : [cursor::Direction::Up] (see [cursor::move_cursor])
149//! - CVT : [cursor::line_tabulation]
150//! - Display
151//! - NP : [display::next_page]
152//! - PP : [display::previous_page]
153//! - SD : [display::ScrollDirection::Down] (see [display::scroll])
154//! - SL : [display::ScrollDirection::Left] (see [display::scroll])
155//! - SR : [display::ScrollDirection::Right] (see [display::scroll])
156//! - SU : [display::ScrollDirection::Up] (see [display::scroll])
157//! - Device
158//! - DA : [device::attributes]
159//! - DMI : [device::DMI]
160//! - DC1 : [device::DC1]
161//! - DC2 : [device::DC2]
162//! - DC3 : [device::DC3]
163//! - DC4 : [device::DC4]
164//! - DSR : [device::report_status] (see [device::StatusReport])
165//! - EMI : [device::EMI]
166//! - FNK : [device::function_key]
167//! - IDCS : [device::identify_control_string] (see [device::ControlString])
168//! - IGS : [device::identify_graphic_sub]
169//! - INT : [device::INT]
170//! - MC : [device::media_copy] (see [device::CopyStatus])
171//! - RIS : [device::RIS]
172//! - SEF : [device::eject_and_feed]
173//! - Separators
174//! - IS1 : [characters::separator::US]
175//! - IS2 : [characters::separator::RS]
176//! - IS3 : [characters::separator::GS]
177//! - IS4 : [characters::separator::FS]
178//! - Area
179//! - DAQ : [area::area_qualification]
180//! - EPA : [area::EPA]
181//! - ESA : [area::ESA]
182//! - SPA : [area::SPA]
183//! - SSA : [area::SSA]
184//! - Mode
185//! - RM : [mode::Mode::reset]
186//! - SM : [mode::Mode::set]
187//! - Transmission
188//! - ACK : [transmission::ACK]
189//! - DLE : [transmission::DLE]
190//! - ENQ : [transmission::ENQ]
191//! - EOT : [transmission::EOT]
192//! - ETB : [transmission::ETB]
193//! - ETX : [transmission::ETX]
194//! - NAK : [transmission::NAK]
195//! - NBH : [presentation::NBH]
196//! - SOH : [transmission::SOH]
197//! - STX : [transmission::STX]
198//! - SYN : [transmission::SYN]
199//!
200//! Other :
201//! - BEL : [characters::BEL]
202//! - CAN : [characters::CAN]
203//! - CCH : [escape::CCH]
204//! - EM : [characters::EM]
205//! - MW : [escape::MW]
206//! - NUL : [characters::NUL]
207//! - PU1 : [escape::PU1]
208//! - PU2 : [escape::PU2]
209//! - STS : [escape::STS]
210//! - SUB : [characters::SUB]
211
212pub mod characters;
213pub mod escape;
214pub mod delimiters;
215pub mod introducers;
216pub mod transmission;
217pub mod shifts;
218pub mod control;
219pub mod format;
220pub mod presentation;
221pub mod editor;
222pub mod display;
223pub mod device;
224pub mod area;
225pub mod mode;
226pub mod cursor;
227
228/// The page is erased and the cursor position is set to the first line and the first column.
229///
230/// - The ANSI/ECMA printed function is : `ED(2),CUP(1,1)`
231/// - The ANSI/ECMA printed sequence is : `\x1b[2J\x1b[1;1H`
232///
233pub fn clear_screen() {
234 use crate::cursor::set_position;
235 use crate::editor::{erase_in_page, AreaPosition};
236
237 print!("{}{}", erase_in_page(AreaPosition::Whole), set_position(1, 1));
238}
239
240#[cfg(test)]
241mod tests {
242 #[test]
243 fn test() {
244 use crate::clear_screen;
245 use crate::cursor::set_position;
246 use crate::presentation::{format_str, select_graphic};
247
248 // Direct format
249 println!("Hello {}World{}!", select_graphic().fg_red().bold().underline(), select_graphic().default());
250
251 // Clear screen
252 clear_screen();
253
254 // Using format_str
255 let fmt_world = format_str(
256 "World",
257 select_graphic().fg_red().bold().underline()
258 );
259 println!("Hello {fmt_world}!");
260
261 set_position(5, 1).exec();
262 println!("This line is printed on the fifth line.");
263 }
264
265}