194 lines
7.5 KiB
Plaintext
194 lines
7.5 KiB
Plaintext
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<boolean>
|
|
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<boolean> | 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<boolean>
|
|
|
|
// 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(...)
|