Heading 2 Document API class mt-12 Heading 3 useDocument() class mb-4 mt-12 Markdown | Parameter | Type | Description | -------------- | --------------------- | ----------------------------------------------------------------------- | reader | [Reader](#reader) | When called, resolves to a string containing the next line in the document. | indent | string | The character used for indentation in the document. Only a single character is permitted. | **@returns** | [Document](#document) | A set of convenience functions for iterating through and parsing a document line by line. Provides a simple set of convenience functions around parseLine for more ergonomic parsing of Terrace documents. CodeBlock typescript // Type Definition function useDocument (reader: Reader, indent: string = ' '): Document // Import Path import { useDocument } from '@terrace-lang/js/document' Heading 3 Document class mb-4 mt-12 Markdown Container for a handful of convenience functions for parsing documents. Obtained from [useDocument()](#usedocument) above CodeBlock typescript // Type Definition type Document = { next: (levelScope?: number) => Promise level: () => number, line: (startOffset?: number) => string, head: () => string, tail: () => string, match: (matchHead: string) => boolean } Heading 3 Document.next() class mb-4 mt-12 Markdown | Parameter | Type | Description | -------------- | --------------------- | ----------------------------------------------------------------------- | levelScope | number = -1 | If specified, `next()` will return `false` when it encounters a line with a level at or below `levelScope` | **@returns** | Promise | Returns `true` after parsing a line, or `false` 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 `true` after parsing the next line, or `false` upon reaching the end of the document. If the `levelScope` parameter is provided, `next()` will return `false` 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. 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 typescript // Type Definition next: (levelScope?: number) => Promise // Import Path import { useDocument } from '@terrace-lang/js/document' // Usage const { next } = useDocument(...) while (await next()) { // Do something with each line. } Heading 3 Document.level() class mb-4 mt-12 Markdown | Parameter | Type | Description | -------------- | --------------------- | ----------------------------------------------------------------------- | **@returns** | number | The indent level of the current line Returns the number of indent characters of the current line. Given the following document, `level()` would return 0, 1, 2, and 5 respectively for each line. CodeBlock terrace block block block block CodeBlock typescript // Type Definition level: () => number // Usage import { useDocument } from '@terrace-lang/js/document' const { level } = useDocument(...) Heading 3 Document.line() class mb-4 mt-12 Markdown | Parameter | Type | Description | -------------- | --------------------- | ----------------------------------------------------------------------- | levelScope | startOffset = [level()](#document-level) | How many indent characters to skip before outputting the line contents. Defaults to the current indent level | **@returns** | string | The line contents starting from `startOffset` Get a string with the current line contents. Skips all indent characters by default, but this can be configured with `startOffset` Given the following document CodeBlock terrace root sub-line Markdown - Calling `line()` on the second line returns "sub-line", trimming off the leading indent characters. - Calling `line(0)` however, returns "    sub-line", with all four leading spaces. `startOffset` is primarily used for parsing blocks that have literal indented multi-line text, such as markdown. CodeBlock typescript // Type Definition line: (startOffset?: number) => string // Usage import { useDocument } from '@terrace-lang/js/document' const { line } = useDocument(...) Heading 3 Document.head() class mb-4 mt-12 Markdown | Parameter | Type | Description | -------------- | --------------------- | ----------------------------------------------------------------------- | **@returns** | string | The `head` portion (first word) of a line Get 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. Terrace DSLs do not *need* to use head-tail line structure, but support for them is built into the parser Given the following line, [head()](#document-head) returns "title" CodeBlock terrace title An Important Document CodeBlock typescript // Type Definition head: () => string // Usage import { useDocument } from '@terrace-lang/js/document' const { head } = useDocument(...) Heading 3 Document.tail() class mb-4 mt-12 Markdown | Parameter | Type | Description | -------------- | --------------------- | ----------------------------------------------------------------------- | **@returns** | string | The remainder of the line following the [head()](#document-head) portion, with no leading space Get all text following the first "word" of a line, starting from the first character after the space at the end of [head()](#document-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, [tail()](#document-tail) returns "An Important Document" CodeBlock terrace title An Important Document CodeBlock typescript // Type Definition tail: () => string // Usage import { useDocument } from '@terrace-lang/js/document' const { tail } = useDocument(...) Heading 3 Document.match() class mb-4 mt-12 Markdown | Parameter | Type | Description | -------------- | --------------------- | ----------------------------------------------------------------------- | matchValue | string | A string to check against [head()](#document-head) for equality | **@returns** | boolean | Whether the current [head()](#document-head) matches the passed value Quickly check if the current line head matches a specified value Shorthand for `matchValue === head()` Given the following line CodeBlock terrace title An Important Document Markdown - `match('title')` returns `true` - `match('somethingElse`) returns `false` CodeBlock typescript // Type Definition match: (matchValue: string) => boolean // Usage import { useDocument } from '@terrace-lang/js/document' const { match } = useDocument(...)