stamen

Static Menu Generator

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

commit	acf78d86b24d9223a32b26aeedd672f2b90171a2
parent	8202f553483bb8e73a63b7929f43673c7dcd5aff
author	Dimitrije Dobrota < mail@dimitrijedobrota.com >
date	Fri, 14 Jun 2024 18:49:47 +0200

Version 1.1

Diffstat:

M	CMakeLists.txt	\|	+ -
M	README.md	\|	+++++++++++++++++++++++++++++++++++++++++++++++++ ---------------------------------
M	src/generate.cpp	\|	+ -

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},