modules/pod/parser.zzm

NAME

pod/parser - Parse POD into DOM-like node objects.

SYNOPSIS

  from pod/parser import parse_pod, load_pod, PodParser;
  from std/io import Path;

  let doc := parse_pod("=head1 NAME\n\nExample\n\n=cut\n");
  say( doc.first_by_type("heading").text() );

  let same := load_pod( new Path("lib/example.zzm") );
  let parser := new PodParser();
  let again := parser.parse(same);

DESCRIPTION

This pure-Zuzu module parses Plain Old Documentation blocks from either a string or a std/io Path. It ignores non-POD source text outside POD regions and assembles the documentation into mutable DOM-like objects.

The returned object is a PodDocument. Its children are PodNode objects. Nodes expose methods for DOM traversal, inspection, and manipulation, including children, child, append_child, remove_child, descendants, find_by_type, and text_content.

Paragraph nodes are unwrapped while parsing: a blank line starts a new paragraph, but a single newline inside paragraph text is treated as a soft wrap and becomes one space. Verbatim/code blocks preserve their line breaks.

EXPORTED FUNCTIONS

• parse_pod(String|Path source)

  Parse POD from a string, or slurp and parse UTF-8 POD from a Path. Returns: PodDocument.

• parse_pod_string(String text)

  Parse POD from a string. Returns: PodDocument.

• load_pod(Path path)

  Slurp UTF-8 POD from a Path and parse it. Returns: PodDocument.

EXPORTED CLASSES

• PodDocument

  The root document node.

• PodNode

  A mutable DOM node. Constructors are public so callers can build and manipulate additional nodes when needed.

• PodParser

  Small OO wrapper with parse, parse_string, and load methods.

COPYRIGHT AND LICENCE

pod/parser is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.