mls-parser 0.0.2__py3-none-any.whl

mls_parser/__init__.py

@@ -0,0 +1 @@
+version = "0.0.2"

mls_parser/__main__.py

@@ -0,0 +1,67 @@
+"""
+__main__.py
+
+Layout Model Sheet Parser
+"""
+
+# System
+import logging
+import logging.config
+import sys
+import argparse
+from pathlib import Path
+
+# Parser
+from mls_parser import version
+from mls_parser.layout_parser import LayoutParser
+
+_logpath = Path("mls_parser.log")
+
+def get_logger():
+    """Initiate the logger"""
+    log_conf_path = Path(__file__).parent / 'log.conf'  # Logging configuration is in this file
+    logging.config.fileConfig(fname=log_conf_path, disable_existing_loggers=False)
+    return logging.getLogger(__name__)  # Create a logger for this module
+
+# Configure the expected parameters and actions for the argparse module
+def parse(cl_input):
+    """
+    The command line interface is for diagnostic purposes
+
+    :param cl_input:
+    :return:
+    """
+    parser = argparse.ArgumentParser(description='Model layout parser')
+    parser.add_argument('cmfile', nargs='?', action='store',
+                        help='Model layout file name with .mls extension')
+    parser.add_argument('-D', '--debug', action='store_true',
+                        help='Debug mode'),
+    parser.add_argument('-V', '--version', action='store_true',
+                        help='Print the current version of parser')
+    return parser.parse_args(cl_input)
+
+
+def main():
+    # Start logging
+    logger = get_logger()
+    logger.info(f'Model layout parser version: {version}')
+
+    # Parse the command line args
+    args = parse(sys.argv[1:])
+
+    if args.version:
+        # Just print the version and quit
+        print(f'Model layout parser version: {version}')
+        sys.exit(0)
+
+    if args.cmfile:
+        fpath = Path(args.cmfile)
+        d = args.debug
+        result = LayoutParser.parse_file(file_input=fpath, debug=d)
+
+    logger.info("No problemo")  # We didn't die on an exception, basically
+    print("\nNo problemo")
+
+
+if __name__ == "__main__":
+    main()

mls_parser/exceptions.py

@@ -0,0 +1,100 @@
+"""
+exceptions.py – Model layout parser specific exceptions
+"""
+
+# Every error should have the same format
+# with a standard prefix and postfix defined here
+pre = "\nModel layout parser: ["
+post = "]"
+
+
+class MLSException(Exception):
+    pass
+
+class MLSUserInputException(MLSException):
+    pass
+
+class MLSIOException(MLSException):
+    pass
+
+class LayoutParseError(MLSUserInputException):
+    def __init__(self, model_file, e):
+        self.model_file = model_file
+        self.e = e
+
+    def __str__(self):
+        return f'{pre}Parse error in layout "{self.model_file}"\n\t{self.e}"{post}'
+
+class LayoutInputFileOpen(MLSIOException):
+    def __init__(self, path):
+        self.path = path
+
+    def __str__(self):
+        return f'{pre}Parser cannot open this layout file: "{self.path}"{post}'
+
+class LayoutInputFileEmpty(MLSIOException):
+    def __init__(self, path):
+        self.path = path
+
+    def __str__(self):
+        return f'{pre}For some reason, nothing was read from the layout file: "{self.path}"{post}'
+
+class LayoutGrammarFileOpen(MLSIOException):
+    def __init__(self, path):
+        self.path = path
+
+    def __str__(self):
+        return f'{pre}Parser cannot open this layout grammar file: "{self.path}"{post}'
+
+class MultipleFloatsInSameStraightConnector(MLSException):
+    def __init__(self, name):
+        self.name = name
+
+    def __str__(self):
+        return f'{pre}Straight connector "{self.name}" has two floating anchors (*). Specify one.{post}'
+
+class MultipleFloatsInSameBranch(MLSException):
+    def __init__(self, branch):
+        self.branch = branch
+
+    def __str__(self):
+        return f'{pre}There may be at most one floating anchor (*) per branch: "{self.branch}"{post}'
+
+class ConflictingGraftFloat(MLSException):
+    def __init__(self, stem):
+        self.stem = stem
+
+    def __str__(self):
+        return f'{pre}A floating anchor(*) may not graft (>, >>): "{self.stem}"{post}'
+
+class MultipleGraftsInSameBranch(MLSException):
+    def __init__(self, branch):
+        self.branch = branch
+
+    def __str__(self):
+        return f'{pre}There may be at most one graft (>, >>) per branch: "{self.branch}"{post}'
+
+class TrunkLeafGraftConflict(MLSException):
+    def __str__(self):
+        return f'{pre}Leaf may not graft locally (>) if Trunk is grafting (>) {post}'
+
+class ExternalLocalGraftConflict(MLSException):
+    def __init__(self, branch):
+        self.branch = branch
+
+    def __str__(self):
+        return f'{pre}Branch has local (>) graft with conflicting external graft (>>) in preceding branch: "{self.branch}"{post}'
+
+class ExternalGraftOnLastBranch(MLSException):
+    def __init__(self, branch):
+        self.branch = branch
+
+    def __str__(self):
+        return f'{pre}Last branch in tree layout has a superfluous external (>>) graft: "{self.branch}"{post}'
+
+class GraftRutBranchConflict(MLSException):
+    def __init__(self, branch):
+        self.branch = branch
+
+    def __str__(self):
+        return f'{pre}A rut branch, with (: Ln[R+/-n]), may not include a local graft(>): "{self.branch}"{post}'

