297 lines
11 KiB
Plaintext
297 lines
11 KiB
Plaintext
Heading 2 Document API
|
|
class mt-12
|
|
|
|
Heading 3 TerraceDocument::new()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| reader | impl [Reader](#reader) | An object that implements the Reader trait for reading lines.
|
|
| indent | char | The character used for indentation in the document. Only a single character is permitted.
|
|
| **@returns** | [TerraceDocument](#terrace-document) | An async iterator for parsing a Terrace document line by line.
|
|
|
|
Creates a new TerraceDocument with the specified reader and indentation character.
|
|
This is the main entry point for parsing Terrace documents.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub fn new<R: Reader + Send + Sync + 'static>(reader: R, indent: char) -> Self
|
|
|
|
// Import Path
|
|
use terrace::{TerraceDocument, StringReader};
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config\n database\n host localhost");
|
|
let mut doc = TerraceDocument::new(reader, ' ');
|
|
|
|
Heading 3 TerraceDocument::with_reader()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| reader | impl [Reader](#reader) | An object that implements the Reader trait for reading lines.
|
|
| **@returns** | [TerraceDocument](#terrace-document) | An async iterator for parsing a Terrace document with default space indentation.
|
|
|
|
Creates a new TerraceDocument with the specified reader and default space (' ') indentation.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub fn with_reader<R: Reader + Send + Sync + 'static>(reader: R) -> Self
|
|
|
|
// Import Path
|
|
use terrace::{TerraceDocument, StringReader};
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config\n database\n host localhost");
|
|
let mut doc = TerraceDocument::with_reader(reader);
|
|
|
|
Heading 3 TerraceDocument
|
|
class mb-4 mt-12
|
|
Markdown
|
|
The main document iterator that provides async access to parsed Terrace nodes.
|
|
Use this for ergonomic document parsing with automatic memory management and async iteration.
|
|
|
|
CodeBlock rust
|
|
// Struct Definition
|
|
pub struct TerraceDocument {
|
|
// Implementation details...
|
|
}
|
|
|
|
Heading 3 TerraceDocument::next()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | Option<[TerraceNode](#terrace-node)> | The next parsed node in the document, or None if the document has ended.
|
|
|
|
Advances to the next line in the document and returns a parsed TerraceNode.
|
|
This method is async and should be called in an async context.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub async fn next(&mut self) -> Option<TerraceNode>
|
|
|
|
// Import Path
|
|
use terrace::{TerraceDocument, StringReader};
|
|
|
|
// Usage
|
|
let reader = StringReader::new("line1\n line2\nline3");
|
|
let mut doc = TerraceDocument::with_reader(reader);
|
|
|
|
while let Some(node) = doc.next().await {
|
|
println!("Level: {}, Content: '{}'", node.level(), node.content());
|
|
}
|
|
|
|
Heading 3 TerraceNode
|
|
class mb-4 mt-12
|
|
Markdown
|
|
Represents a single parsed line/node in a Terrace document.
|
|
Provides convenient access to different parts of the parsed line.
|
|
|
|
CodeBlock rust
|
|
// Struct Definition
|
|
#[derive(Debug, Clone)]
|
|
pub struct TerraceNode {
|
|
// Implementation details...
|
|
}
|
|
|
|
Heading 3 TerraceNode::head()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | &str | The head portion of the node (text before the first space).
|
|
|
|
Returns the first word or identifier of the line.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub fn head(&self) -> &str
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config database localhost");
|
|
let mut doc = TerraceDocument::with_reader(reader);
|
|
|
|
if let Some(node) = doc.next().await {
|
|
assert_eq!(node.head(), "config");
|
|
}
|
|
|
|
Heading 3 TerraceNode::tail()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | &str | The tail portion of the node (text after the first space).
|
|
|
|
Returns everything after the first space character in the line.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub fn tail(&self) -> &str
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config database localhost");
|
|
let mut doc = TerraceDocument::with_reader(reader);
|
|
|
|
if let Some(node) = doc.next().await {
|
|
assert_eq!(node.tail(), "database localhost");
|
|
}
|
|
|
|
Heading 3 TerraceNode::content()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | &str | The full content of the node after indentation.
|
|
|
|
Returns the complete text content of the line, excluding the indentation characters.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub fn content(&self) -> &str
|
|
|
|
// Usage
|
|
let reader = StringReader::new(" config database localhost");
|
|
let mut doc = TerraceDocument::with_reader(reader);
|
|
|
|
if let Some(node) = doc.next().await {
|
|
assert_eq!(node.content(), "config database localhost");
|
|
assert_eq!(node.level(), 2);
|
|
}
|
|
|
|
Heading 3 TerraceNode::level()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | usize | The indentation level of the node.
|
|
|
|
Returns the number of indentation characters at the beginning of the line.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub fn level(&self) -> usize
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config\n database\n host localhost");
|
|
let mut doc = TerraceDocument::with_reader(reader);
|
|
|
|
let levels: Vec<usize> = doc.map(|node| node.level()).await;
|
|
assert_eq!(levels, vec![0, 1, 2]);
|
|
|
|
Heading 3 TerraceNode::is()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| value | &str | The value to compare against the node's head.
|
|
| **@returns** | bool | True if the node's head matches the given value.
|
|
|
|
Convenience method to check if the node's head matches a specific value.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub fn is(&self, value: &str) -> bool
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config\n database\n server");
|
|
let mut doc = TerraceDocument::with_reader(reader);
|
|
|
|
if let Some(node) = doc.next().await {
|
|
assert!(node.is("config"));
|
|
assert!(!node.is("database"));
|
|
}
|
|
|
|
Heading 3 TerraceDocument::collect()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| **@returns** | Vec<[TerraceNode](#terrace-node)> | A vector containing all nodes in the document.
|
|
|
|
Collects all nodes from the document into a vector for batch processing.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub async fn collect(mut self) -> Vec<TerraceNode>
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config\n database\n host localhost");
|
|
let doc = TerraceDocument::with_reader(reader);
|
|
|
|
let nodes = doc.collect().await;
|
|
assert_eq!(nodes.len(), 3);
|
|
assert_eq!(nodes[0].head(), "config");
|
|
assert_eq!(nodes[1].head(), "database");
|
|
assert_eq!(nodes[2].head(), "host");
|
|
|
|
Heading 3 TerraceDocument::filter()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| predicate | F | A closure that takes a &TerraceNode and returns bool.
|
|
| **@returns** | Vec<[TerraceNode](#terrace-node)> | A vector containing only nodes that match the predicate.
|
|
|
|
Filters nodes based on a predicate function.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub async fn filter<F>(mut self, predicate: F) -> Vec<TerraceNode>
|
|
where
|
|
F: FnMut(&TerraceNode) -> bool,
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config\n database\n server\n database");
|
|
let doc = TerraceDocument::with_reader(reader);
|
|
|
|
let databases = doc.filter(|node| node.head() == "database").await;
|
|
assert_eq!(databases.len(), 2);
|
|
|
|
Heading 3 TerraceDocument::find()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| predicate | F | A closure that takes a &TerraceNode and returns bool.
|
|
| **@returns** | Option<[TerraceNode](#terrace-node)> | The first node that matches the predicate, or None.
|
|
|
|
Finds the first node that matches a predicate function.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub async fn find<F>(mut self, predicate: F) -> Option<TerraceNode>
|
|
where
|
|
F: FnMut(&TerraceNode) -> bool,
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config\n database\n server");
|
|
let doc = TerraceDocument::with_reader(reader);
|
|
|
|
let server_node = doc.find(|node| node.head() == "server").await;
|
|
assert!(server_node.is_some());
|
|
assert_eq!(server_node.unwrap().head(), "server");
|
|
|
|
Heading 3 TerraceDocument::map()
|
|
class mb-4 mt-12
|
|
Markdown
|
|
| Parameter | Type | Description
|
|
| -------------- | --------------------- | -----------------------------------------------------------------------
|
|
| mapper | F | A closure that takes a TerraceNode and returns a value of type T.
|
|
| **@returns** | Vec<T> | A vector containing the mapped values.
|
|
|
|
Transforms each node using a mapper function.
|
|
|
|
CodeBlock rust
|
|
// Function Signature
|
|
pub async fn map<F, T>(mut self, mapper: F) -> Vec<T>
|
|
where
|
|
F: FnMut(TerraceNode) -> T,
|
|
|
|
// Usage
|
|
let reader = StringReader::new("config\n database\n server");
|
|
let doc = TerraceDocument::with_reader(reader);
|
|
|
|
let heads: Vec<String> = doc.map(|node| node.head().to_string()).await;
|
|
assert_eq!(heads, vec!["config", "database", "server"]);
|