151 lines
5.1 KiB
Plaintext
151 lines
5.1 KiB
Plaintext
Heading 2 Document API
|
|
class mt-12
|
|
|
|
Heading 3 NewTerraceDocument()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| reader | [Reader](#reader) | An interface that reads lines from a document.
|
|
| indent | rune | The character used for indentation in the document. Only a single character is permitted.
|
|
| **@returns** | *TerraceDocument | A pointer to a TerraceDocument, which is an iterator for parsing a document line by line.
|
|
|
|
Provides a simple set of convenience functions around ParseLine for more ergonomic parsing of Terrace documents.
|
|
CodeBlock go
|
|
// Function Definition
|
|
func NewTerraceDocument(reader Reader, indent rune) *TerraceDocument
|
|
|
|
// Import Path
|
|
import "terrace.go"
|
|
|
|
Heading 3 TerraceDocument
|
|
class mb-4 mt-12
|
|
Markdown
|
|
Container for a handful of convenience functions for parsing documents.
|
|
Obtained from [NewTerraceDocument()](#newterracedocument) above
|
|
CodeBlock go
|
|
// Type Definition
|
|
type TerraceDocument struct {
|
|
// ... (private fields)
|
|
}
|
|
|
|
Heading 3 TerraceDocument.Next()
|
|
class mb-4 mt-12
|
|
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | (*TerraceNode, error) | Returns a pointer to the next TerraceNode and an error. The error is `io.EOF` at the end of the document.
|
|
|
|
Advances the current position in the terrace document and returns the next node.
|
|
|
|
Returns `io.EOF` upon reaching the end of the document.
|
|
|
|
Intended to be used inside a for loop to parse a section of a Terrace document.
|
|
|
|
CodeBlock go
|
|
// Method Definition
|
|
func (d *TerraceDocument) Next() (*TerraceNode, error)
|
|
|
|
// Import Path
|
|
import "terrace.go"
|
|
|
|
// Usage
|
|
doc := terrace.NewTerraceDocument(...)
|
|
for {
|
|
node, err := doc.Next()
|
|
if err == io.EOF {
|
|
break
|
|
}
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
// Do something with each node.
|
|
}
|
|
|
|
Heading 3 TerraceNode
|
|
class mb-4 mt-12
|
|
Markdown
|
|
Represents a single node/line in a Terrace document.
|
|
CodeBlock go
|
|
// Type Definition
|
|
type TerraceNode struct {
|
|
// ... (private fields)
|
|
}
|
|
|
|
Heading 3 TerraceNode.Level()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | int | The indent level of the current node
|
|
|
|
Returns the number of indent characters of the current node.
|
|
|
|
Given the following document, `Level()` would return 0, 1, 2, and 5 respectively for each line.
|
|
CodeBlock terrace
|
|
block
|
|
block
|
|
block
|
|
block
|
|
|
|
CodeBlock go
|
|
// Method Definition
|
|
func (n *TerraceNode) Level() int
|
|
|
|
Heading 3 TerraceNode.Content()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | string | The line contents starting from the first non-indent character.
|
|
|
|
Get a string with the current line contents. Skips all indent characters.
|
|
|
|
Given the following document
|
|
CodeBlock terrace
|
|
root
|
|
sub-line
|
|
Markdown
|
|
- Calling `Content()` on the second line returns "sub-line", trimming off the leading indent characters.
|
|
|
|
CodeBlock go
|
|
// Method Definition
|
|
func (n *TerraceNode) Content() string
|
|
|
|
Heading 3 TerraceNode.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()` returns "title"
|
|
CodeBlock terrace
|
|
title An Important Document
|
|
CodeBlock go
|
|
// Method Definition
|
|
func (n *TerraceNode) Head() string
|
|
|
|
Heading 3 TerraceNode.Tail()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | string | The remainder of the line following the `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()`
|
|
|
|
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()` returns "An Important Document"
|
|
CodeBlock terrace
|
|
title An Important Document
|
|
CodeBlock go
|
|
// Method Definition
|
|
func (n *TerraceNode) Tail() string |