mls_parser/layout.peg

@@ -0,0 +1,109 @@
+// Flatland Model Layout Arpeggio Clean Peg Grammar
+
+// This grammar expresses the geometric layout of nodes and connectors and where
+// connectors attach to node faces on a diagram. It does not specify any meaning
+// associated with the nodes and connectors. Node and connector names are ascribed
+// in their model files, but no other information in the model files is referenced
+// in this grammar.
+
+// You can draw unconnected nodes, connected nodes or a blank sheet
+diagram_layout = EOL* layout_spec ((node_block connector_block) / (node_block))? EOF
+
+// Layout spec
+layout_spec = (diagram notation color? presentation sheet padding? orientation frame? frame_presentation?)# // Each of these in any order
+
+// Diagram
+diagram = "diagram" SP+ name EOL* // The type of diagram to draw
+notation =  "notation" SP+ name EOL* // The notation to use in the diagram
+color = "color" SP+ name EOL* // The type of diagram to draw
+presentation = "presentation" SP+ name EOL* // The presentation style for drawing
+sheet = "sheet" SP+ name EOL* // The sheet size name
+padding = "padding" (tpad? bpad? lpad? rpad?)# EOL*
+tpad = SP+ 't'number
+bpad = SP+ 'b'number
+lpad = SP+ 'l'number
+rpad = SP+ 'r'number
+orientation = "orientation" SP+ ("portrait" / "landscape") EOL* // The sheet orientation
+frame = "frame" SP+ name EOL* // The frame name
+frame_presentation = "frame_presentation" SP+ name EOL* // The presentation style for the frame
+
+// Node
+node_block = nodes_header node_spec+
+nodes_header = "nodes" EOL*
+node_spec = INDENT node_name wrap? (SP+ node_width_expansion)? (SP+ node_height_expansion)? SP+ node_placement (SP+ color_tag)? EOL*
+node_name = name
+node_width_expansion = number '%'  // Increase the width of the node
+node_height_expansion = comp_height_expansion (SP+ comp_height_expansion)*  // A node's height is the sum of its expanded compartments
+comp_height_expansion = '[C' number ']' number '%'  // Increase the height of a single compartment
+node_placement = grid_place (SP+ ':' SP+ grid_place)*  // One or more such locations
+grid_place = node_loc (SP+ node_align)? // Location in grid where a node will appear
+node_loc = span ',' span  // Row and column
+span =  number '-' number / number
+color_tag = '<' name '>'
+
+// Connector
+connector_block = connectors_header connector_layout+ // All
+connectors_header = "connectors" EOL* // starts section where connector layout info is specified
+connector_layout = INDENT cname_place?  ( binary_layout / tree_layout / unary_layout ) EOL*
+cname_place = dir? name wrap? bend? notch? csep // Side of connector axis and name of connector (since it is probably short)
+bend = '.' number // Bend in connector where 1 is at the tstem side increasing to the pstem side
+
+// Binary connector
+binary_layout = tstem csep pstem tertiary_node? (csep paths)? // All layout info for a binary connector
+tstem = stem_side // one stem in a binary connector (t and p are arbitary names)
+pstem = stem_side // the opposite stem in a binary connector
+tertiary_node = ',' SP+ node_face
+paths = path (SP+ path)*
+sname_place = dir wrap  // Side of stem axis and number of text lines after wrapping in stem name text block
+stem_side = (sname_place SP+)? node_face // Either the tstem or pstem layout
+
+// Tree layout
+tree_layout = trunk_face (SP+ branch)+ // All layout info for a tree connector
+trunk_face = node_face ('>')? // May or may not graft the trunk branch with > symbol
+branch = '{ ' leaf_faces (csep path)? ' }' // A branch is attached to one or more leaf faces
+leaf_faces = leaf_face (', ' leaf_face)*
+leaf_face = node_face ('>>' / '>' )?  // graft its own branch or the next one
+// Within a branch, one leaf may either graft that branch > or graft the subsequent branch >>
+// See patterns 3 and 2 respectively in tech note tn.2 in the documentation folder for examples
+// There are three ways to specify the path of a branch:
+//    1) Interpolated - Compute position between opposing node faces (no specification)
+//    2) Grafted - Line up branch with some face placement (a > on the trunk or some leaf face or a >> on a leaf face)
+//    3) Rut - Run branch down a rut in a lane as specified by a path (path)
+// A branch that is neither interpolated nor grafted has a path specified where it runs
+
+// Unary connector
+unary_layout = stem_side
+
+// Face attachment
+node_ref = name ('.' number)? // Optional additional placement of the same node
+face =  "t" / "b" / "l" / "r" // top, bottom, left or right node face
+dir = "+" / "-" // direction of increasing coord values, up and to the right is positive
+csep = SP+ ':' SP+ // argument separator
+anchor = notch / '*'
+node_face = face anchor? "|" node_ref // Where a stem attaches to a node face
+
+// Alignment
+valign = ">" ("top" / "bottom")
+halign = ">" ("right" / "left")
+node_align = valign SP? halign / halign SP? valign / valign / halign
+// A notch is based on a system where 0 means 'centered' and deviations from the center are proportional
+// increments, each the same size, distant from the center in the positive or negative direction
+// Positive is always in the increasing coordinate direction, up or to the right
+notch = '0' / ('+' / '-') number // A unit of alignment, center, or a positive or negative integer
+path = 'L' number ('R' notch)? // Lane and rut, assume rut 0 if R not specified
+
+// Elements
+wrap = '/' number // Number of lines to wrap an associated string
+number = r'[1-9][0-9]*' // Always a positive integer
+
+// Model element names
+// A name is one or more words separated by a delimiter
+delim = r'[ _]' // Delimiter to separate words in a name
+word = r'[A-Za-z][A-Za-z0-9]*' // String of alpahnumeric text with no whitespace starting with alpha char
+name = word (delim word)* // Sequence of delimited words forming a name
+
+// Whitespace and comments
+INDENT = "    "  // For clarity
+EOL = SP* COMMENT? '\n' // end of line: Comments, blank lines, whitespace we can omit from the parser result
+COMMENT = '//' r'.*' // Comment slashes don't work if included in the regular expression for some reason
+SP = " "

