stamen

Static Menu Generator

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

commit	02f29537709af555084d5c8eaac6d3caddc9b8cc
parent	98b872b2708de3b428418815b77ad9a4bae5f0cf
author	Dimitrije Dobrota <mail@dimitrijedobrota.com>
date	Wed, 26 Feb 2025 18:37:51 +0100

Update README to reflect recent changes

Diffstat:

M	CMakeLists.txt	\|	+-
M	README.md	\|	+++++++++++++++++++++++++++++++---------------------------------------------------

2 files changed, 35 insertions(+), 57 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt

@@ -4,7 +4,7 @@ include(cmake/prelude.cmake)

project(

stamen

VERSION 1.2.8

VERSION 1.2.9

DESCRIPTION "Static menu generator"

HOMEPAGE_URL "https://git.dimitrijedobrota.com/stamen"

LANGUAGES C CXX

diff --git a/README.md b/README.md

@@ -4,11 +4,10 @@ Static menu generator written in C++20

## Description

This project allows for a creation of static menus, to be used in C or C++, on

the fly. The stamen library acts as a framework for linking and keeping track

of the menus, whilst allowing a custom display function to be used for maximum

flexibility. In dynamic mode configuration file can be read on the fly without

recompilation.

This project is a code generation tool that takes care of the menus. The

stamen acts as a framework for linking and keeping track of the menus, whilst

allowing a custom display function to be used for maximum flexibility. In

dynamic mode configuration file can be read on the fly without recompilation.

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

@@ -21,9 +20,10 @@ The main advantage of stamen is two modes it can operate in:

## Dependencies

* CMake 3.25.2 or latter

* Compiler with C++20 support (tested: clang 16.0.5, gcc 13.2.0)

* [Poafloc 1.1](https://github.com/DimitrijeDobrota/poafloc)

* CMake 3.14 or latter

* Compiler with C++20 support (tested: clang 19.1.7, gcc 14.2.1)

* [`Cemplate 0.2`](https://github.com/DimitrijeDobrota/cemplate)

* [`Poafloc 1.2`](https://github.com/DimitrijeDobrota/poafloc)

## Building and installing

@@ -39,12 +39,10 @@ See the [BUILDING](BUILDING.md) document.

There are a few things needed before you begin.

* 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++

* Panel and item codes must be one word. In addition they must be valid 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 it is intended to detonate the position of an

* Each free function must have `int name(std::size_t);` signature as prescribed by

`stamen::callback_f`. Passed value 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.

@@ -91,35 +89,25 @@ reference to another panel or any other function (from now on referred to as

After writing a configuration file, run `stamen <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 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.

Include file will contain declarations for all of the menu functions, as well

as the class to be used in this specific menu instance. 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. The name of the file with free functions

can be changed with `--header NAME` flag;

Generated source file should be compiled with the rest of your code, as it

contains definitions for the menu functions.

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.

User should give a definition of `menu_t::visit(const menu_t& menu)`, that

actually renders the menu end prompts the user for action.

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.

You can call any function to display the menu starting from that specific panel.

### Custom display function

Please refer to the implementation of `stamen_builtin_display` to get a general

Please refer to the implementation in `example/static.cpp` to get a general

idea of the direction.

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

function pointed to by the callback field on selected item to invoke the next

panel or free function. The return type of int is intended to be used as a

@@ -130,45 +118,35 @@ terminates, but you can use in any way you see fit.

### Dynamic menu

In dynamic mode, configuration file is read every time the program is run. In

order to invoke the menu you need to add the following snippet to your C

program:

order to invoke the menu you need to add the following snippet:

```

#include <stamen.h>

#include "stamen/stamen.hpp"

// read the configuration

stamen_menu_read("path to config");

stamen::Stamen inst(ifs);

// register free functions

stamen_menu_insert("free function code", some_free_function);

inst.insert("free function code", some_free_function);

...

// start the menu on specific panel

stamen_menu_dynamic("panel code", display_function);

```

For C++ there is a namespaced version of the functions:

```

#include <stamen.h>

// read the configuration

stamen::menu::read("path to config");

// register free functions

stamen::menu::insert("free function code", some_free_function);

inst.dynamic("menu_main", display);

...

// start the menu on specific panel

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++.

library with C++ compiler as the last step.

## Version History

- 1.3

* Drop C support (it was fun while it lasted)

* Use [`Cemplate`](https://github.com/DimitrijeDobrota/cemplate) for code generation

* No need to include stamen headers as everything is self contained

* Cleanup the code with better implementation

- 1.2

* Modernize CMake project

* Modernize codebase

@@ -186,12 +164,12 @@ written in C or C++.

## Contributing

See the [CONTRIBUTING](CONTRIBUTING.md) document.

See the [`CONTRIBUTING`](CONTRIBUTING.md) document.

## License

This project is licensed under the MIT License -

see the [LICENSE](LICENSE.md) file for details

see the [`LICENSE`](LICENSE.md) file for details