stamen

Static Menu Generator

git clone git://git.dimitrijedobrota.com/stamen.git

README.md (5314B)

1 # stamen 2 3 Static menu generator written in C++20 4 5 ## Description 6 7 This project is a code generation tool that takes care of the menus. The 8 stamen acts as a framework for linking and keeping track of the menus, whilst 9 allowing a custom display function to be used for maximum flexibility. In 10 dynamic mode configuration file can be read on the fly without recompilation. 11 12 The main goal of this project is experimentation. I have been toying with menus 13 for a while and I've noticed a lot of boilerplate code emerging. That's why I 14 decided to automate the task by generating menus on the fly. 15 16 The main advantage of stamen is two modes it can operate in: 17 1) Static mode, where the menus are pregenerated and linked together with zero cost. 18 2) Dynamic mode, where menus are generated on the fly (possibly in runtime) without recompilation. 19 20 21 ## Dependencies 22 23 * CMake 3.14 or latter 24 * Compiler with C++20 support (tested: clang 19.1.7, gcc 14.2.1) 25 26 27 ## Building and installing 28 29 See the [`BUILDING`](BUILDING.md) document. 30 31 32 ## Usage 33 34 > Please reference example folder for relevant usage examples. 35 36 > Refer to example/CMakeLists.txt to see how to integrate stamen into build system 37 38 There are a few things needed before you begin. 39 40 * Panel and item codes must be one word. In addition they must be valid C++ 41 function names if static menu is to be build correctly. 42 * Each free function must have `int name(std::size_t);` signature as prescribed by 43 `stamen::callback_f`. Passed value is intended to detonate the position of an 44 item in the previous panel which is essential for dynamic menu implementation, 45 but it is not required to be used like that. 46 47 ### Configuration 48 49 In order to generate the desired menu, a configuration file needs to be 50 written. Here is an example: 51 ``` 52 + menu_main Main Menu 53 - submenu_1 Enter Submenu 1 54 - submenu_2 Enter Submenu 2 55 - finish Quit 56 57 + submenu_1 Submenu 1 58 - operation1 Operation 1 59 - operation2 Operation 2 60 61 + submenu_2 Submenu 2 62 - operation1 Operation 1 63 - operation2 Operation 2 64 ``` 65 66 Configuration file consists of 2 types of entities: panels and items. Empty 67 lines are ignored. 68 69 Panel is detonated by `+` sign at the start of the line and consists of two 70 parts: code(one word) and title(rest of the line). 71 72 Item entity is detonated by `-` sign at the start of the line and consists of 73 two parts: code(one word) and prompt(rest of the line). 74 75 Panel entity creates a new panel, and each subsequent menu item is added as an 76 option to the panel, until new panel is created. 77 78 Panel code is an unique reference to the panel, whilst item code can be a 79 reference to another panel or any other function (from now on referred to as 80 `free function`). 81 82 83 ### Static menu 84 85 > Please refer to `stamen --help` for list of all options 86 87 After writing a configuration file, run `stamen <config file>` which 88 will create source file and include file in the current directory with the name 89 as the configuration file but with extensions `.cpp` and `.hpp` respectively. 90 91 Include file will contain declarations for all of the menu functions, as well 92 as the class to be used in this specific menu instance. You should include this 93 file in your code. 94 95 Generated source file should be compiled with the rest of your code, as it 96 contains definitions for the menu functions. 97 98 User should give a definition of `menu_t::visit(const menu_t& menu)`, that 99 actually renders the menu end prompts the user for action. 100 101 You can call any function to display the menu starting from that specific panel. 102 103 104 ### Custom display function 105 106 Please refer to the implementation in `example/static.cpp` to get a general 107 idea of the direction. 108 109 After prompting user to select one of the items all you have to do is call a 110 function pointed to by the callback field on selected item to invoke the next 111 panel or free function. The return type of int is intended to be used as a 112 measure how many panels back should be backtracked after a free function 113 terminates, but you can use in any way you see fit. 114 115 116 ### Dynamic menu 117 118 In dynamic mode, configuration file is read every time the program is run. In 119 order to invoke the menu you need to add the following snippet: 120 121 ``` 122 #include "stamen/stamen.hpp" 123 124 // read the configuration 125 stamen::Stamen inst(ifs); 126 127 // register free functions 128 inst.insert("free function code", some_free_function); 129 ... 130 131 // start the menu on specific panel 132 inst.dynamic("menu_main", display); 133 ... 134 ``` 135 136 For the dynamic mode the work, you program needs to be linked with the stamen 137 library with C++ compiler as the last step. 138 139 140 ## Version History 141 142 - 1.3 143 * Drop C support (it was fun while it lasted) 144 * Use [`Cemplate`](https://github.com/DimitrijeDobrota/cemplate) for code generation 145 * No need to include stamen headers as everything is self contained 146 * Cleanup the code with better implementation 147 148 - 1.2 149 * Modernize CMake project 150 * Modernize codebase 151 152 - 1.1 153 * Separate C and C++ interfaces 154 * Separate dynamic mode into menu namespace 155 * Improve functionality of code generation 156 * Get rid of unnecessary moving parts (stamen_display, ...) 157 * Clean up implementation 158 159 - 1.0 160 * Initial Release 161 162 163 ## Contributing 164 165 See the [`CONTRIBUTING`](CONTRIBUTING.md) document. 166 167 168 ## License 169 170 This project is licensed under the MIT License - see the [`LICENSE`](LICENSE.md) file for details 171 172