[examples] write examples directory

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

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.

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.

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

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.

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
 }

examples/type_metadata/type_metadata.h

@@ -1,5 +1,5 @@
 /*
-** Example: type-metadata
+** Example: type metadata
 **
 ** TODO full commentary
 **

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;
 
 

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:

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              <type>
+**  "arena" ** REQUIRED
+**   #define MD_IMPL_Arena              <type> (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