mls_parser/layout_parser.py

@@ -0,0 +1,118 @@
+""" layout_parser.py – Parse layout file """
+
+from mls_parser.exceptions import LayoutGrammarFileOpen, LayoutInputFileOpen, LayoutInputFileEmpty, LayoutParseError
+from mls_parser.layout_visitor import LayoutVisitor
+from arpeggio import visit_parse_tree, NoMatch
+from arpeggio.cleanpeg import ParserPEG
+import os
+from pathlib import Path
+
+
+class LayoutParser:
+    """
+    Parses a model layout file using the arpeggio parser generator
+
+        Attributes
+
+        - grammar_file -- (class based) Name of the system file defining the Executable UML grammar
+        - root_rule_name -- (class based) Name of the top level grammar element found in grammar file
+        - debug -- debug flag (used to set arpeggio parser mode)
+        - model_grammar -- The model grammar text read from the system grammar file
+        - model_text -- The input model text read from the user supplied text file
+    """
+
+    debug = False  # by default
+    mls_grammar = None  # We haven't read it in yet
+    model_text = None  # User will provide this in a file
+    model_file = None  # The user supplied xcm file path
+
+    root_rule_name = 'diagram_layout'  # The required name of the highest level parse element
+
+    # Useful paths within the project
+    src_path = Path(__file__).parent.parent  # Path to src folder
+    module_path = src_path / 'mls_parser'
+    grammar_path = module_path  # The grammar files are all here
+    cwd = Path.cwd()
+    diagnostics_path = cwd / 'diagnostics'  # All parser diagnostic output goes here
+
+    # Files
+    grammar_file = grammar_path / "layout.peg"  # We parse using this peg grammar
+    grammar_model_pdf = diagnostics_path / "layout.pdf"
+    parse_tree_pdf = diagnostics_path / "layout_parse_tree.pdf"
+    parse_tree_dot = cwd / f"{root_rule_name}_parse_tree.dot"
+    parser_model_dot = cwd / f"{root_rule_name}_peg_parser_model.dot"
+
+    pg_tree_dot = cwd / "peggrammar_parse_tree.dot"
+    pg_model_dot = cwd / "peggrammar_parser_model.dot"
+    pg_tree_pdf = diagnostics_path / "peggrammar_parse_tree.pdf"
+    pg_model_pdf = diagnostics_path / "peggrammar_parser_model.pdf"
+
+    @classmethod
+    def parse_file(cls, file_input: Path, debug=False):
+        """
+
+        :param file_input:  class model file to read
+        :param debug:  Run parser in debug mode
+        """
+        cls.model_file = file_input
+        cls.debug = debug
+        if debug:
+            # If there is no diagnostics directory, create one in the current working directory
+            cls.diagnostics_path.mkdir(parents=False, exist_ok=True)
+
+        # Read the class model file
+        try:
+            cls.model_text = open(file_input, 'r').read() + '\n'
+            # At least one newline at end simplifies grammar rules
+        except OSError as e:
+            raise LayoutInputFileOpen(file_input)
+
+        if not cls.model_text:
+            raise LayoutInputFileEmpty(file_input)
+
+        return cls.parse()
+
+    @classmethod
+    # def parse(cls) -> Subsystem_a:
+    def parse(cls):
+        """
+        Parse the model file and return the content
+        :return:  The abstract syntax tree content of interest
+        """
+        # Read the grammar file
+        try:
+            cls.mls_grammar = open(LayoutParser.grammar_file, 'r').read()
+        except OSError as e:
+            raise LayoutGrammarFileOpen(LayoutParser.grammar_file)
+
+        # Create an arpeggio parser for our model grammar that does not eliminate whitespace
+        # We interpret newlines and indents in our grammar, so whitespace must be preserved
+        parser = ParserPEG(cls.mls_grammar, LayoutParser.root_rule_name, skipws=False, debug=cls.debug)
+        if cls.debug:
+            # Transform dot files into pdfs
+            # os.system(f'dot -Tpdf {cls.pg_tree_dot} -o {cls.pg_tree_pdf}')
+            # os.system(f'dot -Tpdf {cls.pg_model_dot} -o {cls.pg_model_pdf}')
+            os.system(f'dot -Tpdf {cls.parser_model_dot} -o {cls.grammar_model_pdf}')
+            cls.parser_model_dot.unlink(True)
+            cls.pg_tree_dot.unlink(True)
+            cls.pg_model_dot.unlink(True)
+
+        # Now create an abstract syntax tree from our model text
+        try:
+            parse_tree = parser.parse(cls.model_text)
+        except NoMatch as e:
+            raise LayoutParseError(cls.model_file.name, e) from None
+
+        # Transform that into a result that is better organized with grammar artifacts filtered out
+        result = visit_parse_tree(parse_tree, LayoutVisitor(debug=cls.debug))
+
+        if cls.debug:
+            # Transform dot files into pdfs
+            os.system(f'dot -Tpdf {cls.parse_tree_dot} -o {cls.parse_tree_pdf}')
+            # Delete dot files since we are only interested in the generated PDFs
+            # Comment this part out if you want to retain the dot files
+            cls.parse_tree_dot.unlink(True)
+
+        return result
+
+

