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"]);