Wrote Toy_Lexer, Toy_Parser API

c-api/toy_ast_node_h.md

@@ -0,0 +1,12 @@
+# toy_ast_node.h
+
+This header defines the structure of the nodes used in the Abstract Syntax Tree, known as `Toy_ASTNode`. Most of what is defined here is intended for internal use, so is not documented here.
+
+This header doesn't need to be included directly, as it is included in [toy_parser.h](c-api/toy_parser_h.md).
+
+## Defined Functions
+
+### void Toy_freeASTNode(Toy_ASTNode* node)
+
+This function cleans up any valid instance of `Toy_ASTNode` pointer passed to it. It is most commonly used to clean up the values returned by `Toy_scanParser`, after they have been passsed to `Toy_writeCompiler`, or when the node is an error node.
+

c-api/toy_lexer_h.md

@@ -0,0 +1,10 @@
+# toy_lexer.h
+
+This header defines the structure `Toy_Lexer`, which can be bound to a piece of source code, and used to tokenize it within a parser.
+
+## Defined Functions
+
+### void Toy_initLexer(Toy_Lexer* lexer, const char* source)
+
+This function initializes a lexer, binding it to the `source` parameter; the lexer is now ready to be passed to the parser.
+

c-api/toy_parser_h.md

@@ -0,0 +1,68 @@
+# toy_parser.h
+
+This header defines the structure `Toy_Parser` which, after being initialized with a `Toy_Lexer` produces a series of abstract syntax trees to be passed to the `Toy_Compiler`. The following is a utility function provided by [repl_tools.h](c-api/repl_tools_h.md), demonstrating how to use the parser.
+
+```c
+//generate bytecode from a given string
+const unsigned char* Toy_compileString(const char* source, size_t* size) {
+    //declare the relevant instances
+	Toy_Lexer lexer;
+	Toy_Parser parser;
+	Toy_Compiler compiler;
+
+    //initialize each of them
+	Toy_initLexer(&lexer, source);
+	Toy_initParser(&parser, &lexer);
+	Toy_initCompiler(&compiler);
+
+    //when the parser returns NULL, it is finished
+	Toy_ASTNode* node = Toy_scanParser(&parser);
+	while(node != NULL) {
+		//if the parser returns an error node, clean up and exit gracefully
+		if (node->type == TOY_AST_NODE_ERROR) {
+			Toy_freeASTNode(node);
+			Toy_freeCompiler(&compiler);
+			Toy_freeParser(&parser);
+            //no need to clean the lexer
+			return NULL;
+		}
+
+        //write the node to the compiler
+		Toy_writeCompiler(&compiler, node);
+		Toy_freeASTNode(node);
+
+        //grab the next node
+		node = Toy_scanParser(&parser);
+	}
+
+	//get the bytecode to be returned
+	const unsigned char* tb = Toy_collateCompiler(&compiler, size);
+
+	//cleanup
+	Toy_freeCompiler(&compiler);
+	Toy_freeParser(&parser);
+	//no need to clean the lexer
+
+	//finally
+	return tb;
+}
+```
+
+This header also includes [toy_ast_node.h](c-api/toy_ast_node_h.md), so the `Toy_freeASTNode` function can also be used.
+
+## Defined Functions
+
+### void Toy_initParser(Toy_Parser* parser, Toy_Lexer* lexer)
+
+This function initializes a `Toy_Parser`, binding the given `Toy_Lexer` to it.
+
+### void Toy_freeParser(Toy_Parser* parser)
+
+This function frees a `Toy_Parser` once its task is completed.
+
+### Toy_ASTNode* Toy_scanParser(Toy_Parser* parser)
+
+This function returns an abstract syntax tree representing part of the program, or an error node. The abstract syntax tree must be passed to `Toy_writeCompiler` and/or `Toy_freeASTNode`.
+
+This function should be called repeatedly until it returns `NULL`, indicating the end of the program.
+

index.md

@@ -58,13 +58,14 @@ print tally(); //3
 * [Testing Toy](deep-dive/testing-toy)
 * [Roadmap](deep-dive/roadmap)
 
-# Full C API
+# Public C API
 
-* [toy_ast_node.h]
+* [repl_tools.h]
+* [toy_ast_node.h](c-api/toy_ast_node_h.md)
 * [toy_common.h](c-api/toy_common_h.md)
 * [toy_compiler.h]
 * [toy_interpreter.h]
-* [toy_lexer.h]
+* [toy_lexer.h](c-api/toy_lexer_h.md)
 * [toy_literal_array.h]
 * [toy_literal_dictionary.h]
 * [toy_literal.h]