2023-04-01 22:07:44 -07:00
# gencpp
2024-12-06 21:21:09 -08:00
An attempt at simple staged metaprogramming for C/C++.
2023-04-01 22:07:44 -07:00
2024-12-06 21:21:09 -08:00
The library API is a composition of code element constructors, and a non-standards-compliant single-pass C/C++ parser.
These build up a code AST to then serialize with a file builder, or can be traversed for staged-reflection of C/C++ code.
2023-04-22 19:24:55 -07:00
2024-12-10 13:38:01 -08:00
This code base attempts follow the [handmade philosophy ](https://handmade.network/manifesto ).
Its not meant to be a black box metaprogramming utility, it should be easy to intergrate into a user's project domain.
# Documentation
[]
2023-07-24 11:30:35 -07:00
2023-04-03 00:55:28 -07:00
## Notes
2024-12-10 13:38:01 -08:00
**On Partial Hiatus: Life has got me tackling other issues..**
I will be passively updating the library with bug fixes and minor improvements as I use it for my personal projects.
2024-05-05 18:53:22 -07:00
There won't be any major reworks or features to this thing for a while.
2023-10-01 09:37:29 -07:00
2024-12-10 13:38:01 -08:00
This project is still in development (very much an alpha state), so expect bugs and missing features.
2023-09-11 15:34:37 -07:00
See [issues ](https://github.com/Ed94/gencpp/issues ) for a list of known bugs or todos.
The library can already be used to generate code just fine, but the parser is where the most work is needed. If your C++ isn't "down to earth" expect issues.
2023-07-24 08:20:13 -07:00
2023-09-11 15:34:37 -07:00
A `natvis` and `natstepfilter` are provided in the scripts directory (its outdated, I'll update this readme when its not).
2023-07-15 20:38:53 -07:00
2023-04-03 23:04:19 -07:00
## Usage
2023-04-01 22:07:44 -07:00
2023-07-18 21:14:15 -07:00
A metaprogram is built to generate files before the main program is built. We'll term runtime for this program as `GEN_TIME` . The metaprogram's core implementation are within `gen.hpp` and `gen.cpp` in the project directory.
2023-04-01 22:07:44 -07:00
2023-04-02 09:35:14 -07:00
`gen.cpp` \`s `main()` is defined as `gen_main()` which the user will have to define once for their program. There they will dictate everything that should be generated.
2023-04-01 22:07:44 -07:00
2024-12-06 21:21:09 -08:00
In order to keep the locality of this code within the same files the following pattern may be used (although this pattern isn't the best to use):
2023-04-01 22:07:44 -07:00
Within `program.cpp` :
2023-04-07 23:16:25 -07:00
2023-04-01 22:07:44 -07:00
```cpp
2023-07-18 21:14:15 -07:00
#ifdef GEN_TIME
2023-04-01 22:07:44 -07:00
#include "gen.hpp"
...
u32 gen_main()
{
2023-04-07 23:16:25 -07:00
...
2023-04-01 22:07:44 -07:00
}
#endif
2023-08-08 08:56:42 -07:00
// "Stage" agnostic code.
2023-07-18 21:14:15 -07:00
#ifndef GEN_TIME
2023-04-01 22:07:44 -07:00
#include "program.gen.cpp"
2023-04-07 23:16:25 -07:00
// Regular runtime dependent on the generated code here.
2023-04-01 22:07:44 -07:00
#endif
```
2024-12-10 13:38:01 -08:00
The design uses a constructive builder API for the code to generate.
2023-07-29 02:52:06 -07:00
The user is provided `Code` objects that are used to build up the AST.
2023-04-03 23:04:19 -07:00
2023-04-07 23:16:25 -07:00
Example using each construction interface:
2023-04-22 19:24:55 -07:00
### Upfront
2023-08-08 08:56:42 -07:00
Validation and construction through a functional interface.
2023-04-07 23:16:25 -07:00
```cpp
2024-10-27 15:58:37 -07:00
Code t_uw = def_type( name(usize) );
2023-04-07 23:16:25 -07:00
Code t_allocator = def_type( name(allocator) );
2023-07-12 00:41:16 -07:00
Code t_string_const = def_type( name(char), def_specifiers( args( ESpecifier::Const, ESpecifier::Ptr ) ));
2023-04-07 23:16:25 -07:00
Code header;
{
Code num = def_variable( t_uw, name(Num) );
Code cap = def_variable( t_uw, name(Capacity) );
Code mem_alloc = def_variable( t_allocator, name(Allocator) );
2023-07-12 00:41:16 -07:00
Code body = def_struct_body( args( num, cap, mem_alloc ) );
2023-04-07 23:16:25 -07:00
header = def_struct( name(ArrayHeader), __ , __ , body );
}
```
2023-04-22 19:24:55 -07:00
### Parse
2023-04-07 23:16:25 -07:00
2023-08-08 08:56:42 -07:00
Validation through ast construction.
2023-04-07 23:16:25 -07:00
```cpp
Code header = parse_struct( code(
struct ArrayHeader
{
2024-10-27 15:58:37 -07:00
usize Num;
usize Capacity;
2023-04-07 23:16:25 -07:00
allocator Allocator;
};
));
```
2023-06-28 22:37:42 -07:00
### Untyped
2023-04-07 23:16:25 -07:00
2023-08-08 08:56:42 -07:00
No validation, just glorified text injection.
2023-04-07 23:16:25 -07:00
```cpp
2023-07-24 20:10:10 -07:00
Code header = code_str(
2023-04-22 19:24:55 -07:00
struct ArrayHeader
2023-04-07 23:16:25 -07:00
{
2024-10-27 15:58:37 -07:00
usize Num;
usize Capacity;
2023-04-07 23:16:25 -07:00
allocator Allocator;
2023-04-22 19:24:55 -07:00
};
2023-07-24 20:10:10 -07:00
);
2023-04-07 23:16:25 -07:00
```
2024-12-10 13:38:01 -08:00
`name` is a helper macro for providing a string literal with its size, intended for the name parameter of functions.
`code` is a helper macro for providing a string literal with its size, but intended for code string parameters.
2023-07-12 00:41:16 -07:00
`args` is a helper macro for providing the number of arguments to varadic constructors.
2023-07-24 20:10:10 -07:00
`code_str` is a helper macro for writting `untyped_str( code( <content> ))`
2023-04-07 23:16:25 -07:00
All three constrcuton interfaces will generate the following C code:
2023-04-03 23:04:19 -07:00
```cpp
struct ArrayHeader
{
2024-10-27 15:58:37 -07:00
usize Num;
usize Capacity;
2023-04-04 13:13:48 -07:00
allocator Allocator;
2023-04-03 23:04:19 -07:00
};
```
2023-04-07 23:16:25 -07:00
2023-04-03 23:04:19 -07:00
**Note: The formatting shown here is not how it will look. For your desired formatting its recommended to run a pass through the files with an auto-formatter.**
2023-09-11 15:34:37 -07:00
*(The library currently uses clang-format for formatting, beware its pretty slow...)*
2023-04-03 23:04:19 -07:00
2023-04-01 22:07:44 -07:00
## Building
2023-07-29 02:52:06 -07:00
See the [scripts directory ](scripts/ ).