m6rclib is a Python package that provides a parser and prompt compiler for the Metaphor language, a structured text format for defining roles, contexts, and actions.
pip install m6rclib
from m6rclib import MetaphorParser
# Create a parser instance
parser = MetaphorParser()
# Parse a Metaphor string
input_text = """
Role:
You are a helpful assistant.
Context:
The user needs help with Python.
Action:
Provide clear Python examples.
"""
# Parse the input with search paths for Include: directives
syntax_tree = parser.parse(input_text, "example.m6r", ["/path/to/includes"])
The main class for parsing Metaphor documents.
-
parse(input_text: str, filename: str, search_paths: List[str], embed_path: Optional[str]) -> MetaphorASTNode
- Parses a string containing Metaphor content
- Args:
input_text
: The Metaphor content to parsefilename
: Name to use for error reportingsearch_paths
: List of paths to search for included filesembed_path
: Path used to search for embedded files
- Returns: The root of the abstract syntax tree
- Raises:
MetaphorParserError
: If there are syntax errorsFileNotFoundError
: If a required file cannot be found
-
parse_file(filename: str, search_paths: List[str]) -> MetaphorASTNode
- Parses a Metaphor file
- Args:
filename
: Path to the file to parsesearch_paths
: List of paths to search for included files
- Returns: The root of the abstract syntax tree
- Raises:
MetaphorParserError
: If there are syntax errorsFileNotFoundError
: If the file cannot be found
Represents a node in the abstract syntax tree (AST).
-
node_type: MetaphorASTNodeType
- The type of the node
- Read-only
-
value: str
- The raw text value of the node
- Read-only
-
parent: Optional[MetaphorASTNode]
- The parent node, if any
- Read-only
-
children: List[MetaphorASTNode]
- The node's child nodes (returns a shallow copy)
- Read-only
-
attach_child(child: MetaphorASTNode) -> None
- Adds a child node to this node
- Args:
child
: The node to attach as a child
-
detach_child(child: MetaphorASTNode) -> None
- Removes a child node from this node
- Args:
child
: The node to detach
- Raises:
ValueError
: If the node is not a child of this node
-
get_children_of_type(self, node_type: MetaphorASTNodeType) -> List['MetaphorASTNode']
- Returns a list of all immediate children that match the specified node type.
- Args:
node_type (MetaphorASTNodeType)
: The type of nodes to filter for
- Returns:List of child nodes matching the specified type
An enumeration of possible AST node types.
ROOT (0)
: Root node of the ASTTEXT (1)
: Text content nodeROLE (2)
: Role definition nodeCONTEXT (3)
: Context definition nodeACTION (4)
: Action definition node
Helper functions for formatting nodes and errors.
-
format_ast(node: MetaphorASTNode) -> str
- Format an AST node and its children as a string
- Args:
node
: The root node to format
- Returns: Formatted string representation of the AST
-
format_errors(errors: List[MetaphorParserSyntaxError]) -> str
- Format a list of syntax errors as a string
- Args:
errors
: List of syntax errors to format
- Returns: Formatted error string with each error on separate lines
Main exception wrapper for parser errors.
- Attributes:
errors: List[MetaphorParserSyntaxError]
: List of syntax errors encountered
Detailed syntax error information.
- Attributes:
message: str
: Error descriptionfilename: str
: File where error occurredline: int
: Line number of errorcolumn: int
: Column number of errorinput_text: str
: Input line containing error
Metaphor files use the following format:
Role:
Description of the role
Additional role details
Context:
Description of the context
Context details
Context: Subsection
More detailed context information
Action:
Description of the action
Step-by-step actions to take
-
Include: filename
- Includes another Metaphor file
- File is searched for in the provided search paths
-
Embed: pattern
- Embeds the contents of matching files
- Supports glob patterns
- Use
**/
for recursive matching