cayaml 0.1.0.dev3__py3-none-any.whl → 0.1.1__py3-none-any.whl

cayaml/__init__.py

@@ -1,168 +1,29 @@
-"""
-Minimal YAML Parser and Unparser
-
-This module provides a very basic YAML parser and unparser that supports a subset
-of YAML syntax (mappings and sequences, with simple scalars). It uses only Python's
-built-in libraries and is intended for simple use cases.
-
-Usage:
-    data = parse_yaml(yaml_string)
-    yaml_string = unparse_yaml(data)
-"""
-
-
-def get_indent(line):
-    """Return the number of leading spaces in a line."""
-    return len(line) - len(line.lstrip(" "))
-
-
-def parse_scalar(value):
-    """Convert a scalar string into int, float, bool, None or leave as string."""
-    # Remove quotes if present
-    if (value.startswith('"') and value.endswith('"')) or (
-        value.startswith("'") and value.endswith("'")
-    ):
-        return value[1:-1]
-    lower = value.lower()
-    if lower == "true":
-        return True
-    if lower == "false":
-        return False
-    if lower in ["null", "~"]:
-        return None
-    try:
-        return int(value)
-    except ValueError:
-        pass
-    try:
-        return float(value)
-    except ValueError:
-        pass
-    return value
-
-
-def parse_mapping(lines, indent):
-    """Parse a block of lines representing a mapping."""
-    mapping = {}
-    while lines and get_indent(lines[0]) >= indent:
-        if get_indent(lines[0]) != indent:
-            break
-        line = lines.pop(0)
-        # Ignore comment lines
-        if line.strip().startswith("#"):
-            continue
-        if ":" not in line:
-            continue  # Skip lines that do not look like key: value pairs
-        key, _, value = line.strip().partition(":")
-        key = key.strip()
-        value = value.strip()
-        if value == "":
-            # If no inline value, check if a nested block follows.
-            if lines and get_indent(lines[0]) > indent:
-                value, _ = parse_block(lines, get_indent(lines[0]))
-            else:
-                value = None
-        else:
-            value = parse_scalar(value)
-        mapping[key] = value
-    return mapping
-
-
-def parse_list(lines, indent):
-    """Parse a block of lines representing a list."""
-    lst = []
-    while (
-        lines and get_indent(lines[0]) == indent and lines[0].lstrip().startswith("-")
-    ):
-        line = lines.pop(0)
-        # Remove the dash marker and get the content.
-        content = line.lstrip()[1:].strip()
-        if content == "":
-            # If nothing follows the dash, check for an indented block.
-            if lines and get_indent(lines[0]) > indent:
-                item, _ = parse_block(lines, get_indent(lines[0]))
-            else:
-                item = None
-        else:
-            item = parse_scalar(content)
-            # If the next line is indented more, treat it as a nested block.
-            if lines and get_indent(lines[0]) > indent:
-                extra, _ = parse_block(lines, get_indent(lines[0]))
-                # If the inline value is a mapping, merge the extra block.
-                if isinstance(item, dict) and isinstance(extra, dict):
-                    item.update(extra)
-                else:
-                    item = extra
-        lst.append(item)
-    return lst
-
-
-def parse_block(lines, indent):
-    """Determine if the current block is a list or mapping and parse accordingly."""
-    if not lines:
-        return None, lines
-    # If the current line starts with a dash, treat as a list; otherwise, a mapping.
-    if lines[0].lstrip().startswith("-"):
-        result = parse_list(lines, indent)
-    else:
-        result = parse_mapping(lines, indent)
-    return result, lines
-
-
-def parse_yaml(yaml_str):
-    """
-    Parse a YAML string and return the corresponding Python data structure.
-    Supports a minimal subset of YAML.
-    """
-    lines = yaml_str.splitlines()
-    # Remove completely blank lines.
-    lines = [line for line in lines if line.strip() != ""]
-    result, _ = parse_block(lines, 0)
-    return result
-
-
-def format_scalar(value):
-    """Format a scalar value as a YAML string."""
-    if value is None:
-        return "null"
-    if isinstance(value, bool):
-        return "true" if value else "false"
-    if isinstance(value, (int, float)):
-        return str(value)
-    if isinstance(value, str):
-        # Quote the string if it contains spaces or special characters.
-        if not value or any(c in value for c in [" ", ":", "-", "#"]):
-            escaped = value.replace('"', '\\"')
-            return f'"{escaped}"'
-        return value
-    return str(value)
-
-
-def unparse_yaml(data, indent=0):
-    """
-    Convert a Python data structure into a YAML-formatted string.
-    Supports a minimal subset of YAML.
-    """
-    lines = []
-    prefix = " " * indent
-    if isinstance(data, dict):
-        for key, value in data.items():
-            if isinstance(value, (dict, list)):
-                lines.append(f"{prefix}{key}:")
-                lines.append(unparse_yaml(value, indent + 2))
-            else:
-                lines.append(f"{prefix}{key}: {format_scalar(value)}")
-    elif isinstance(data, list):
-        for item in data:
-            if isinstance(item, (dict, list)):
-                lines.append(f"{prefix}-")
-                lines.append(unparse_yaml(item, indent + 2))
-            else:
-                lines.append(f"{prefix}- {format_scalar(item)}")
-    else:
-        lines.append(f"{prefix}{format_scalar(data)}")
-    return "\n".join(lines)
-
-
-# Public API
-__all__ = ["parse_yaml", "unparse_yaml"]
+from .api import (
+    load,
+    loads,
+    dump,
+    dumps,
+    load_all,
+    loads_all,
+    round_trip_load,
+    round_trip_loads,
+    round_trip_dump,
+    round_trip_dumps,
+    round_trip_load_all,
+    round_trip_loads_all,
+)
+
+__all__ = [
+    "load",
+    "loads",
+    "dump",
+    "dumps",
+    "load_all",
+    "loads_all",
+    "round_trip_load",
+    "round_trip_loads",
+    "round_trip_dump",
+    "round_trip_dumps",
+    "round_trip_load_all",
+    "round_trip_loads_all",
+]

