alec

Abstraction Layer for Escape Codes

git clone git://git.dimitrijedobrota.com/alec.git

README.md (7424B)

1 # alec 2 3 Abstraction Layer for Escape Codes 4 5 ## Description 6 7 This project is a header-only library that allows for easy creation and usage 8 of ANSI Escape Codes from C++ project. It exports a set of template variables 9 to be used when the content is known at compile time, as well as a set of 10 functions to be used at run-time. 11 12 Since there are two set of functionalities I noticed a twofold code duplication 13 so I decided to add a preprocessing step that turns a bison-like config file 14 into the desired header, based on the set of simple rules. This step was not 15 100% necessary, and might be an overkill, but I wanted to experiment with this 16 concept for a while and now I have got the change. 17 18 Generator code shown here is written in flex and bison and can be easily 19 adapted for other use cases. 20 21 22 ## Dependencies 23 24 * CMake 3.25.2 or latter 25 * Compiler with C++20 support (tested on clang version 16.0.5) 26 * Flex 2.6.4 27 * Bison 3.8.2 28 29 30 ## Building and installing 31 32 See the [`BUILDING`](BUILDING.md) document. 33 34 35 ### Usage 36 37 > Please reference demo folder for relevant usage example. 38 39 Everything that this library provide is found in `alec` namespace. 40 Functions have names shown in the table below, whilst templates have suffix _v 41 and don't need to be called. 42 43 #### Available functions with short explanation 44 45 | Name | parameters | Description | 46 |-------------------|---------------------|---------------------------------------------------| 47 | cursor_up | int cnt | Move cursor `cnt` lines up | 48 | cursor_down | int cnt | Move cursor `cnt` lines down | 49 | cursor_frwd | int cnt | Move cursor `cnt` lines left | 50 | cursor_back | int cnt | Move cursor `cnt` lines right | 51 | cursor_line_next | int cnt | Move cursor to beginning of line `cnt` lines down | 52 | cursor_line_prev | int cnt | Move cursor to beginning of line `cnt` lines up | 53 | cursor_column | int col | Set cursor to specific position on current line | 54 | cursor_position | int col, int row | Set cursor to specific position on screen | 55 | erase_display | Motion mtn | Erase in display mode | 56 | erase_line | Motion mtn | Erase in line mode | 57 | scroll_up | int cnt | Scroll whole page up by `cnt` | 58 | scroll_down | int cnt | Scroll whole page down by `cnt` | 59 | foreground | Color color | Set foreground to `color` | 60 | background | Color color | Set background to `color` | 61 | foreground | int idx | Set foreground to `idx` in 256 color pallet | 62 | background | int idx | Set background to `idx` in 256 color pallet | 63 | foreground | int R, int G, int B | Set foreground to `RGB` value | 64 | background | int R, int G, int B | Set background to `RGB` value | 65 | decor_set | Decor decor | Turn specific decoration on | 66 | decor_reset | Decor decor | Turn specific decoration of | 67 | cursor_save | | Saves cursor position | 68 | cursor_restore | | Restore cursor position | 69 | screen_mode_set | int mode | Changes screen width or type to `mode` | 70 | screen_mode_reset | int mode | Reset screen width or type to `mode` | 71 | screen_save | | Save screen | 72 | screen_restore | | Restore screen | 73 | cursor_show | | Show cursor | 74 | cursor_hide | | Hide cursor | 75 | abuf_enable | | Enable alternate screen buffer | 76 | abuf_disable | | Disable alternate screen buffer | 77 | paste_enable | | Turn on bracketed paste mode | 78 | paste_disable | | Turn off bracketed paste mode | 79 80 81 #### Enumeration 82 83 ##### Ctrl 84 85 * BELL: Terminal bell 86 * BS: Backspace 87 * HT: Horizontal TAB 88 * LF: Linefeed (newline) 89 * VT: Vertical TAB 90 * FF: Formfeed 91 * CR: Carriage return 92 * ESC: Escape character 93 * DEL: Delete character 94 95 96 ##### Motion 97 98 * END: erase from cursor until end of screen/line 99 * BEGIN: erase from cursor to beginning of screen/line 100 * WHOLE: erase entire screen/line 101 102 103 ##### Color 104 105 * BLACK 106 * RED 107 * GREEN 108 * YELLOW 109 * BLUE 110 * MAGENTA 111 * CYAN 112 * WHITE 113 * DEFAULT 114 115 116 ##### Decor 117 118 * RESET 119 * BOLD 120 * DIM 121 * ITALIC 122 * UNDERLINE 123 * BLINK 124 * INVERSE 125 * HIDE 126 * STRIKE 127 128 129 ## Configuration 130 131 Configuration file `alec.rules.hpp` is used to customize the output of 132 `alec.hpp` file. Similarly to Flex and Bison, configuration files needs to have 133 3 sections separated by `/*%%*/`: prologue, grammar and epilogue. Prologue and 134 epilogue are copied as-is to the output file whilst the grammar section 135 contains rules for generating template and function code. 136 137 * Rules can be separated by an arbitrary number of blank lines. 138 * Everything can have arbitrary indentation that is not carried to the resulting file. 139 * There could be C-style comments that are copied to the resulting file. 140 141 Each rule consists of 4 lines: 142 1. Name: name of the generated function, must be valid C++ name 143 2. Parameters: list of `type name` pairs separated by a comma 144 3. Constraints: list of constraint functions separated by a comma 145 4. Rules: list of chars and ints (or expressions producing them) separated by a 146 comma, or a single string literal 147 148 > You *must* use `|` character in place of empty list rule 149 150 ### Constraints 151 152 * All constraints used in code generation must be defined in the prologue 153 * Every constraint listed will be applied to all of the arguments one by one. 154 * Every constraint has to have a function and template concept variant with the 155 same name, but suffix _v for the template one. 156 * Function constraints are translated into asserts, whilst template ones are used 157 in requires clause of the teconceptmplate. 158 159 ### Examples 160 161 ```c++ 162 // begining of a header file 163 164 // tamplate constraint 165 template <int n> 166 concept limit_pos_v = n >= 0; 167 168 // function constraint 169 static inline bool limit_pos(int n) { return n >= 0; }; 170 171 /*%%*//* 172 173 // comment that goes into output 174 decor_reset 175 Decor decor 176 | 177 (int)decor + 20, 'm' 178 179 screen_mode_set 180 int mode 181 limit_pos 182 '=', mode, 'h' 183 184 paste_enable 185 | 186 | 187 "?2004h" 188 189 *//*%%*/ 190 191 // ending of a header file 192 ``` 193 194 195 ## Version History 196 197 * 0.1 198 * Initial Release 199 200 201 ## Contributing 202 203 See the [`CONTRIBUTING`](CONTRIBUTING.md) document. 204 205 206 ## License 207 208 This project is licensed under the MIT License - see the [`LICENSE`](LICENSE.md) file for details 209 210 ## References 211 212 * [`ANSI Escape Sequences gist`](https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797) 213 * [`Wikipedia article`](https://en.wikipedia.org/wiki/ANSI_escape_code) 214