commit acf78d86b24d9223a32b26aeedd672f2b90171a2
parent 8202f553483bb8e73a63b7929f43673c7dcd5aff
Author: Dimitrije Dobrota <mail@dimitrijedobrota.com>
Date: Fri, 14 Jun 2024 20:49:47 +0200
Version 1.1
Diffstat:
3 files changed, 51 insertions(+), 34 deletions(-)
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -3,7 +3,7 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
project(
stamen
- VERSION 1.0.1
+ VERSION 1.1.0
DESCRIPTION "Static menu generator"
LANGUAGES C CXX
)
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# stamen
+# Stamen
Static menu generator written in C++20
@@ -15,6 +15,10 @@ The main goal of this project is experimentation. I have been toying with menus
for a while and I've noticed a lot of boilerplate code emerging. That's why I
decided to automate the task by generating menus on the fly.
+The main advantage of stamen is two modes it can operate in:
+1) Static mode, where the menus are pregenerated and linked together with zero cost.
+2) Dynamic mode, where menus are generated on the fly (possibly in runtime) without recompilation.
+
## Getting Started
@@ -22,15 +26,16 @@ decided to automate the task by generating menus on the fly.
* CMake 3.25.2 or latter
* Compiler with C++20 support
+* [Poafloc Library](https://github.com/DimitrijeDobrota/poafloc)
### Installing
* Clone the repo
* Make a build folder and cd into it
-* Run `cmake -DCMAKE_BUILD_TYPE=Release <path to cloned repo>`
-* Run `make`
-* If desired run `make install` in order to install the library and generator program
+* Run `cmake <path to cloned repo>` to set up the build scripts
+* Run `make` to build the project
+* Run `cmake --build . --target install` to install the project
### Configuration
@@ -73,38 +78,44 @@ reference to another panel or any other function (from now on referred to as
> Please reference demo folder for relevant usage example.
+> Refer to demo/CMakeLists.txt to see how to integrate stamen into build system
+
There are a few things needed before you begin.
-* All types and functions with prefix stamen_ are also available in namespace
-stamen:: in C++ for easier use.
+* All types and functions with prefixes `stamen_` and `stamen_menu_` are also
+available in namespaces `stamen::` and `stamen::menu::` in C++ for easier use.
* Panel and item codes must be one word. In addition they must be valid C/C++
function names if static menu is to be build correctly.
-* Each free function must have `int name(int)` signature as prescribed by
-`stamen_callback_f`. Passed int doesn't need to serve any specific purpose,
-it is intended to detonate the position of an item in the previous panel
-which is essential for dynamic menu implementation.
-* You must set a value of the static variable `const stamen_display_f
-stamen_display` to specify function used for displaying the menu. You can start
-by using a build in `stamen_builtin_display`, just make sure to link stamen
-library while building your project.
+* Each free function must have `int name(int);` signature as prescribed by
+`stamen_callback_f`. Passed int it is intended to detonate the position of an
+item in the previous panel which is essential for dynamic menu implementation,
+but it is not required to be used like that.
#### Static menu
-After writing a configuration file, run `./bin/generate <config file>` which
+> Please refer to `stamen-generate --help` for list of all options
+
+After writing a configuration file, run `stamen-generate <config file>` which
will create source file and include file in the current directory with the name
as the configuration file but with extensions `.cpp` and `.hpp` respectively.
-You can create files with extensions `.c` and `.h` by appending C to previous
-command
+You can create files with extensions `.c` and `.h` by appending adding `--c`
+flag to the command line arguments.
Include file will contain declarations for all of the menu functions. You
should include this file in your code.
Source file contains definitions for the menu functions. It also includes
`shared.h` file which should contain declarations for all of the free functions
-you have specified in the configuration.
+you have specified in the configuration. The name of the file with free functions
+can be changed with `--header NAME` flag;
+
+Custom display function to be used can be set with `-d FUNC` flag. Specified
+function will be forward-declared according to `stamen_display_f`, so you
+don't have to worry about doing it yourself.
-Generated source file should be compiled with the rest of your code.
+Generated source file should be compiled with the rest of your code. If
+`stamen_builtin_display` is not used, there is no need to link with the stamen library.
You can call any function to display the menu starting from that specific pane.
@@ -114,7 +125,7 @@ You can call any function to display the menu starting from that specific pane.
Please refer to the implementation of `stamen_builtin_display` to get a general
idea of the direction.
-A display function should have `int name(const char*, const item_t[], int)`
+A display function should have `int name(const char*, const stamen_item_t[], int)`
signature as prescribed by `stamen_display_f`.
After prompting user to select one of the items all you have to do is call a
@@ -133,41 +144,47 @@ program:
```
#include <stamen.h>
-const stamen_display_f stamen_display = stamen_builtin_display;
-
// read the configuration
-stamen_read("path to config");
+stamen_menu_read("path to config");
// register free functions
-stamen_insert("free function code", some_free_function);
+stamen_menu_insert("free function code", some_free_function);
...
// start the menu on specific panel
-stamen_dynamic("panel code");
+stamen_menu_dynamic("panel code", display_function);
```
For C++ there is a namespaced version of the functions:
```
#include <stamen.h>
-const stamen::display_f stamen_display = stamen::builtin_display;
-
// read the configuration
-stamen::read("path to config");
+stamen::menu::read("path to config");
// register free functions
-stamen::insert("free function code", some_free_function);
+stamen::menu::insert("free function code", some_free_function);
...
// start the menu on specific panel
-stamen::dynamic("panel code");
+stamen::menu::dynamic("panel code", display_function);
```
-`
+For the dynamic mode the work, you program needs to be linked with the stamen
+library with C++ compiler as the last step, regardless whether the program was
+written in C or C++.
+
## Version History
-* 1.0
+- 1.1
+ * Separate C and C++ interfaces
+ * Separate dynamic mode into menu namespace
+ * Improve functionality of code generation
+ * Get rid of unnecessary moving parts (stamen_display, ...)
+ * Clean up implementation
+
+- 1.0
* Initial Release
diff --git a/src/generate.cpp b/src/generate.cpp
@@ -97,7 +97,7 @@ static const poafloc::option_t options[]{
{0, 0, 0, 0, "Output settings", 2},
{"display", 'd', "FUNC", 0, "Set display function to be called"},
{"user", 'u', 0, 0, "Include user stamen headers"},
- {"header", 'h', "FUNC", 0,
+ {"header", 'h', "NAME", 0,
"Header with free functions, default: shared.h"},
{0, 0, 0, 0, "Informational Options", -1},
{0},