mls_parser/layout_visitor.py

@@ -0,0 +1,510 @@
+""" layout_visitor.py """
+from collections import namedtuple
+from enum import Enum
+from arpeggio import PTNodeVisitor
+from mls_parser.exceptions import (ConflictingGraftFloat, MultipleGraftsInSameBranch, ExternalLocalGraftConflict,
+                                   MultipleFloatsInSameBranch, TrunkLeafGraftConflict, GraftRutBranchConflict,
+                                   ExternalGraftOnLastBranch)
+
+
+DiagramLayout = namedtuple('DiagramLayout', 'layout_spec node_placement connector_placement')
+LayoutSpec = namedtuple('LayoutSpec', 'dtype pres notation color sheet orientation frame frame_presentation padding')
+
+class NodeFace(Enum):
+    """
+    Values are multiplied by absolute distance to get an x or y coordinate.
+    """
+    TOP = 0
+    BOTTOM = 1
+    RIGHT = 2
+    LEFT = 3
+
+
+face_map = {'r': NodeFace.RIGHT, 'l': NodeFace.LEFT, 't': NodeFace.TOP, 'b': NodeFace.BOTTOM}
+
+
+class LayoutVisitor(PTNodeVisitor):
+    """
+    Organized in the same categories commented in the clean peg grammar file.
+
+        Some conventions:
+
+        - Comment each visit with parsing semantics
+        - Descriptive named variables if processing is required
+        - Use *node.rule_name* in case the rule name changes
+        - Combine values into dictionaries for stability, ease of interpretation and to avoid mistakes
+        - Assigining result to a variable that is returned for ease of debugging
+    """
+
+    # Root
+    @classmethod
+    def visit_diagram_layout(cls, node, children) -> DiagramLayout:
+        """
+        EOL* layout_spec ((node_block connector_block) / (node_block))? EOF
+
+        Root Rule
+        """
+        # Organize the input into a layout spec, a node dictionary, and an optional connector block
+        lspec = children.results['layout_spec'][0]
+        node_pdict = {}
+        for n in children.results['node_block'][0]:
+            dup_num = n.get('duplicate')
+            key = n['node_name'] if not dup_num else f"{n['node_name']}_{dup_num}"
+            node_pdict[key] = n
+
+        if 'connector_block' in children.results:
+            rc = children.results['connector_block'][0]
+        else:
+            rc = None
+        return DiagramLayout(layout_spec=lspec, node_placement=node_pdict, connector_placement=rc)
+
+    @classmethod
+    def visit_layout_spec(cls, node, children) -> LayoutSpec:
+        """
+        (diagram notation color? presentation sheet padding? orientation frame? frame_presentation?)#
+
+        Layout specification
+        """
+        ld = children.results
+        frame = ld.get('frame')
+        color = ld.get('color', ['white'])
+        frame_presentation = ld.get('frame_presentation')
+        padding = ld.get('padding')
+        lspec = LayoutSpec(dtype=ld['diagram'][0], notation=ld['notation'][0], pres=ld['presentation'][0],
+                           orientation=ld['orientation'][0], sheet=ld['sheet'][0],
+                           color=color[0],
+                           frame=None if not frame else frame[0],
+                           # frame_presentation not relevant if no frame
+                           frame_presentation=None if not frame else frame_presentation[0],
+                           padding=None if not padding else padding[0])
+        return lspec
+
+    # Diagram
+    @classmethod
+    def visit_diagram(cls, node, children):
+        """Keyword argument"""
+        return children[0]
+
+    @classmethod
+    def visit_notation(cls, node, children):
+        """Keyword argument"""
+        return children[0]
+
+    @classmethod
+    def visit_color(cls, node, children):
+        """Keyword argument"""
+        return children[0]
+
+    @classmethod
+    def visit_presentation(cls, node, children):
+        """Keyword argument"""
+        return children[0]
+
+    @classmethod
+    def visit_sheet(cls, node, children):
+        """Keyword argument"""
+        return children[0]
+
+    @classmethod
+    def visit_padding(cls, node, children):
+        """Keyword argument"""
+        d = {k: v for c in children for k, v in c.items()}
+        return d
+
+    @classmethod
+    def visit_tpad(cls, node, children):
+        return {'top': children[0]}
+
+    @classmethod
+    def visit_bpad(cls, node, children):
+        return {'bottom': children[0]}
+
+    @classmethod
+    def visit_lpad(cls, node, children):
+        return {'left': children[0]}
+
+    @classmethod
+    def visit_rpad(cls, node, children):
+        return {'right': children[0]}
+
+    @classmethod
+    def visit_orientation(cls, node, children):
+        """Keyword argument"""
+        return children[0]
+
+    @classmethod
+    def visit_frame(cls, node, children):
+        """Keyword argument"""
+        return children[0]
+
+    @classmethod
+    def visit_frame_presentation(cls, node, children):
+        """Keyword argument"""
+        return children[0]
+
+
+    # Node
+    @classmethod
+    def visit_node_block(cls, node, children):
+        """ nodes_header node_spec+ """
+        return children
+
+    @classmethod
+    def visit_node_spec(cls, node, children):
+        """
+        INDENT node_name wrap? (SP+ node_width_expansion)? (SP+ node_height_expansion)?
+         SP+ node_placement (SP+ color_tag)? EOL*
+        """
+        ditems = {k: v for c in children for k, v in c.items()}
+        return ditems
+
+    @classmethod
+    def visit_node_name(cls, node, children):
+        """ name """
+        return {node.rule_name: ''.join(children)}
+
+    @classmethod
+    def visit_node_width_expansion(cls, node, children):
+        """ number '%' """
+        # Convert percentage to ratio ensuring ratio is positive
+        user_percent = children[0]
+        ratio = 0 if user_percent < 0 else round(user_percent / 100, 2)
+        return {node.rule_name: ratio}
+
+    @classmethod
+    def visit_node_height_expansion(cls, node, children):
+        """ number '%' """
+        d = {k: v for k, v in children}
+        return {node.rule_name: d}
+
+    @classmethod
+    def visit_comp_height_expansion(cls, node, children):
+        """ '[C' number ']' number '%' """
+        # Convert percentage to ratio ensuring ratio is positive
+        user_percent = children[1]
+        ratio = 0 if user_percent < 0 else round(user_percent / 100, 2)
+        return [children[0], ratio]
+
+    @classmethod
+    def visit_node_placement(cls, node, children):
+        """ grid_place (SP+ ':' SP+ grid_place)* """
+        return {'placements': children}
+
+    @classmethod
+    def visit_grid_place(cls, node, children):
+        """ node_loc (SP+ node_align)? """
+        d = {k: v for c in children for k, v in c.items()}
+        return d
+
+    @classmethod
+    def visit_node_loc(cls, node, children):
+        """
+        span ',' span
+
+        row and column
+        """
+        return {node.rule_name: children}
+
+    @classmethod
+    def visit_span(cls, node, children):
+        """
+        number '-' number / number
+
+        for example:
+        3-5 is returned as span [3,5]
+        3 is returned as span [3]
+        """
+        return children
+
+    @classmethod
+    def visit_color_tag(cls, node, children):
+        """ '<' name '>' """
+        return {node.rule_name: children[0]}
+
+    # Connector
+    @classmethod
+    def visit_connector_block(cls, node, children):
+        return children
+
+    @classmethod
+    def visit_connector_layout(cls, node, children):
+        """All layout info for the connector"""
+        # Combine all child dictionaries
+        items = {k: v for d in children for k, v in d.items()}
+        items['bend'] = items.get('bend', 1)  # No bend supplied, assume 1
+        return items
+
+    @classmethod
+    def visit_cname_place(cls, node, children):
+        """Name of connector and the side of the connector axis where it is placed"""
+        # If a value is supplied it will be a single time list, so extract with [0]
+        # If no value is supplied for an optional item, default must also be a single item list [default_value]
+        w = children.results.get('wrap')
+        wrap_value = 1 if not w else w[0]['wrap']
+        cplace = {'cname': children.results['name'][0],  # Required component
+                  'dir': children.results.get('dir', [1])[0],  # many optional components with default values
+                  'bend': children.results.get('bend', [1])[0],
+                  'notch': children.results.get('notch', [0])[0],
+                  'wrap': wrap_value,
+                  }
+        return cplace
+
+    @classmethod
+    def visit_bend(cls, node, children):
+        """Number of bend where cname appears"""
+        # return {node.rule_name: int(children[0])}
+        bend = int(children[0])
+        return bend
+
+    # Binary connector
+    @classmethod
+    def visit_binary_layout(cls, node, children):
+        """All layout info for the binary connector"""
+        # Combine all child dictionaries
+        items = {k: v for d in children for k, v in d.items()}
+        return items
+
+    @classmethod
+    def visit_tstem(cls, node, children):
+        """T stem layout info"""
+        items = {k: v for d in children for k, v in d.items()}
+        items['anchor'] = items.get('anchor', 0)
+        tstem = {node.rule_name: items}
+        return tstem
+
+    @classmethod
+    def visit_pstem(cls, node, children):
+        """P stem layout info"""
+        items = {k: v for d in children for k, v in d.items()}
+        items['anchor'] = items.get('anchor', 0)
+        pstem = {node.rule_name: items}
+        return pstem
+
+    @classmethod
+    def visit_tertiary_node(cls, node, children):
+        """Tertiary node face and anchor"""
+        return {node.rule_name: children[0]}
+
+    @classmethod
+    def visit_paths(cls, node, children):
+        """A sequence of one or more paths since a binary connector may bend multiple times"""
+        paths = {node.rule_name: [p['path'] for p in children]}
+        return paths
+
+    @classmethod
+    def visit_sname_place(cls, node, children):
+        """Side of stem axis and number of lines in text block"""
+        d = {'stem_dir': children[0]}  # initialize d
+        d.update(children[1])  # Add wrap key
+        return d
+
+    # Tree connector
+    @classmethod
+    def visit_tree_layout(cls, node, children):
+        """All layout info for the tree connector"""
+        tlayout = children[0]
+        # If the trunk is grafting (>), there can be no other leaf stem grafting locally (>)
+        tlayout['branches'] = [c['branch'] for c in children[1:]]
+        tgraft = tlayout['trunk_face']['graft']
+        tleaves = tlayout['branches'][0]['leaf_faces']
+        if tgraft and [tleaves[n]['graft'] for n in tleaves if tleaves[n]['graft'] == 'local']:
+            raise TrunkLeafGraftConflict()  # In the first branch (trunk branch) both trunk and some leaf are grafting
+        # For all offshoot (non-trunk) branches, there can be no local graft (>) if the preceding branch
+        # is grafting externally (>>).  In other words, no more than one graft per branch.
+        for b, next_b in zip(tlayout['branches'], tlayout['branches'][1:]):
+            lf = b['leaf_faces']
+            external_graft = [lf[n]['graft'] for n in lf if lf[n]['graft'] == 'next']
+            if external_graft:
+                next_lf = next_b['leaf_faces']
+                if [next_lf[n]['graft'] for n in next_lf if next_lf[n]['graft'] == 'local']:
+                    # External graft conflicts with local branch
+                    raise ExternalLocalGraftConflict(set(lf.keys()))
+        # Check for dangling external graft in last branch
+        last_lf = tlayout['branches'][-1]['leaf_faces']
+        external_graft = [last_lf[n]['graft'] for n in last_lf if last_lf[n]['graft'] == 'next']
+        if external_graft:
+            raise ExternalGraftOnLastBranch(branch=set(last_lf.keys()))
+        return tlayout
+
+    @classmethod
+    def visit_trunk_face(cls, node, children):
+        """A single trunk node at the top of the tree layout. It may or may not graft its branch."""
+        face = children[0]  # Face, node and optional notch
+        graft = False if len(children) == 1 else True
+        if 'anchor' not in face.keys():
+            face['anchor'] = 0  # A Trunk face is never grafted, so an unspecified anchor is 0
+        tface = {'trunk_face': {'node_ref': face.pop('node_ref'), **face, 'graft': graft}}
+        return tface
+
+    @classmethod
+    def visit_branch(cls, node, children):
+        """A tree connector branch"""
+        branch = {k: v for d in children for k, v in d.items()}
+        # Verify that this is either an interpolated, rut or graft branch and not an illegal mix
+        # If a path is specified it is a rut branch or if there is a local graft it is a grafted branch
+        # If both path and local graft are present in the same branch it is illegal
+        if branch.get('path', None):  # Path specified, so there should be no local grafts in this branch
+            lf = branch['leaf_faces']
+            local_graft = [lf[n]['graft'] for n in lf if lf[n]['graft'] == 'local']
+            if local_graft:
+                raise GraftRutBranchConflict(branch=set(lf.keys()))
+        # Return dictionary of leaf faces and an optional path keyed to the local rule
+        return {node.rule_name: branch}
+
+    @classmethod
+    def visit_leaf_faces(cls, node, children):
+        """Combine into dictionary of each leaf face indexed by node name"""
+        lfaces = {k: v for d in children for k, v in d.items()}
+        if len([lfaces[n]['graft'] for n in lfaces if lfaces[n]['graft']]) > 1:
+            raise MultipleGraftsInSameBranch(branch=set(lfaces.keys()))
+        if len([lfaces[n]['anchor'] for n in lfaces if lfaces[n]['anchor'] == 'float']) > 1:
+            raise MultipleFloatsInSameBranch(branch=set(lfaces.keys()))
+        return {node.rule_name: lfaces}
+
+    @classmethod
+    def visit_leaf_face(cls, node, children):
+        """Branch face that may be a graft to its branch (local) or the (next) branch"""
+        lface = children[0]
+        graft = None
+        if 'anchor' not in lface.keys():
+            lface['anchor'] = 0  # If not float or a number, it must be zero in a tree layout
+        if len(children) == 2:
+            graft = 'local' if children[1] == '>' else 'next'
+        if lface['anchor'] == 'float' and graft:
+            raise ConflictingGraftFloat(stem=lface['name'])
+        lface['graft'] = graft
+        node_ref = lface.pop('node_ref')
+        # name = node_ref[0] if len(node_ref) == 1 else f"{node_ref[0]}_{node_ref[1]}"
+        return {node_ref: lface}  # Single element dictionary indexed by the node name
+
+    # Unary connector
+    @classmethod
+    def visit_unary_layout(cls, node, children):
+        """Unary layout which is just a single stem"""
+        return {'ustem': children[0]}
+
+    # Face attachment
+    @classmethod
+    def visit_node_ref(cls, node, children):
+        """name number?"""
+        return children[0] if len(children) < 2 else f"{children[0]}_{children[1]}"
+
+    @classmethod
+    def visit_face(cls, node, children):
+        """Face character"""
+        return face_map[node.value]
+
+    @classmethod
+    def visit_dir(cls, node, children):
+        """Pos-neg direction"""
+        return 1 if node.value == '+' else -1
+
+    @classmethod
+    def visit_anchor(cls, node, children):
+        """Anchor position"""
+        anchor = 'float' if children[0] == '*' else children[0]
+        return anchor
+
+    @classmethod
+    def visit_node_face(cls, node, children):
+        """Where connector attaches to node face"""
+        nface = {k: v[0] for k, v in children.results.items()}
+        return nface
+
+    # Alignment
+    @classmethod
+    def visit_valign(cls, node, children):
+        """Vertical alignment of noce in its cell"""
+        return {node.rule_name: children[0].upper()}
+
+    @classmethod
+    def visit_halign(cls, node, children):
+        """Horizontal alignment of noce in its cell"""
+        return {node.rule_name: children[0].upper()}
+
+    @classmethod
+    def visit_node_align(cls, node, children):
+        """Vertical and/or horizontal alignment of node in its cell"""
+        if len(children) == 2:
+            # Merge the two dictionaries
+            return {**children[0], **children[1]}
+        else:
+            return children[0]
+
+    @classmethod
+    def visit_notch(cls, node, children):
+        """The digit 0 or a positive or negative number of notches"""
+        if children[0] == '0':
+            return 0
+        else:
+            scale = -1 if children[0] == '-' else 1
+            return int(children[1]) * scale
+
+    @classmethod
+    def visit_path(cls, node, children):
+        """
+        'L' number ('R' notch)?
+
+        Lane and rut, assume rut 0 if R not specified
+        """
+        # Rut is zero by default
+        path = {node.rule_name: {'lane': children[0], 'rut': children.results.get('notch', [0])[0]}}
+        return path  # { path: { lane: <lane_num>, rut: <rut_displacement> }
+
+    # Elements
+    @classmethod
+    def visit_wrap(cls, node, children):
+        """
+        '/' number
+
+        Number of lines to wrap an associated string
+        """
+        return {node.rule_name: int(children[0])}
+
+    @classmethod
+    def visit_number(cls, node, children):
+        """
+        r'[1-9][0-9]*'
+
+        Natural nummber
+        """
+        return int(node.value)
+
+    @classmethod
+    def visit_name(cls, node, children):
+        """
+        word (delim word)*
+
+        Sequence of delimited words forming a name
+        """
+        name = ''.join(children)
+        return name
+
+    # Discarded whitespace and comments
+    @classmethod
+    def visit_LINEWRAP(cls, node, children):
+        """
+        EOL SP*
+
+        end of line followed by optional INDENT on next line
+        """
+        return None
+
+    @classmethod
+    def visit_EOL(cls, node, children):
+        """
+        SP* COMMENT? '\n'
+
+        end of line: Spaces, Comments, blank lines, whitespace we can omit from the parser result
+        """
+        return None
+
+    @classmethod
+    def visit_SP(cls, node, children):
+        """
+        ' '
+
+        Single space character (SP)
+        """
+        return None
+

