thederf/Terrace
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Make more progress on package configuration, fill out C docs.

Browse Source
This commit is contained in:
Joshua Bemenderfer
2023-02-21 22:35:53 -05:00
parent fb90f825ed
commit 3b7077e761
19 changed files with 872 additions and 275 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
packages/c/document.h
View File

@@ -3,6 +3,7 @@
#include "parser.h"
// Tracks state of a given while being parsed.
typedef struct terrace_document_s {
// == Internal State == //
unsigned int _repeatCurrentLine;
@@ -37,7 +38,7 @@ terrace_document_t terrace_create_document(const char indent, int (*reader)(char
terrace_document_t document = {
._repeatCurrentLine = 0,
._currentLine = 0,
.lineData = terrace_create_line_data(indent),
.lineData = terrace_create_linedata(indent),
.reader = reader,
.userData = userData
};
@@ -56,6 +57,7 @@ terrace_document_t terrace_create_document(const char indent, int (*reader)(char
* block
* block
* ```
* @param {terrace_document_t*} doc A pointer to the Terrace document being parsed
* @returns {unsigned int} The indent level of the current line
*/
unsigned int terrace_level(terrace_document_t* doc) {
@@ -64,7 +66,7 @@ unsigned int terrace_level(terrace_document_t* doc) {
/**
* Get a string with the current line contents
* If `startOffset` is -1, skips all indent characters by default. Otherwise only skips the amount specified
* If `startOffset` is -1, skips all indent characters by default. Otherwise only skips the amount specified.
*
* Given the following document
*
@@ -78,7 +80,7 @@ unsigned int terrace_level(terrace_document_t* doc) {
* `startOffset`s other than `-1` are primarily used for parsing blocks that have literal indented multi-line text
*
* @param {terrace_document_t*} doc A pointer to the Terrace document being parsed
* @param {int} startOffset How many indent characters to skip before outputting the line contents. Defaults to the current indent level
* @param {int} startOffset How many indent characters to skip before outputting the line contents. If set to -1, uses the current indent level.
* @returns {char*} The line contents starting from `startOffset`
*/
char* terrace_line(terrace_document_t* doc, int startOffset) {
@@ -92,7 +94,7 @@ char* terrace_line(terrace_document_t* doc, int startOffset) {
* Often used for deciding how to parse a block.
*
* Because C uses NULL-terminated strings, we cannot easily slice a string to return something out of the middle.
* Instead, `terrace_head_length` provides the length of the head portion.
* Instead, `terrace_head_length()` provides the length of the head portion.
* In combination with `doc->lineData.offsetHead`, you can copy the head section into a new string,
* or use any number of `strn*` C stdlib functions to work with the head section without copying it.
*
@@ -103,16 +105,16 @@ char* terrace_line(terrace_document_t* doc, int startOffset) {
* ```terrace
* title An Important Document
* ```
* @param {terrace_document_t*} doc A pointer to the Terrace document being parsed
* @param {terrace_document_t*} doc A pointer to the current document state struct.
* @returns {int} The length of the `head` portion (first word) of a line
*/
int terrace_head_length(terrace_document_t* doc) {
unsigned int terrace_head_length(terrace_document_t* doc) {
return doc->lineData.offsetTail - doc->lineData.offsetHead;
}
/**
* Get a char pointer to everything following the first "word" of a line,
* starting from the first character after the space at the end of `head`
* starting from the first character after the space at the end of `head`.
*
* Terrace DSLs do not *need* to use head-tail line structure, but support for them is built into the parser
*
@@ -121,8 +123,8 @@ int terrace_head_length(terrace_document_t* doc) {
* ```terrace
* title An Important Document
* ```
* @param {terrace_document_t*} doc A pointer to the Terrace document being parsed
* @returns {char*} The remainder of the line following the `head` portion, with no leading space
* @param {terrace_document_t*} doc A pointer to the current document state struct.
* @returns {char*} The remainder of the line following the `head` portion, with no leading space.
*/
char* terrace_tail(terrace_document_t* doc) {
return doc->_currentLine + doc->lineData.offsetTail + 1;
@@ -131,7 +133,7 @@ char* terrace_tail(terrace_document_t* doc) {
/**
* Quickly check if the current line head matches a specified value. Useful in many document-parsing situations.
*
* Given the following line
* Given the following line:
*
* ```terrace
* title An Important Document
@@ -140,8 +142,9 @@ char* terrace_tail(terrace_document_t* doc) {
* `terrace_match(doc, "title")` returns `1`
* `terrace_match(doc, "somethingElse") returns `0`
*
* @param {const char*} matchValue A string to check against the line `head` for equality
* @returns {char} A byte set to 0 if the head does not match, or 1 if it does match
* @param {terrace_document_t*} doc A pointer to the current document state struct.
* @param {const char*} matchValue A string to check against the line `head` for equality.
* @returns {char} A byte set to 0 if the head does not match, or 1 if it does match.
*/
char terrace_match(terrace_document_t* doc, const char* matchHead) {
// Get a pointer to the start of the head portion of the string.
@@ -168,7 +171,7 @@ char terrace_match(terrace_document_t* doc, const char* matchHead) {
* If the `levelScope` parameter is not -1, `terrace_next()` will also return `0` when it encounters a line
* with a level at or below `levelScope`. This allows you to iterate through subsections of a document.
*
* If a lower-level line was encountered, the following call to `next()` will repeat this line again.
* If a lower-level line was encountered, the following call to `terrace_next()` will repeat this line again.
* This allows a child loop to look forward, determine that the next line will be outside its purview,
* and return control to the calling loop transparently without additional logic.
*
@@ -179,7 +182,7 @@ char terrace_match(terrace_document_t* doc, const char* matchHead) {
* // Do something with each line.
* }
* ```
*
* @param {terrace_document_t*} doc A pointer to the current document state struct.
* @param {number} levelScope If set above -1, `next()` will return `0` when it encounters a line with a level at or below `levelScope`
* @returns {char} Returns `1` after parsing a line, or `0` if the document has ended or a line at or below `levelScope` has been encountered.
*/
@@ -209,4 +212,4 @@ char terrace_next(terrace_document_t* doc, int levelScope) {
return 1;
}
#endif
#endif