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

259
docs/src/docs/c.tce
View File

@@ -16,8 +16,8 @@ Section light
Markdown
Documentation is available for the following languages:
- [C](/docs/c/) - 10% Complete
- [JavaScript](/docs/javascript/) - 50% Complete
- [C](/docs/c/) - 75% Complete
- [JavaScript](/docs/javascript/) - 75% Complete
- [Python](/docs/python/) - 0% Complete
Heading 2 Getting Started
@@ -81,9 +81,18 @@ Section light
Heading 2 Core API
class mt-12
Markdown
**Note:** The Core API is designed for maximum portability and is not intended to be directly consumed.
For most projects you'll want to use the [Document API](#document-api) instead.
It provides an ergonomic wrapper around the Core API and lets you focus on parsing
your documents.
Heading 3 terrace_linedata_t
class my-6
class mb-4 mt-12
Markdown
This struct holds information about each line as it is parsed. Mutated each time [terrace_parse_line()](#terrace-parse-line) is called. Not intended to be used directly.
Use the relevant `terrace_` functions from the [Document API](#document-api) instead.
CodeBlock c
// Holds the parsed information from each line.
typedef struct terrace_linedata_s {
@@ -98,10 +107,248 @@ Section light
unsigned int offsetTail;
} terrace_linedata_t;
Heading 3 terrace_parse_line()
class my-6
Heading 3 terrace_create_linedata()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| indent | const char | The character used for indentation in the document. Only a single character is permitted.
| **@returns** | [terrace_linedata_t](#terrace-linedatat) | A terrace_linedata_t struct with the specified indent character and all other values initialized to 0.
Initialize a [terrace_linedata](#terrace-linedatat) struct with default values to pass to [terrace_parse_line()](#terrace-parse-line).
CodeBlock c
void terrace_parse_line(char* line, terrace_linedata_t *lineData)
// Call Signature
terrace_linedata_t terrace_create_linedata(const char indent)
Heading 3 terrace_parse_line()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| line | char* | A pointer to the line to parse as a C-style string. Shouldn't end with a newline.
| lineData | [terrace_linedata_t](#terrace-linedatat)* | A pointer to the terrace_linedata_t struct to store information about the current line in.
Core Terrace parser function, sets `level`, `offsetHead`, and `offsetTail` in a [terrace_linedata](#terrace-linedatat) struct based on the current line.
CodeBlock c
// Call Signature
void terrace_parse_line(const char* line, terrace_linedata_t* lineData)
Heading 2 Document API
class mt-12
Heading 3 terrace_document_t
class mb-4 mt-12
Markdown
Tracks state of a document while being parsed.
Obtained from [terrace_create_document()](#terrace-create-document) below
CodeBlock c
// Type Definition
typedef struct terrace_document_s {
// == Internal State == //
unsigned int _repeatCurrentLine;
// Current line being read
char* _currentLine;
// == External Information == //
// Embedded line data struct. Holds information about the current parsed line
terrace_linedata_t lineData;
// Custom data passed to the readline function
void* userData;
/**
* Line reader function, provided by the user
* Needed to get the next line inside of `terrace_next(doc)`
* @param {char**} line First argument is a pointer to `_currentLine`, above
* @param {void*} userData Second argument is `userData`, above
* @returns {int} The number of characters read, or -1 if no characters were read.
*/
int (*reader)(char** line, void* userData);
} terrace_document_t;
Heading 3 terrace_create_document()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| indent | const char | The indent character to use. Generally a single space character.
| reader | int (\*reader)(char** line, void* userData) | A function pointer to a function that reads lines sequentially from a user-provided source. Receives a pointer to `lineData->_currLine`, and `userData`, supplied in the next argument.
| userData | void * | A user-supplied pointer to any state information needed by their reader function. Passed to `reader`each time it is called.
| **@returns** | [terrace_document_t](#terrace-documentt) | A state struct needed by the convenience functions below.
Initializes the state needed for the convenience functions below. Takes a user-supplied `reader` function to read each line from a user-determined source.
CodeBlock c
// Call Signature
terrace_document_t terrace_create_document(const char indent, int (*reader)(char** line, void* userData), void* userData)
Heading 3 terrace_next()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| doc | [terrace_document_t*](#terrace-documentt) | A pointer to the current document state struct.
| levelScope | int | 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.
Advances the current position in the terrace document and populates lineData
with the parsed information from that line.
Returns `1` after parsing the next line, or `0` upon reaching the end of the document.
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 `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.
Intended to be used inside a while loop to parse a section of a Terrace document.
CodeBlock c
// Call Signature
char terrace_next(terrace_document_t* doc, int levelScope)
// Usage
while(terrace_next(doc, -1)) {
// Do something with each line.
}
Heading 3 terrace_level()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| doc | [terrace_document_t*](#terrace-documentt) | A pointer to the current document state struct.
| **@returns** | unsigned int | The indent level of the current line
Returns the number of indent characters of the current line.
Given the following document, `terrace_level(doc)` would return 0, 1, 2, and 5 respectively for each line.
CodeBlock terrace
block
block
block
block
CodeBlock c
// Call Signature
unsigned int terrace_level(terrace_document_t* doc)
// Usage
while(terrace_next(doc, -1)) {
printf("Indent Level: %u", terrace_level(doc));
}
Heading 3 terrace_line()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| doc | [terrace_document_t*](#terrace-documentt) | A pointer to the current document state struct.
| startOffset | int | 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`
Get a string with the current line contents.
If `startOffset` is -1, skips all indent characters by default. Otherwise only skips the amount specified.
Given the following document
CodeBlock terrace
root
sub-line
Markdown
- Calling `terrace_line(doc, -1)` on the second line returns "sub-line", trimming off the leading indent characters.
- Calling `terrace_line(doc, 0)` however, returns "    sub-line", with all four leading spaces.
`startOffset`s other than `-1` are primarily used for parsing blocks that have literal indented multi-line text
CodeBlock c
// Call Signature
char* terrace_line(terrace_document_t* doc, int startOffset)
// Usage
while(terrace_next(doc, -1)) {
printf("Line with indent characters: %s", terrace_line(doc, 0));
printf("Line without indent characters: %s", terrace_line(doc, -1));
}
Heading 3 terrace_head_length()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| doc | [terrace_document_t*](#terrace-documentt) | A pointer to the current document state struct.
| **@returns** | unsigned int | The length of the `head` portion (first word) of a line
Get the *length* of the first "word" of a line,
starting from the first non-indent character to the first space or end of the line
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.
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.
Terrace DSLs do not *need* to use head-tail line structure, but support for them is built into the parser
Given the following line, `terrace_head_length(doc)` returns `5`
CodeBlock terrace
title An Important Document
CodeBlock c
// Call Signature
unsigned int terrace_head_length(terrace_document_t* doc)
// Usage
while(terrace_next(doc, -1)) {
printf("Head length: %u", terrace_head_length(doc));
}
Heading 3 terrace_tail()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| doc | [terrace_document_t*](#terrace-documentt) | A pointer to the current document state struct.
| **@returns** | char* | The remainder of the line following the `head` portion, with no leading space.
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`.
Terrace DSLs do not *need* to use head-tail line structure, but support for them is built into the parser
Given the following line, `terrace_tail(doc)` returns "An Important Document"
CodeBlock terrace
title An Important Document
CodeBlock c
// Call Signature
char* terrace_tail(terrace_document_t* doc)
// Usage
while(terrace_next(doc, -1)) {
printf("Line tail: %s", terrace_tail(doc));
}
Heading 3 terrace_match()
class mb-4 mt-12
Markdown
| Parameter | Type | Description
| -------------- | --------------------- | -----------------------------------------------------------------------
| doc | [terrace_document_t*](#terrace-documentt) | A pointer to the current document state struct.
| matchValue | const char* | 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.
Quickly check if the current line head matches a specified value. Useful in many document-parsing situations.
Given the following line:
CodeBlock terrace
title An Important Document
Markdown
- `terrace_match(doc, "title")` returns `1`
- `terrace_match(doc, "somethingElse")` returns `0`
CodeBlock c
// Call Signature
char terrace_match(terrace_document_t* doc, const char* matchHead)
// Usage
while(terrace_next(doc, -1)) {
printf("Does the line start with 'title': %d", terrace_match(doc, "title"));
}
Heading 2 Recipes
class mt-12

2
docs/src/docs/javascript.tce
View File

@@ -16,7 +16,7 @@ Section light
Markdown
Documentation is available for the following languages:
- [C](/docs/c/) - 10% Complete
- [C](/docs/c/) - 75% Complete
- [JavaScript](/docs/javascript/) - 75% Complete
- [Python](/docs/python/) - 0% Complete