mls_parser/log.conf

@@ -0,0 +1,42 @@
+[loggers]
+keys=root,mlsParserLogger
+
+[handlers]
+keys=fileHandler, consoleHandler, consoleHandlerUser
+
+[formatters]
+keys=mlsParserFormatter, mlsParserFormatterUser
+
+[logger_root]
+level=DEBUG
+handlers=fileHandler, consoleHandlerUser
+
+[logger_mlsParserLogger]
+level=DEBUG
+handlers=fileHandler, consoleHandlerUser
+qualname=mlsParserLogger
+propagate=0
+
+[handler_fileHandler]
+class=FileHandler
+level=DEBUG
+formatter=mlsParserFormatter
+args=('mls_parser.log', 'w')
+
+[handler_consoleHandlerUser]
+class=StreamHandler
+level=WARNING
+formatter=mlsParserFormatterUser
+args=(sys.stderr,)
+
+[handler_consoleHandler]
+class=StreamHandler
+level=WARNING
+formatter=mlsParserFormatter
+args=(sys.stderr,)
+
+[formatter_mlsParserFormatter]
+format=mlsParser parser: %(name)s - %(levelname)s - %(message)s
+
+[formatter_mlsParserFormatterUser]
+format=mlsParser parser: %(levelname)s - %(message)s

