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