From 8432125f5535538109b3b0787a755e8359a2a8f2 Mon Sep 17 00:00:00 2001 From: Allen Webster Date: Fri, 8 Oct 2021 11:08:51 -0700 Subject: [PATCH] [examples] write examples directory --- examples/examples_directory.txt | 62 +++++++++++++++++++ examples/intro/datadesk_like_template.c | 10 +-- examples/intro/parse_check.c | 2 +- examples/type_metadata/type_info.h | 2 +- .../type_metadata/type_info_final_program.c | 2 +- examples/type_metadata/type_metadata.c | 6 +- examples/type_metadata/type_metadata.h | 2 +- examples/user_errors/user_errors.c | 4 +- examples/user_errors/user_errors.mdesk | 2 +- source/md.c | 16 ++--- 10 files changed, 85 insertions(+), 23 deletions(-) create mode 100644 examples/examples_directory.txt diff --git a/examples/examples_directory.txt b/examples/examples_directory.txt new file mode 100644 index 0000000..d1a4c2f --- /dev/null +++ b/examples/examples_directory.txt @@ -0,0 +1,62 @@ +EXAMPLES: + + +1. "hello world" intro/hello_world.c + Just enough C code to setup a from-scratch metadesk program, parse + "hello world", and print the results. + + This example is a "build test", to make sure your compiler is finiding the + source files and can build them. + + +2. "parse check" intro/parse_check.c + An example utility that parses files specified on the command line, reports + any errors from the metadesk parser, and then prints the results. + + This example includes lots of notes about the basics of setting up a metadesk + parsing program from scratch, and getting used to the helpers in the library. + + +3. intro/hello_world.mdesk, intro/labels.mdes, intro/sets.mdesk + These files include examples of the features of the metadesk language. We + recommend putting these through the "parse check" example utility to see how + different language constructs get parsed, if you want to get more familiar + with the language side of metadesk. + + +4. "data desk like template" intro/data_desk_like_template.c + An example for users of Data Desk, the pre-cursor to Metadesk. + + +5. "user errors" user_errors/* + This example shows how you can mix in your own error reporting with the errors + that come back from the metadesk parser. + + +6. "type metadata" type_metadata/* + 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 + matches what a typical metadesk based metaprogram grows to look like over + time. It includes: + analyzing a metadesk parse tree + doing error checks + generating C types, functions, a data tables + generating type serialization metadata + generating enum string tables + generating enum mapping functions + printing diagnostics + including generated files into a final program + + Commentary in this example focuses on strategies for setting up an effective + metaprogram. + + +7. "overrides" integration/overrides.c + When including the Metadesk library into an existing codebase, the overrides + system in the library will let you plug in existing implementations you have + for many of the basic requirements of the library. This can also be useful if + you want to make your program CRT-free, or direct metadesk allocations to your + own custom allocator. + + diff --git a/examples/intro/datadesk_like_template.c b/examples/intro/datadesk_like_template.c index 73e530a..e11be85 100644 --- a/examples/intro/datadesk_like_template.c +++ b/examples/intro/datadesk_like_template.c @@ -1,13 +1,13 @@ /* -** Example: datadesk-like-template +** Example: data desk like template ** ** This example is setup as a copy-pastable template for creating metadesk ** based metaprograms that have the same structure as datadesk metaprograms. ** -** Datadesk was a precursor language to metadesk. This example is mostly meant -** to help datadesk users understand metadesk and migrate onto it. +** Data Desk was a precursor language to metadesk. This example is mostly meant +** to help Data Desk users understand metadesk and migrate onto it. ** -** A "datadesk-like" metaprogram is passed the input metacode files on the +** A "data-desk-like" metaprogram is passed the input metacode files on the ** command line. These files are parsed. Then a set of three user-defined ** functions that form the "custom layer" are called. The "custom layer" ** defines all the additional analysis and code generation. @@ -24,7 +24,7 @@ static MD_Arena *arena = 0; -//~ Declare user defined functions (the datadesk "custom layer") ////////////// +//~ Declare user defined functions (the data desk "custom layer") ////////////// static void Initialize(void); // Runs at the beginning of generation. static void TopLevel(MD_Node *node); // Runs once for each top-level node from each file. diff --git a/examples/intro/parse_check.c b/examples/intro/parse_check.c index 9bc7d16..e458f19 100644 --- a/examples/intro/parse_check.c +++ b/examples/intro/parse_check.c @@ -1,5 +1,5 @@ /* -** Example: parse-check +** Example: parse check ** ** This example shows how to use the metadesk library to parse metadesk files, ** print errors, and dump verbose feedback on the resulting metadesk trees. diff --git a/examples/type_metadata/type_info.h b/examples/type_metadata/type_info.h index 251b9b0..271d0e1 100644 --- a/examples/type_metadata/type_info.h +++ b/examples/type_metadata/type_info.h @@ -1,5 +1,5 @@ /* -** Example: type-metadata +** 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 diff --git a/examples/type_metadata/type_info_final_program.c b/examples/type_metadata/type_info_final_program.c index 27708bc..ac00754 100644 --- a/examples/type_metadata/type_info_final_program.c +++ b/examples/type_metadata/type_info_final_program.c @@ -1,5 +1,5 @@ /* -** Example: type-metadata +** Example: type metadata ** ** This file shows including the generated type information into a final ** program and using that type info to unpack a buffer of data. diff --git a/examples/type_metadata/type_metadata.c b/examples/type_metadata/type_metadata.c index 6aaa3a6..6799984 100644 --- a/examples/type_metadata/type_metadata.c +++ b/examples/type_metadata/type_metadata.c @@ -1,5 +1,5 @@ /* -** Example: type-metadata +** Example: type metadata ** ** TODO full commentary ** @@ -1152,7 +1152,8 @@ main(int argc, char **argv) fclose(c); } - // print state + // print diagnostics of the parse analysis +#if 0 for (GEN_TypeInfo *type = first_type; type != 0; type = type->next) @@ -1207,4 +1208,5 @@ main(int argc, char **argv) MD_S8VArg(map_case->out->string)); } } +#endif } diff --git a/examples/type_metadata/type_metadata.h b/examples/type_metadata/type_metadata.h index fcc62d3..204e52c 100644 --- a/examples/type_metadata/type_metadata.h +++ b/examples/type_metadata/type_metadata.h @@ -1,5 +1,5 @@ /* -** Example: type-metadata +** Example: type metadata ** ** TODO full commentary ** diff --git a/examples/user_errors/user_errors.c b/examples/user_errors/user_errors.c index ab52e74..10a00ee 100644 --- a/examples/user_errors/user_errors.c +++ b/examples/user_errors/user_errors.c @@ -1,5 +1,5 @@ /* -** Example: user-errors +** Example: user errors ** ** This example shows how to print custom error messages. ** @@ -10,8 +10,6 @@ #include "md.h" #include "md.c" -// @notes For simple single-threaded memory management in a run-once-and-exit -// utility, a single global arena is our recommended approach. static MD_Arena *arena = 0; diff --git a/examples/user_errors/user_errors.mdesk b/examples/user_errors/user_errors.mdesk index de010d2..35200dd 100644 --- a/examples/user_errors/user_errors.mdesk +++ b/examples/user_errors/user_errors.mdesk @@ -1,5 +1,5 @@ /* -** Setup as input to the user-errors example +** Setup as input to the "user errors" example */ @foo @bar Foo: diff --git a/source/md.c b/source/md.c index 1890159..6b19270 100644 --- a/source/md.c +++ b/source/md.c @@ -4,26 +4,26 @@ ** Overrides & Options Macros ** ** Overridable -** "memset" ** REQUIRED (default crt-based implementation) +** "memset" ** REQUIRED ** #define MD_IMPL_Memset (void*, int, uint64) -> void* ** #define MD_IMPL_Memmove (void*, void*, uint64) -> void* ** -** "file iteration" ** OPTIONAL (default for win32 and linux) +** "file iteration" ** OPTIONAL (required for the metadesk FileIter helpers to work) ** #define MD_IMPL_FileIterBegin (MD_FileIter*, MD_String8) -> Boolean ** #define MD_IMPL_FileIterNext (MD_Arena*, MD_FileIter*) -> MD_FileInfo ** #define MD_IMPL_FileIterEnd (MD_FileIter*) -> void ** -** "file load" ** OPTIONAL (default for win32 and linux) +** "file load" ** OPTIONAL (required for MD_ParseWholeFile to work) ** #define MD_IMPL_LoadEntireFile (MD_Arena*, MD_String8 filename) -> MD_String8 ** -** "low level memory" ** OPTIONAL (required for default arena) (default for win32 and linux) +** "low level memory" ** OPTIONAL (required when relying on the default arenas) ** #define MD_IMPL_Reserve (uint64) -> void* ** #define MD_IMPL_Commit (void*, uint64) -> MD_b32 ** #define MD_IMPL_Decommit (void*, uint64) -> void ** #define MD_IMPL_Release (void*, uint64) -> void ** -** "arena" ** REQUIRED (default available) -** #define MD_IMPL_Arena +** "arena" ** REQUIRED +** #define MD_IMPL_Arena (must set before including md.h) ** #define MD_IMPL_ArenaAlloc () -> MD_IMPL_Arena* ** #define MD_IMPL_ArenaRelease (MD_IMPL_Arena*) -> void ** #define MD_IMPL_ArenaGetPos (MD_IMPL_Arena*) -> uint64 @@ -32,12 +32,12 @@ ** #define MD_IMPL_ArenaSetAutoAlign (MD_IMPL_Arena*, uint64) -> void ** #define MD_IMPL_ArenaHeaderSize uint64 ** -** "scratch" ** REQUIRED (default available) +** "scratch" ** REQUIRED ** #define MD_IMPL_GetScratch (MD_IMPL_Arena**, uint64) -> MD_IMPL_Arena* ** "scratch constants" ** OPTIONAL (required for default scratch) ** #define MD_IMPL_ScratchCount uint64 [default 2] ** -** "sprintf" ** OPTIONAL (default available) +** "sprintf" ** REQUIRED ** #define MD_IMPL_Vsnprintf (char*, uint64, char const*, va_list) -> uint64 ** ** Default Implementation Controls