mls_parser-0.0.2.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2023 Leon Starr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mls_parser-0.0.2.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.1
+Name: mls-parser
+Version: 0.0.2
+Summary: Flatland Model Layout Sheet Parser
+Author-email: Leon Starr <leon_starr@modelint.com>
+License: MIT License
+        
+        Copyright (c) 2019-2023 Leon Starr
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: repository, https://github.com/modelint/mls-parser
+Project-URL: documentation, https://github.com/modelint/mls-parser/wiki
+Keywords: action language,executable uml,class model,mbse,xuml,xtuml,platform independent,sysml
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Arpeggio
+Requires-Dist: tomli; python_version < "3.13"
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Provides-Extra: dev
+Requires-Dist: bump2version; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# Model Layout Parser
+
+Parses an *.mls file (Model Layout Style) to yield an abstract syntax tree using python named tuples
+
+### Why you need this
+
+You need to process an *.mls file to layout a model diagram
+
+### Installation
+
+Create or use a python 3.13+ environment. Then
+
+% pip install mls-parser
+
+At this point you can invoke the parser via the command line or from your python script.
+
+#### From your python script
+
+You need this import statement at a minimum:
+
+    from mls-parser.parser import LayoutParser
+
+You can then specify a path as shown:
+
+    result = LayoutParser.parse_file(file_input=path_to_file, debug=False)
+
+In either case, `result` will be a list of parsed class model elements. You may find the header of the `visitor.py`
+file helpful in interpreting these results.
+
+#### From the command line
+
+This is not the intended usage scenario, but may be helpful for testing or exploration. Since the parser
+may generate some diagnostic info you may want to create a fresh working directory and cd into it
+first. From there...
+
+    % mls elevator.mls
+
+The .xcm extension is not necessary, but the file must contain xcm text. See this repository's wiki for
+more about the mls language. The grammar is defined in the [layout.peg](https://github.com/modelint/mls-parser/blob/main/src/mls_parser/layout.peg) file. (if the link breaks after I do some update to the code, 
+just browse through the code looking for the class_model.peg file, and let me know so I can fix it)
+
+You can also specify a debug option like this:
+
+    % mls elevator.mls -D
+
+This will create a scrall-diagnostics folder in your current working directory and deposite a coupel of PDFs defining
+the parse of both the class model grammar: `class_model_tree.pdf` and your supplied text: `class_model.pdf`.
+
+You should also see a file named `mls-parser.log` in a diagnostics directory within your working directory

