From 88dac53ae04d71b67a2be400c371a1f429e3d1f7 Mon Sep 17 00:00:00 2001
From: Kayne Ruse <kayneruse@gmail.com>
Date: Fri, 10 Mar 2023 08:41:58 +1100
Subject: [PATCH] Added toy.h, thanks for the suggestion GabrielGavrilov!

Resolved #72
---
 repl/repl_main.c    |  5 +---
 repl/repl_tools.c   |  6 ++--
 source/toy.h        | 67 +++++++++++++++++++++++++++++++++++++++++++++
 source/toy_common.h |  2 +-
 4 files changed, 72 insertions(+), 8 deletions(-)
 create mode 100644 source/toy.h

diff --git a/repl/repl_main.c b/repl/repl_main.c
index c7249a5..a3b64f6 100644
--- a/repl/repl_main.c
+++ b/repl/repl_main.c
@@ -6,10 +6,7 @@
 
 #include "toy_console_colors.h"
 
-#include "toy_lexer.h"
-#include "toy_parser.h"
-#include "toy_compiler.h"
-#include "toy_interpreter.h"
+#include "toy.h"
 
 #include <stdio.h>
 #include <stdlib.h>
diff --git a/repl/repl_tools.c b/repl/repl_tools.c
index e26b861..fd44bd7 100644
--- a/repl/repl_tools.c
+++ b/repl/repl_tools.c
@@ -78,10 +78,10 @@ const unsigned char* Toy_compileString(const char* source, size_t* size) {
 	Toy_initParser(&parser, &lexer);
 	Toy_initCompiler(&compiler);
 
-	//run the parser until the end of the source
+	//step 1 - run the parser until the end of the source
 	Toy_ASTNode* node = Toy_scanParser(&parser);
 	while(node != NULL) {
-		//pack up and leave
+		//on error, pack up and leave
 		if (node->type == TOY_AST_NODE_ERROR) {
 			Toy_freeASTNode(node);
 			Toy_freeCompiler(&compiler);
@@ -94,7 +94,7 @@ const unsigned char* Toy_compileString(const char* source, size_t* size) {
 		node = Toy_scanParser(&parser);
 	}
 
-	//get the bytecode dump
+	//step 2 - get the bytecode dump
 	const unsigned char* tb = Toy_collateCompiler(&compiler, size);
 
 	//cleanup
diff --git a/source/toy.h b/source/toy.h
new file mode 100644
index 0000000..4f146d6
--- /dev/null
+++ b/source/toy.h
@@ -0,0 +1,67 @@
+#pragma once
+
+/* toy.h - A Toy Programming Language
+
+If you're looking how to use Toy directly, try https://toylang.com/
+Otherwise, these headers may help learn how Toy works internally.
+
+*/
+
+/* utilities - these define a bunch of useful macros based on platform.
+
+The most important one is `TOY_API`, which highlights functions intended for the end user.
+
+*/
+
+#include "toy_common.h"
+#include "toy_console_colors.h"
+#include "toy_memory.h"
+
+/* core pipeline - from source to execution
+
+Each step is as follows:
+
+source   -> lexer       -> token
+token    -> parser      -> AST
+AST      -> compiler    -> bytecode
+bytecode -> interpreter -> result
+
+I should note that the parser -> compiler phase is actually made up of two steps - the write step
+and the collate step. See `Toy_compileString()` in `repl/repl_tools.c` for an example of how to compile
+properly.
+
+*/
+
+#include "toy_lexer.h"
+#include "toy_parser.h"
+#include "toy_compiler.h"
+#include "toy_interpreter.h"
+
+/* building block structures - the basic units of operation
+
+Literals represent any value within the language, including some internal ones that you never see.
+Literal Arrays are literally arrays within memory, and are the most heavily used structure in Toy.
+Literal Dictionaries are unordered key-value hashmaps, that use a running strategy for collisions.
+
+*/
+
+#include "toy_literal.h"
+#include "toy_literal_array.h"
+#include "toy_literal_dictionary.h"
+
+/* other components - you probably won't use these directly, but they're a good learning opportunity.
+
+`Toy_Scope` holds the variables of a specific scope within Toy - be it a script, a function, a block, etc.
+Scopes are also where the type system lives at runtime. They use identifier literals as keys, exclusively.
+
+`Toy_RefString` is a utility class that wraps traditional C strings, making them less memory intensive and
+faster to copy and move. In reality, since strings are considered immutable, multiple variables can point
+to the same string to save memory, and you can just create a new one of these vars pointing to the original
+rather than copying entirely for a speed boost. This module has it's own memory allocator system that is
+plugged into the main memory allocator.
+
+*/
+
+#include "toy_scope.h"
+#include "toy_refstring.h"
+
diff --git a/source/toy_common.h b/source/toy_common.h
index d4f73c2..ef18c43 100644
--- a/source/toy_common.h
+++ b/source/toy_common.h
@@ -6,7 +6,7 @@
 
 #define TOY_VERSION_MAJOR 1
 #define TOY_VERSION_MINOR 1
-#define TOY_VERSION_PATCH 1
+#define TOY_VERSION_PATCH 2
 #define TOY_VERSION_BUILD __DATE__ " " __TIME__
 
 //platform/compiler-specific instructions