cayaml/api.py

@@ -0,0 +1,150 @@
+"""
+api.py - Public API for Cayaml
+
+This module exports two sets of functions (plain mode vs. round-trip mode),
+plus additional "_all" variants for multi-document loading:
+
+Plain mode (single doc):
+  - loads(yaml_str)
+  - load(file_obj)
+  - dumps(data)
+  - dump(data, file_obj)
+
+Plain mode (multi-doc):
+  - loads_all(yaml_str)
+  - load_all(file_obj)
+
+Round-trip mode (single doc):
+  - round_trip_loads(yaml_str)
+  - round_trip_load(file_obj)
+  - round_trip_dumps(data)
+  - round_trip_dump(data, file_obj)
+
+Round-trip mode (multi-doc):
+  - round_trip_loads_all(yaml_str)
+  - round_trip_load_all(file_obj)
+"""
+
+from .parser import _internal_parse_stream, _internal_to_ast
+from .unparser import _internal_dump_plain, _internal_dump_round_trip
+from .plain_conversion import to_plain
+from .ast_nodes import Node, YamlStream
+
+
+# -----------------------------
+# Plain mode (single-document)
+# -----------------------------
+def loads(yaml_str: str):
+    """
+    Parse a YAML string (plain mode) and return plain Python objects (dict, list, scalars).
+    If multiple documents exist, this returns only the first one.
+    """
+    docs = loads_all(yaml_str)
+    return docs[0] if docs else None
+
+
+def load(file_obj):
+    """
+    Parse YAML from a file-like object (plain mode) and return plain Python objects.
+    If multiple documents exist, this returns only the first one.
+    """
+    yaml_str = file_obj.read()
+    return loads(yaml_str)
+
+
+def dumps(data) -> str:
+    """
+    Convert plain Python objects into a YAML-formatted string (without preserving formatting metadata).
+    """
+    if not isinstance(data, Node):
+        data = _internal_to_ast(data)
+    return _internal_dump_plain(data)
+
+
+def dump(data, file_obj):
+    """
+    Dump plain Python objects to a file-like object as YAML.
+    """
+    file_obj.write(dumps(data))
+
+
+# -----------------------------
+# Plain mode (multi-document)
+# -----------------------------
+def loads_all(yaml_str: str):
+    """
+    Parse a YAML string in plain mode.
+    Return a list of plain Python objects, one per document in the stream.
+    """
+    yaml_stream = _internal_parse_stream(yaml_str)
+    if not isinstance(yaml_stream, YamlStream):
+        # If for some reason only one doc was found, wrap it in a list
+        return [to_plain(yaml_stream)]
+    return [to_plain(doc) for doc in yaml_stream.documents]
+
+
+def load_all(file_obj):
+    """
+    Parse YAML from a file-like object in plain mode.
+    Return a list of plain Python objects, one per document.
+    """
+    yaml_str = file_obj.read()
+    return loads_all(yaml_str)
+
+
+# --------------------------------
+# Round-trip mode (single-doc)
+# --------------------------------
+def round_trip_loads(yaml_str: str):
+    """
+    Parse a YAML string in round-trip mode (preserving formatting).
+    If multiple documents exist, returns only the first one.
+    """
+    docs = round_trip_loads_all(yaml_str)
+    return docs[0] if docs else None
+
+
+def round_trip_load(file_obj):
+    """
+    Round-trip from a file-like object.
+    If multiple docs, returns only the first one.
+    """
+    yaml_str = file_obj.read()
+    return round_trip_loads(yaml_str)
+
+
+def round_trip_dumps(data) -> str:
+    """
+    Convert the AST (or plain objects -> AST) to YAML, preserving formatting.
+    """
+    if not isinstance(data, Node):
+        data = _internal_to_ast(data)
+    return _internal_dump_round_trip(data)
+
+
+def round_trip_dump(data, file_obj):
+    """
+    Dump the AST to a file, preserving formatting.
+    """
+    file_obj.write(round_trip_dumps(data))
+
+
+# --------------------------------
+# Round-trip mode (multi-doc)
+# --------------------------------
+def round_trip_loads_all(yaml_str: str):
+    """
+    Parse a YAML string in round-trip mode, returning multiple docs as a list of DocumentNodes.
+    """
+    yaml_stream = _internal_parse_stream(yaml_str)
+    if isinstance(yaml_stream, YamlStream):
+        return yaml_stream.documents
+    return [yaml_stream]
+
+
+def round_trip_load_all(file_obj):
+    """
+    Parse from a file in round-trip mode, returning multiple docs as DocumentNodes.
+    """
+    yaml_str = file_obj.read()
+    return round_trip_loads_all(yaml_str)

