From 367b5272295d63997e4ab6c88daebd456e69e97c Mon Sep 17 00:00:00 2001 From: Allen Webster Date: Fri, 8 Oct 2021 21:01:04 -0700 Subject: [PATCH] [examples] start type metadata commentary --- examples/examples_directory.txt | 2 + examples/type_metadata/type_info.h | 5 +-- .../type_metadata/type_info_final_program.c | 2 +- examples/type_metadata/type_metadata.c | 39 ++++++++++++++++++- examples/type_metadata/types.mdesk | 4 +- 5 files changed, 46 insertions(+), 6 deletions(-) diff --git a/examples/examples_directory.txt b/examples/examples_directory.txt index d1a4c2f..bed4b02 100644 --- a/examples/examples_directory.txt +++ b/examples/examples_directory.txt @@ -34,6 +34,8 @@ EXAMPLES: 6. "type metadata" type_metadata/* + (Start exploring this example at type_metadata/type_metadata.c) + A common use case for a metaprogramming system in C is to mark up type information with metadata. This example shows the "Metadesk way" of implementing that use case. This is the biggest example included and closely diff --git a/examples/type_metadata/type_info.h b/examples/type_metadata/type_info.h index 271d0e1..f13b317 100644 --- a/examples/type_metadata/type_info.h +++ b/examples/type_metadata/type_info.h @@ -1,9 +1,8 @@ /* ** Example: type metadata ** -** This is a hand written header to be included into the final program to -** define types that will be used to layout the metadata tables created by the -** generator. +** This is a hand written header to be included into the final program. It +** defines the types used to layout the generated tables of metadata. ** ** This file *does not* get included into the generator itself. ** diff --git a/examples/type_metadata/type_info_final_program.c b/examples/type_metadata/type_info_final_program.c index ac00754..2ccfafc 100644 --- a/examples/type_metadata/type_info_final_program.c +++ b/examples/type_metadata/type_info_final_program.c @@ -31,7 +31,7 @@ struct V2F32 int main(int argc, char **argv) { - + // TODO(allen): write example final program return(0); } diff --git a/examples/type_metadata/type_metadata.c b/examples/type_metadata/type_metadata.c index 6799984..f3ae63a 100644 --- a/examples/type_metadata/type_metadata.c +++ b/examples/type_metadata/type_metadata.c @@ -1,7 +1,44 @@ /* ** Example: type metadata ** -** TODO full commentary +** This example is full of commentary on strategies for setting up Metadesk +** programs. There are many many ways a system like this could be built, +** this example only demonstrates one way. Everything here should be taken as +** our best attempt to pass on insights about using Metadesk, and not as the +** "one true way". +** +** This example shows what a typical Metadesk based metaprogram for generating +** type metadata looks like. Metadesk can be used for all sorts of other +** purposes, managing data tables, authoring content, configuration systems, +** and more, but a very common reason that a C programmer reaches for a +** metaprogramming system is to make up for C's lack of type metadata. +** +** The "Metadesk way" of solving this problem is to move the hand written type +** definitions into metadesk files, and to generate the C structs AND the +** tables for type metadata from the metaprogram. +** +** A more common approach is to mark up C types and create a custom parser +** for the modified C hybdrid. That approach requires a lot of heuristics to +** deal with the complex grammar of C code, and is especially hard to make +** both robust and reusable. The Metadesk way makes the problem a lot more +** simple, if you are comfortable with generating C types instead of writing +** them by hand in C. +** +** +** Files: +** type_metadata.h - This example is big enough that we pulled out the types +** and function declarations from the metaprogram to keep +** things organized. +** type_info.h - This header is included in the "final program" and +** defines the types that will form the tables of metdata. +** type_info_final_program.c - In addition to the metaprogram this example +** includes a "final program", i.e. one that depends on +** generated code. There is more commentary there. +** generated/* - This is the output folder where the generated files +** should be saved by the metaprogram. +** types.mdesk - Sample input for this metaprogram. The code generated +** from this metadesk file will be necessary to make +** type_info_final_program.c compile. ** */ diff --git a/examples/type_metadata/types.mdesk b/examples/type_metadata/types.mdesk index f47ed17..554788f 100644 --- a/examples/type_metadata/types.mdesk +++ b/examples/type_metadata/types.mdesk @@ -1,5 +1,7 @@ /* -** Setup as input to the type metadata example +** Example: type metadata +** +** Input for the type definition system setup by type_metadata.c */ @type(basic) U32: 4;