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