mls_parser-0.0.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+mls_parser/__init__.py,sha256=zWVHf3DqIS6sYe780DU38lmTH_EXQUcBK32nOsBO7ao,18
+mls_parser/__main__.py,sha256=NkowelWxc7cc6HRmcRRcWMdMShy0nKC4uO4Rm9EuB-g,1877
+mls_parser/exceptions.py,sha256=hJx2OZPTEFOS4RqZJfH0meqV4ZzH7iBP7O9fXLV_McI,3059
+mls_parser/layout.peg,sha256=BBAeHYR5hBgThUtCej5FmiphI3DlV_1kGJh4NgvnFLo,6019
+mls_parser/layout_parser.py,sha256=fahdd8YeyJybJXZzz-lDoMi202Sv5UFJa0oGGmMiYcA,4854
+mls_parser/layout_visitor.py,sha256=krXYZHIs0UkwJ446fYEmyLs448Iq5nPmOa2QRIh0rHI,18008
+mls_parser/log.conf,sha256=EL_8Pn8A7gz1IV_AODmgtQdBsOREtmhaoomIuAxMSLk,867
+mls_parser-0.0.2.dist-info/LICENSE,sha256=kL0xVrwl2i3Pk9mQXAVAPANCTaLGGOsoXgvqW7TBs20,1072
+mls_parser-0.0.2.dist-info/METADATA,sha256=pEBz1x1dFI3geJSkm09J8nojcG0QykMgsJxsVf7B3Dk,4026
+mls_parser-0.0.2.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
+mls_parser-0.0.2.dist-info/entry_points.txt,sha256=HsIgu1_OJw84-8oMi7zGKznq7oQgpviMC_HL46vsjVo,49
+mls_parser-0.0.2.dist-info/top_level.txt,sha256=s_pWxPSrMvumqwFDqPVWrajhZO2giOrZg9acHgn6h8Q,11
+mls_parser-0.0.2.dist-info/RECORD,,

mls_parser-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mls_parser-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mls = mls_parser.__main__:main

mls_parser-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+mls_parser