cayaml/ast_nodes.py

@@ -0,0 +1,221 @@
+# ast_nodes.py - Updated with equality methods for SequenceNode (and MappingNode)
+
+
+class Node:
+    """
+    Base class for all YAML AST nodes.
+
+    Attributes:
+        leading_comments (list of str): Comments preceding this node.
+        trailing_comments (list of str): Comments following this node.
+        tag (str or None): YAML tag/type hint (e.g., "!!str", "!CustomTag").
+        anchor (str or None): Anchor name if this node is anchored (e.g., &anchorName).
+        alias_of (str or None): If this node is an alias (e.g., *anchorName), this stores the referenced anchor name.
+    """
+
+    def __init__(self):
+        self.leading_comments = []  # Comments before the node
+        self.trailing_comments = []  # Comments after the node
+        self.tag = None
+        self.anchor = None
+        self.alias_of = None
+
+    def is_alias(self):
+        return self.alias_of is not None
+
+    def has_anchor(self):
+        return self.anchor is not None
+
+    def __repr__(self):
+        return (
+            f"<{self.__class__.__name__} tag={self.tag!r} "
+            f"anchor={self.anchor!r} alias_of={self.alias_of!r}>"
+        )
+
+
+class DocumentNode(Node):
+    """
+    Represents a single YAML document.
+
+    Attributes:
+        root (Node): The root node of the document (MappingNode, SequenceNode, or ScalarNode).
+        has_doc_start (bool): True if the document start marker '---' was encountered.
+        has_doc_end (bool): True if the document end marker '...' was encountered.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.root = None
+        self.has_doc_start = False
+        self.has_doc_end = False
+
+    def __getitem__(self, key):
+        if self.root and isinstance(self.root, MappingNode):
+            return self.root[key]
+        raise TypeError("DocumentNode does not contain a subscriptable mapping")
+
+    def __setitem__(self, key, value):
+        if self.root and isinstance(self.root, MappingNode):
+            self.root[key] = value
+        else:
+            raise TypeError("DocumentNode does not contain a subscriptable mapping")
+
+    def __eq__(self, other):
+        # If other is a DocumentNode, compare all attributes.
+        if isinstance(other, DocumentNode):
+            return (
+                self.has_doc_start == other.has_doc_start
+                and self.has_doc_end == other.has_doc_end
+                and self.leading_comments == other.leading_comments
+                and self.trailing_comments == other.trailing_comments
+                and self.root == other.root
+            )
+        # Otherwise, delegate equality to the root node.
+        return self.root == other
+
+    def __repr__(self):
+        return (
+            f"<DocumentNode doc_start={self.has_doc_start} "
+            f"doc_end={self.has_doc_end} root={self.root!r}>"
+        )
+
+
+class MappingNode(Node):
+    """
+    Represents a YAML mapping (key-value pairs) while preserving key order and merge operators.
+
+    Attributes:
+        pairs (list of tuple(Node, Node)): An ordered list of (key, value) node pairs.
+        merges (list of Node): A list of nodes specified by merge operators (<<:), if any.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.pairs = []  # List of tuples: (key_node, value_node)
+        self.merges = []  # Nodes merged via the '<<' operator
+
+    def add_pair(self, key_node, value_node):
+        self.pairs.append((key_node, value_node))
+
+    def __getitem__(self, key):
+        for k, v in self.pairs:
+            if hasattr(k, "value") and k.value == key:
+                # For plain scalars (no block style, no comments, etc.), return the raw value.
+                if isinstance(v, ScalarNode) and v.style is None:
+                    return v.value
+                return v
+        raise KeyError(key)
+
+    def __setitem__(self, key, value):
+        for i, (k, _) in enumerate(self.pairs):
+            if hasattr(k, "value") and k.value == key:
+                self.pairs[i] = (k, value)
+                return
+        new_key = ScalarNode(key)
+        self.add_pair(new_key, value)
+
+    def __eq__(self, other):
+        if isinstance(other, MappingNode):
+            return self.pairs == other.pairs
+        elif isinstance(other, dict):
+            converted = {}
+            for k, v in self.pairs:
+                key = k.value if hasattr(k, "value") else k
+                # For scalar nodes, use the unboxed value.
+                if isinstance(v, ScalarNode):
+                    converted[key] = v.value
+                else:
+                    converted[key] = v
+            return converted == other
+        return False
+
+    def __repr__(self):
+        return f"<MappingNode pairs={self.pairs!r} merges={self.merges!r}>"
+
+
+class SequenceNode(Node):
+    """
+    Represents a YAML sequence (an ordered list of items).
+
+    Attributes:
+        items (list of Node): The sequence items.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.items = []
+
+    def add_item(self, item_node):
+        self.items.append(item_node)
+
+    def __eq__(self, other):
+        if isinstance(other, SequenceNode):
+            return self.items == other.items
+        elif isinstance(other, list):
+            # Convert items: if an item is a ScalarNode, compare its value; otherwise, compare the item directly.
+            converted = [
+                item.value if hasattr(item, "value") else item for item in self.items
+            ]
+            return converted == other
+        return False
+
+    def __repr__(self):
+        return f"<SequenceNode items={self.items!r}>"
+
+
+class ScalarNode(Node):
+    """
+    Represents a YAML scalar value (string, int, float, etc.) and captures block style details.
+
+    Attributes:
+        value: The scalar value.
+        style (str or None): The style of the scalar. Options include:
+                             None for plain scalars, '|' for literal, '>' for folded.
+        chomping (str or None): The chomping indicator for block scalars ('+', '-', or None).
+        lines (list of str or None): The original lines of a block scalar for precise re-emission.
+    """
+
+    def __init__(self, value, style=None):
+        super().__init__()
+        self.value = value
+        self.style = style  # None, '|', or '>' (plain, literal, folded)
+        self.chomping = None
+        self.lines = None
+
+    def __repr__(self):
+        return (
+            f"<ScalarNode value={self.value!r} style={self.style!r} tag={self.tag!r}>"
+        )
+
+    def __eq__(self, other):
+        if isinstance(other, ScalarNode):
+            return (
+                self.value == other.value
+                and self.style == other.style
+                and self.tag == other.tag
+            )
+        else:
+            return self.value == other
+
+
+class YamlStream:
+    """
+    Represents an entire YAML stream which may contain multiple documents.
+
+    Attributes:
+        documents (list of DocumentNode): The list of documents in the stream.
+    """
+
+    def __init__(self):
+        self.documents = []
+
+    def add_document(self, doc: DocumentNode):
+        self.documents.append(doc)
+
+    def __eq__(self, other):
+        if not isinstance(other, YamlStream):
+            return False
+        return self.documents == other.documents
+
+    def __repr__(self):
+        return f"<YamlStream documents={self.documents!r}>"

cayaml/parser.py

@@ -0,0 +1,350 @@
+"""
+parser.py - YAML parser for Cayaml (Swarmauri's Canon YAML)
+
+This minimal parser tokenizes YAML input and builds an AST (using node classes from ast_nodes.py).
+It preserves basic metadata such as document markers and comments.
+Advanced features (anchors, aliases, block styles, etc.) can be added by expanding these functions.
+
+This module exposes two internal functions:
+  - _internal_load(yaml_str): Returns an AST representing the YAML input.
+  - _internal_to_ast(data): Converts plain Python data into an AST.
+"""
+
+import math
+from .ast_nodes import YamlStream, DocumentNode, MappingNode, SequenceNode, ScalarNode
+
+
+def parse_scalar(value: str):
+    """
+    Convert a scalar string into int, float, bool, None, or leave as string.
+    This function also strips quotes if present.
+    """
+    value = value.strip()
+    # Remove quotes if present:
+    if (value.startswith('"') and value.endswith('"')) or (
+        value.startswith("'") and value.endswith("'")
+    ):
+        return value[1:-1]
+
+    lower = value.lower()
+    # Handle booleans
+    if lower == "true":
+        return True
+    if lower == "false":
+        return False
+
+    # Handle null
+    if lower in ("null", "~"):
+        return None
+
+    # Handle special float values
+    if lower in (".inf", "+.inf"):
+        return math.inf
+    if lower == "-.inf":
+        return -math.inf
+    if lower == ".nan":
+        return math.nan
+
+    # Try to parse int (base=0 helps with 0x, 0o, etc.)
+    try:
+        return int(value, 0)
+    except ValueError:
+        pass
+
+    # Try float
+    try:
+        return float(value)
+    except ValueError:
+        pass
+
+    return value
+
+
+def _internal_parse_stream(yaml_str: str) -> YamlStream:
+    """
+    Tokenize and parse a YAML string, returning a YamlStream (which may have multiple DocumentNodes).
+    """
+    lines = yaml_str.splitlines()
+    return parse_stream(lines)
+
+
+def _internal_load(yaml_str: str):
+    """
+    Parse a YAML string and return an AST.
+    If there is only one document, return that DocumentNode;
+    otherwise, return a YamlStream containing multiple DocumentNodes.
+    """
+    lines = yaml_str.splitlines()
+    stream = parse_stream(lines)
+    if len(stream.documents) == 1:
+        return stream.documents[0]
+    return stream
+
+
+def _internal_to_ast(data):
+    """
+    Convert plain Python data (dict, list, or scalar) into our AST.
+    """
+    from .ast_nodes import MappingNode, SequenceNode, ScalarNode
+
+    if isinstance(data, dict):
+        node = MappingNode()
+        for key, value in data.items():
+            key_node = ScalarNode(key)
+            value_node = _internal_to_ast(value)
+            node.add_pair(key_node, value_node)
+        return node
+    elif isinstance(data, list):
+        node = SequenceNode()
+        for item in data:
+            node.add_item(_internal_to_ast(item))
+        return node
+    else:
+        return ScalarNode(data)
+
+
+def parse_stream(lines: list) -> YamlStream:
+    """
+    Parse the entire YAML stream (which may contain multiple documents).
+    Returns a YamlStream object containing DocumentNode(s).
+    """
+    stream = YamlStream()
+    i = 0
+    n = len(lines)
+
+    while i < n:
+        # Skip any leading blank lines
+        while i < n and not lines[i].strip():
+            i += 1
+        if i >= n:
+            break
+
+        doc = DocumentNode()
+        line = lines[i].strip()
+
+        # Check if we see a doc start marker
+        if line.startswith("---"):
+            doc.has_doc_start = True
+            i += 1
+
+        # Collect lines for *this* document until we see '...' or '---'
+        doc_lines = []
+        while i < n:
+            curr = lines[i].rstrip("\n")
+            curr_strip = curr.strip()
+            if curr_strip.startswith("..."):
+                doc.has_doc_end = True
+                i += 1
+                break
+            if curr_strip.startswith("---"):
+                # Start of next doc
+                break
+            doc_lines.append(curr)
+            i += 1
+
+        # If we have lines for this document, parse them as a block
+        if doc_lines:
+            doc.root, _ = parse_block(doc_lines, indent=0)
+        stream.add_document(doc)
+
+    return stream
+
+
+def parse_block(lines: list, indent: int):
+    """
+    Decide whether the block is a mapping or a sequence, then parse.
+    Returns (Node, remaining_lines).
+    """
+    # Skip blank or comment lines to see what's next
+    trimmed = skip_blank_and_comment(lines)
+    if not trimmed:
+        return None, []
+
+    first_line = trimmed[0].lstrip()
+    if first_line.startswith("-"):
+        return parse_sequence(lines, indent)
+    else:
+        return parse_mapping(lines, indent)
+
+
+def parse_mapping(lines: list, indent: int):
+    """
+    Parse a block of lines as a mapping.
+    Returns (MappingNode, remaining_lines).
+    """
+    print("DEBUG parse_mapping lines:", repr(lines), "indent=", indent)
+    mapping = MappingNode()
+    i = 0
+    n = len(lines)
+
+    while i < n:
+        line = lines[i]
+        line_strip = line.strip()
+
+        # Check current indentation of this line
+        current_indent = len(line) - len(line.lstrip())
+
+        # If line is blank or has less indent, we break out of this mapping
+        if not line_strip or current_indent < indent:
+            break
+
+        # If it's a full-line comment at this level, store as leading comment
+        if line.lstrip().startswith("#"):
+            mapping.leading_comments.append(line_strip)
+            i += 1
+            continue
+
+        # If no colon, we presumably have reached a new block or item
+        if ":" not in line_strip:
+            break
+
+        # Split key : value
+        key_part, _, value_part = line_strip.partition(":")
+        key_node = ScalarNode(parse_scalar(key_part.strip()))
+
+        # Move to next line to see if there's nested content or block scalars
+        i += 1
+        raw_value = value_part.strip()
+
+        # -- Block scalar check (| or >) --
+        if raw_value in ("|", ">"):
+            style_char = raw_value  # '|' or '>'
+            block_node = ScalarNode(None, style=style_char)
+            block_node.lines = []
+
+            # Determine the indentation level of the block content from the
+            # first line following the block indicator. YAML treats that
+            # indentation as significant for the entire block, so we capture it
+            # and strip exactly that amount from each subsequent line.
+
+            block_indent = None
+            while i < n:
+                next_line = lines[i]
+                next_line_indent = len(next_line) - len(next_line.lstrip())
+                if next_line_indent <= current_indent or not next_line.strip():
+                    break
+                if block_indent is None:
+                    block_indent = next_line_indent
+                if next_line_indent < block_indent:
+                    break
+                block_node.lines.append(next_line[block_indent:])
+                i += 1
+
+            value_node = block_node
+
+        # If value part is empty => The actual value is on subsequent lines
+        elif not raw_value:
+            nested_lines = []
+            while i < n:
+                nl = lines[i]
+                nl_indent = len(nl) - len(nl.lstrip())
+                if nl_indent <= current_indent or not nl.strip():
+                    break
+                nested_lines.append(nl)
+                i += 1
+
+            if nested_lines:
+                value_node, _ = parse_block(nested_lines, indent=current_indent + 1)
+            else:
+                value_node = ScalarNode("")
+        else:
+            # Normal scalar
+            value_node = ScalarNode(parse_scalar(raw_value))
+
+        mapping.add_pair(key_node, value_node)
+
+    remaining = lines[i:]
+    return mapping, remaining
+
+
+def parse_sequence(lines: list, indent: int):
+    """
+    Parse a block of lines as a sequence.
+    Returns (SequenceNode, remaining_lines).
+    """
+    sequence = SequenceNode()
+    i = 0
+    n = len(lines)
+
+    while i < n:
+        line = lines[i]
+        line_strip = line.strip()
+        current_indent = len(line) - len(line.lstrip())
+
+        if not line_strip or current_indent < indent:
+            break
+
+        if line.lstrip().startswith("#"):
+            sequence.leading_comments.append(line_strip)
+            i += 1
+            continue
+
+        if not line_strip.startswith("-"):
+            break
+
+        # Remove leading dash
+        dash_part = line_strip[1:].strip()  # everything after '-'
+        i += 1
+
+        # If dash_part is '|' or '>', we have a block scalar in a sequence item
+        if dash_part in ("|", ">"):
+            style_char = dash_part
+            block_node = ScalarNode(None, style=style_char)
+            block_node.lines = []
+
+            # As with mappings, determine the indentation for the block scalar
+            # from the first line that follows the indicator. Each subsequent
+            # line must be at least that indented; anything less signals the end
+            # of the block.
+
+            block_indent = None
+            while i < n:
+                nxt = lines[i]
+                nxt_indent = len(nxt) - len(nxt.lstrip())
+                if nxt_indent <= current_indent or not nxt.strip():
+                    break
+                if block_indent is None:
+                    block_indent = nxt_indent
+                if nxt_indent < block_indent:
+                    break
+                block_node.lines.append(nxt[block_indent:])
+                i += 1
+
+            sequence.add_item(block_node)
+
+        elif not dash_part:
+            # Possibly nested structure
+            nested_lines = []
+            while i < n:
+                nested_line = lines[i]
+                nested_indent = len(nested_line) - len(nested_line.lstrip())
+                if nested_indent <= current_indent or not nested_line.strip():
+                    break
+                nested_lines.append(nested_line)
+                i += 1
+
+            if nested_lines:
+                item_node, _ = parse_block(nested_lines, indent=current_indent + 1)
+            else:
+                item_node = ScalarNode("")
+            sequence.add_item(item_node)
+        else:
+            # Normal scalar or inline text after '-'
+            item_node = ScalarNode(parse_scalar(dash_part))
+            sequence.add_item(item_node)
+
+    remaining = lines[i:]
+    return sequence, remaining
+
+
+def skip_blank_and_comment(lines: list):
+    """
+    Return the subset of lines starting with the first non-blank, non-comment line.
+    """
+    i = 0
+    while i < len(lines):
+        if not lines[i].strip() or lines[i].lstrip().startswith("#"):
+            i += 1
+        else:
+            break
+    return lines[i:]

cayaml/plain_conversion.py

@@ -0,0 +1,60 @@
+"""
+plain_conversion.py - Helpers to convert Cayaml AST nodes to plain Python objects.
+
+This module provides the `to_plain()` function which recursively traverses
+the AST (returned by the round-trip loader) and converts each node into its plain
+Python equivalent. For example:
+  - DocumentNode and MappingNode are converted to dictionaries.
+  - SequenceNode is converted to a list.
+  - ScalarNode is converted to its underlying value.
+If the node is a YamlStream containing multiple documents, a list of plain objects is returned.
+"""
+
+from .ast_nodes import DocumentNode, MappingNode, SequenceNode, ScalarNode, YamlStream
+
+
+def to_plain(node):
+    """
+    Recursively convert the given AST node into plain Python objects.
+
+    Parameters:
+        node: An AST node (DocumentNode, MappingNode, SequenceNode, or ScalarNode)
+              or a YamlStream.
+
+    Returns:
+        The equivalent plain Python data structure (dict, list, scalar) for that node.
+    """
+    # If node is a YamlStream, return a list of plain objects, one per document.
+    if isinstance(node, YamlStream):
+        return [to_plain(doc) for doc in node.documents]
+
+    # If node is a DocumentNode, return the plain version of its root.
+    if isinstance(node, DocumentNode):
+        if node.root is not None:
+            return to_plain(node.root)
+        else:
+            return {}
+
+    # If node is a MappingNode, convert its pairs into a dictionary.
+    if isinstance(node, MappingNode):
+        result = {}
+        for key_node, value_node in node.pairs:
+            # Convert the key: if it's a ScalarNode, use its value; otherwise, convert recursively.
+            key = (
+                key_node.value
+                if isinstance(key_node, ScalarNode)
+                else to_plain(key_node)
+            )
+            result[key] = to_plain(value_node)
+        return result
+
+    # If node is a SequenceNode, convert each item recursively.
+    if isinstance(node, SequenceNode):
+        return [to_plain(item) for item in node.items]
+
+    # If node is a ScalarNode, return its underlying value.
+    if isinstance(node, ScalarNode):
+        return node.value
+
+    # Fallback: if the node is already a plain Python object or unknown type.
+    return node

cayaml/unparser.py

@@ -0,0 +1,229 @@
+"""
+unparser.py - YAML unparser for Cayaml (Swarmauri's Canon YAML)
+
+This module traverses the AST (constructed using ast_nodes.py) and
+reconstructs a YAML-formatted string.
+
+It provides two internal dump functions:
+  - _internal_dump_plain(node, indent=0): Emits plain YAML (ignoring extra formatting metadata).
+  - _internal_dump_round_trip(node, indent=0): Emits YAML preserving document markers,
+    comments, anchors/tags, block styles (folded/literal), merge operators, and key order.
+
+If the input to dumps() is a plain Python structure (list, dict, or scalar),
+we convert it to an AST before emitting YAML.
+"""
+
+from .ast_nodes import (
+    DocumentNode,
+    MappingNode,
+    SequenceNode,
+    ScalarNode,
+    Node,
+)
+
+
+# Helper for plain mode scalar conversion.
+def _plain_scalar(node: ScalarNode) -> str:
+    val = node.value
+    if isinstance(val, bool):
+        return "true" if val else "false"
+    elif val is None:
+        return "null"
+    elif isinstance(val, (int, float)):
+        return str(val)
+    elif isinstance(val, str):
+        # Quote if needed.
+        if not val or any(c in val for c in [" ", ":", "-", "#"]):
+            return '"' + val.replace('"', '\\"') + '"'
+        return val
+    else:
+        return str(val)
+
+
+# ====================
+# Round-Trip Dumping
+# ====================
+def _internal_dump_round_trip(node: Node, indent: int = 0) -> str:
+    """Dump the AST node preserving formatting metadata."""
+    if isinstance(node, DocumentNode):
+        return unparse_document(node, indent)
+    elif isinstance(node, MappingNode):
+        return unparse_mapping(node, indent)
+    elif isinstance(node, SequenceNode):
+        return unparse_sequence(node, indent)
+    elif isinstance(node, ScalarNode):
+        return unparse_scalar(node, indent)
+    else:
+        return " " * indent + str(node)
+
+
+def unparse_document(doc: DocumentNode, indent: int = 0) -> str:
+    """Unparse a DocumentNode into YAML text, preserving document markers and comments."""
+    lines = []
+    prefix = " " * indent
+    for comment in doc.leading_comments:
+        lines.append(prefix + comment)
+    if doc.has_doc_start:
+        lines.append(prefix + "---")
+    if doc.root is not None:
+        lines.append(unparse_node(doc.root, indent))
+    if doc.has_doc_end:
+        lines.append(prefix + "...")
+    for comment in doc.trailing_comments:
+        lines.append(prefix + comment)
+    return "\n".join(lines)
+
+
+def unparse_node(node: Node, indent: int = 0) -> str:
+    """Dispatch unparse based on node type (round-trip mode)."""
+    if isinstance(node, MappingNode):
+        return unparse_mapping(node, indent)
+    elif isinstance(node, SequenceNode):
+        return unparse_sequence(node, indent)
+    elif isinstance(node, ScalarNode):
+        return unparse_scalar(node, indent)
+    else:
+        return " " * indent + str(node)
+
+
+def unparse_mapping(mapping: MappingNode, indent: int = 0) -> str:
+    """Unparse a MappingNode with formatting metadata preserved."""
+    lines = []
+    prefix = " " * indent
+    for merge_node in mapping.merges:
+        line = prefix + "<<: " + unparse_node(merge_node, 0)
+        lines.append(line)
+    for key_node, value_node in mapping.pairs:
+        for comment in key_node.leading_comments:
+            lines.append(prefix + comment)
+        key_str = (
+            unparse_scalar(key_node, 0)
+            if isinstance(key_node, ScalarNode)
+            else unparse_node(key_node, 0)
+        )
+        if isinstance(value_node, (MappingNode, SequenceNode)):
+            line = prefix + f"{key_str}:"
+            if key_node.trailing_comments:
+                line += " " + " ".join(key_node.trailing_comments)
+            lines.append(line)
+            lines.append(unparse_node(value_node, indent + 2))
+        else:
+            value_str = unparse_node(value_node, 0)
+            line = prefix + f"{key_str}: {value_str}"
+            if key_node.trailing_comments:
+                line += " " + " ".join(key_node.trailing_comments)
+            lines.append(line)
+    return "\n".join(lines)
+
+
+def unparse_sequence(seq: SequenceNode, indent: int = 0) -> str:
+    """Unparse a SequenceNode with formatting metadata preserved."""
+    lines = []
+    prefix = " " * indent
+    for item in seq.items:
+        if isinstance(item, (MappingNode, SequenceNode)):
+            lines.append(prefix + "-")
+            lines.append(unparse_node(item, indent + 2))
+        else:
+            item_str = unparse_node(item, 0)
+            lines.append(prefix + f"- {item_str}")
+    return "\n".join(lines)
+
+
+def unparse_scalar(scalar: ScalarNode, indent: int = 0) -> str:
+    """Unparse a ScalarNode with formatting metadata preserved."""
+    prefix = " " * indent
+    if scalar.alias_of:
+        return prefix + "*" + scalar.alias_of
+    tag_part = f"{scalar.tag} " if scalar.tag else ""
+    anchor_part = f"&{scalar.anchor} " if scalar.anchor else ""
+    if scalar.style in ("|", ">"):
+        lines = [prefix + tag_part + anchor_part + scalar.style]
+        if scalar.lines:
+            for line in scalar.lines:
+                lines.append(" " * (indent + 2) + line)
+        else:
+            for line in str(scalar.value).splitlines():
+                lines.append(" " * (indent + 2) + line)
+        return "\n".join(lines)
+    else:
+        val = scalar.value
+        if isinstance(val, bool):
+            text = "true" if val else "false"
+        elif val is None:
+            text = "null"
+        elif isinstance(val, (int, float)):
+            text = str(val)
+        elif isinstance(val, str):
+            text = val
+            if not text or any(c in text for c in [" ", ":", "-", "#"]):
+                text = '"' + text.replace('"', '\\"') + '"'
+        else:
+            text = str(val)
+        return prefix + tag_part + anchor_part + text
+
+
+# ==================
+# Plain Dumping
+# ==================
+def _internal_dump_plain(node: Node, indent: int = 0) -> str:
+    """
+    Dump the AST node to plain YAML, ignoring extra formatting metadata.
+    Document markers, comments, and anchors are omitted.
+    """
+    if isinstance(node, DocumentNode):
+        return _internal_dump_plain(node.root, indent)
+    elif isinstance(node, MappingNode):
+        lines = []
+        prefix = " " * indent
+        for key_node, value_node in node.pairs:
+            key_str = (
+                _plain_scalar(key_node)
+                if isinstance(key_node, ScalarNode)
+                else _internal_dump_plain(key_node, 0)
+            )
+            if isinstance(value_node, (MappingNode, SequenceNode)):
+                lines.append(prefix + f"{key_str}:")
+                lines.append(_internal_dump_plain(value_node, indent + 2))
+            else:
+                value_str = (
+                    _plain_scalar(value_node)
+                    if isinstance(value_node, ScalarNode)
+                    else _internal_dump_plain(value_node, 0)
+                )
+                lines.append(prefix + f"{key_str}: {value_str}")
+        return "\n".join(lines)
+    elif isinstance(node, SequenceNode):
+        lines = []
+        prefix = " " * indent
+        for item in node.items:
+            if isinstance(item, (MappingNode, SequenceNode)):
+                lines.append(prefix + "-")
+                lines.append(_internal_dump_plain(item, indent + 2))
+            else:
+                lines.append(
+                    prefix
+                    + f"- {_plain_scalar(item) if isinstance(item, ScalarNode) else _internal_dump_plain(item, 0)}"
+                )
+        return "\n".join(lines)
+    elif isinstance(node, ScalarNode):
+        return " " * indent + _plain_scalar(node)
+    else:
+        return " " * indent + str(node)
+
+
+# The plain scalar conversion is similar to our helper in round-trip mode.
+def _plain_scalar(node: ScalarNode) -> str:
+    val = node.value
+    if isinstance(val, bool):
+        return "true" if val else "false"
+    elif val is None:
+        return "null"
+    elif isinstance(val, (int, float)):
+        return str(val)
+    elif isinstance(val, str):
+        if not val or any(c in val for c in [" ", ":", "-", "#"]):
+            return '"' + val.replace('"', '\\"') + '"'
+        return val
+    else:
+        return str(val)

{cayaml-0.1.0.dev3.dist-info → cayaml-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: cayaml
-Version: 0.1.0.dev3
+Version: 0.1.1
 Summary: Swarmauri's Canon Yaml Handler
 License: Apache-2.0
 Author: Jacob Stewart

cayaml-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+cayaml/__init__.py,sha256=bA4mqOPV6jwnYiF4mPs6w_V3gLsoa6EDZD3h-HIw7u0,476
+cayaml/api.py,sha256=LDYKZmJqEPvJluNh4fSv_ZRN4WmOM4C6FjwiZEg_mPc,4159
+cayaml/ast_nodes.py,sha256=w-Np8ojCjO29kbwRgBnswLlXXbVMiWJr50dgDv3cXqc,7359
+cayaml/parser.py,sha256=v0_OHlRKtV6iAlWsZ26pjC2W_dzRxyGxQeVmdhBbmY8,10741
+cayaml/plain_conversion.py,sha256=_Iy9MSJ9T0_9KJ8eCkWye_BPJ5fdnDLXw0L9B-Z-2QA,2238
+cayaml/unparser.py,sha256=S5ZwV7wRiEq-rpieoC3ZGLwTonAKdaZ5NWSvrISn9zg,8217
+cayaml-0.1.1.dist-info/METADATA,sha256=986AW_QUlI8PWp0HG6-Lt1J_DpJ6hWx4tyeH74m1TK4,454
+cayaml-0.1.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+cayaml-0.1.1.dist-info/RECORD,,

{cayaml-0.1.0.dev3.dist-info → cayaml-0.1.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.2
+Generator: poetry-core 2.1.3
 Root-Is-Purelib: true
 Tag: py3-none-any

cayaml-0.1.0.dev3.dist-info/RECORD

@@ -1,4 +0,0 @@
-cayaml/__init__.py,sha256=7T-rcRLCZTemVt0grS40pvaYg3OB-YjPyRiZibxp4C0,5421
-cayaml-0.1.0.dev3.dist-info/METADATA,sha256=K4Vcs18XntzWfbLzHSBPDq7iH_BeCiYGKYazFu0iyGI,459
-cayaml-0.1.0.dev3.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-cayaml-0.1.0.dev3.dist-info/RECORD,,