links-notation 0.9.0__py3-none-any.whl

links_notation/__init__.py

@@ -0,0 +1,14 @@
+"""
+Platform.Protocols.Lino - Python implementation
+
+Lino (Links Notation) is a simple, intuitive format for representing
+structured data as links between references.
+"""
+
+from .link import Link
+from .parser import Parser
+from .formatter import format_links
+
+__version__ = "0.7.0"
+
+__all__ = ["Link", "Parser", "format_links"]

links_notation/formatter.py

@@ -0,0 +1,24 @@
+"""
+Formatter for Lino notation.
+
+Provides utilities for formatting Link objects back into Lino notation strings.
+"""
+
+from typing import List
+from .link import Link
+
+
+def format_links(links: List[Link], less_parentheses: bool = False) -> str:
+    """
+    Format a list of links into Lino notation.
+
+    Args:
+        links: List of Link objects to format
+        less_parentheses: If True, omit parentheses where safe
+
+    Returns:
+        Formatted string in Lino notation
+    """
+    if not links:
+        return ''
+    return '\n'.join(link.format(less_parentheses) for link in links)

links_notation/link.py

@@ -0,0 +1,178 @@
+"""
+Link class representing a Lino link with optional ID and values.
+"""
+
+from typing import List, Optional
+
+
+class Link:
+    """
+    Represents a link in Lino notation.
+
+    A link can be:
+    - A simple reference (id only, no values)
+    - A link with id and values
+    - A link with only values (no id)
+    """
+
+    def __init__(self, link_id: Optional[str] = None, values: Optional[List['Link']] = None):
+        """
+        Initialize a Link.
+
+        Args:
+            link_id: Optional identifier for the link
+            values: Optional list of child links
+        """
+        self.id = link_id
+        self.values = values if values is not None else []
+        self._is_from_path_combination = False
+
+    def __str__(self) -> str:
+        """String representation using standard formatting."""
+        return self.format(False)
+
+    def __repr__(self) -> str:
+        """Developer-friendly representation."""
+        return f"Link(id={self.id!r}, values={self.values!r})"
+
+    def __eq__(self, other) -> bool:
+        """Check equality with another Link."""
+        if not isinstance(other, Link):
+            return False
+        if self.id != other.id:
+            return False
+        if len(self.values) != len(other.values):
+            return False
+        return all(v1 == v2 for v1, v2 in zip(self.values, other.values))
+
+    def get_values_string(self) -> str:
+        """Get formatted string of all values."""
+        if not self.values:
+            return ''
+        return ' '.join(Link.get_value_string(v) for v in self.values)
+
+    def simplify(self) -> 'Link':
+        """
+        Simplify the link structure.
+        - If no values, return self
+        - If single value, return that value
+        - Otherwise return new Link with simplified values
+        """
+        if not self.values:
+            return self
+        elif len(self.values) == 1:
+            return self.values[0]
+        else:
+            new_values = [v.simplify() for v in self.values]
+            return Link(self.id, new_values)
+
+    def combine(self, other: 'Link') -> 'Link':
+        """Combine this link with another to create a compound link."""
+        return Link(None, [self, other])
+
+    @staticmethod
+    def get_value_string(value: 'Link') -> str:
+        """Get string representation of a value."""
+        return value.to_link_or_id_string()
+
+    @staticmethod
+    def escape_reference(reference: Optional[str]) -> str:
+        """
+        Escape a reference string if it contains special characters.
+
+        Args:
+            reference: The reference string to escape
+
+        Returns:
+            Escaped reference with quotes if needed
+        """
+        if not reference or not reference.strip():
+            return ''
+
+        # Check if single quotes are needed
+        needs_single_quotes = any(c in reference for c in [':', '(', ')', ' ', '\t', '\n', '\r', '"'])
+
+        if needs_single_quotes:
+            return f"'{reference}'"
+        elif "'" in reference:
+            return f'"{reference}"'
+        else:
+            return reference
+
+    def to_link_or_id_string(self) -> str:
+        """Convert to string, using just ID if no values, otherwise full format."""
+        if not self.values:
+            return Link.escape_reference(self.id) if self.id is not None else ''
+        return str(self)
+
+    def format(self, less_parentheses: bool = False, is_compound_value: bool = False) -> str:
+        """
+        Format the link as a string.
+
+        Args:
+            less_parentheses: If True, omit parentheses when safe
+            is_compound_value: If True, this is a value in a compound link
+
+        Returns:
+            Formatted string representation
+        """
+        # Empty link
+        if self.id is None and not self.values:
+            return '' if less_parentheses else '()'
+
+        # Link with only ID, no values
+        if not self.values:
+            escaped_id = Link.escape_reference(self.id)
+            # When used as a value in a compound link, wrap in parentheses
+            if is_compound_value:
+                return f'({escaped_id})'
+            return escaped_id if (less_parentheses and not self.needs_parentheses(self.id)) else f'({escaped_id})'
+
+        # Format values recursively
+        values_str = ' '.join(self.format_value(v) for v in self.values)
+
+        # Link with values only (null id)
+        if self.id is None:
+            if less_parentheses:
+                # Check if all values are simple (no nested values)
+                all_simple = all(not v.values for v in self.values)
+                if all_simple:
+                    # Format each value without extra wrapping
+                    return ' '.join(Link.escape_reference(v.id) for v in self.values)
+                # For mixed or complex values, return without outer wrapper
+                return values_str
+            # For normal mode, wrap in parentheses
+            return f'({values_str})'
+
+        # Link with ID and values
+        id_str = Link.escape_reference(self.id)
+        with_colon = f'{id_str}: {values_str}'
+        return with_colon if (less_parentheses and not self.needs_parentheses(self.id)) else f'({with_colon})'
+
+    def format_value(self, value: 'Link') -> str:
+        """
+        Format a single value within this link.
+
+        Args:
+            value: The value link to format
+
+        Returns:
+            Formatted string for the value
+        """
+        # Check if we're in a compound link from path combinations
+        is_compound_from_paths = self._is_from_path_combination
+
+        # For compound links from paths, format values with parentheses
+        if is_compound_from_paths:
+            return value.format(False, True)
+
+        # Simple link with just an ID - don't wrap in parentheses when used as a value
+        if not value.values:
+            return Link.escape_reference(value.id)
+
+        # Complex value with its own structure - format it normally with parentheses
+        return value.format(False, False)
+
+    def needs_parentheses(self, s: Optional[str]) -> bool:
+        """Check if a string needs to be wrapped in parentheses."""
+        return s and any(c in s for c in [' ', ':', '(', ')'])

links_notation/parser.py

@@ -0,0 +1,350 @@
+"""
+Parser for Lino notation.
+
+This module provides parsing functionality for Links Notation (Lino),
+converting text into structured Link objects.
+"""
+
+from typing import List, Optional, Dict, Any
+from .link import Link
+
+
+class ParseError(Exception):
+    """Exception raised when parsing fails."""
+
+
+class Parser:
+    """
+    Parser for Lino notation.
+
+    Handles both inline and indented syntax for defining links.
+    """
+
+    def __init__(self):
+        """Initialize the parser."""
+        self.indentation_stack = [0]
+        self.pos = 0
+        self.text = ""
+        self.lines = []
+
+    def parse(self, input_text: str) -> List[Link]:
+        """
+        Parse Lino notation text into a list of Link objects.
+
+        Args:
+            input_text: Text in Lino notation
+
+        Returns:
+            List of parsed Link objects
+
+        Raises:
+            ParseError: If parsing fails
+        """
+        try:
+            if not input_text or not input_text.strip():
+                return []
+
+            self.text = input_text
+            self.lines = input_text.split('\n')
+            self.pos = 0
+            self.indentation_stack = [0]
+
+            raw_result = self._parse_document()
+            return self._transform_result(raw_result)
+        except Exception as e:
+            raise ParseError(f"Parse error: {str(e)}") from e
+
+    def _parse_document(self) -> List[Dict]:
+        """Parse the entire document."""
+        self.pos = 0
+        links = []
+
+        while self.pos < len(self.lines):
+            line = self.lines[self.pos]
+            if line.strip():  # Skip empty lines
+                element = self._parse_element(0)
+                if element:
+                    links.append(element)
+            else:
+                self.pos += 1
+
+        return links
+
+    def _parse_element(self, current_indent: int) -> Optional[Dict]:
+        """Parse a single element (link or reference) at given indentation."""
+        if self.pos >= len(self.lines):
+            return None
+
+        line = self.lines[self.pos]
+        indent = len(line) - len(line.lstrip(' '))
+
+        if indent < current_indent:
+            return None
+
+        content = line.strip()
+        if not content:
+            self.pos += 1
+            return None
+
+        self.pos += 1
+
+        # Try to parse the line
+        element = self._parse_line_content(content)
+
+        # Check for children (indented lines that follow)
+        children = []
+        child_indent = indent + 2  # Expect at least 2 spaces for child
+
+        while self.pos < len(self.lines):
+            next_line = self.lines[self.pos]
+            next_indent = len(next_line) - len(next_line.lstrip(' '))
+
+            if next_line.strip() and next_indent > indent:
+                # This is a child
+                child = self._parse_element(child_indent if not children else indent + 2)
+                if child:
+                    children.append(child)
+            else:
+                break
+
+        if children:
+            element['children'] = children
+
+        return element
+
+    def _parse_line_content(self, content: str) -> Dict:
+        """Parse the content of a single line."""
+        # Try multiline link format: (id: values) or (values)
+        if content.startswith('(') and content.endswith(')'):
+            inner = content[1:-1].strip()
+            return self._parse_parenthesized(inner)
+
+        # Try indented ID syntax: id:
+        if content.endswith(':'):
+            id_part = content[:-1].strip()
+            ref = self._extract_reference(id_part)
+            return {'id': ref, 'values': [], 'is_indented_id': True}
+
+        # Try single-line link: id: values
+        if ':' in content and not (content.startswith('"') or content.startswith("'")):
+            parts = content.split(':', 1)
+            if len(parts) == 2:
+                id_part = parts[0].strip()
+                values_part = parts[1].strip()
+                ref = self._extract_reference(id_part)
+                values = self._parse_values(values_part)
+                return {'id': ref, 'values': values}
+
+        # Simple value list
+        values = self._parse_values(content)
+        return {'values': values}
+
+    def _parse_parenthesized(self, inner: str) -> Dict:
+        """Parse content within parentheses."""
+        # Check for id: values format
+        colon_pos = self._find_colon_outside_quotes(inner)
+        if colon_pos >= 0:
+            id_part = inner[:colon_pos].strip()
+            values_part = inner[colon_pos + 1:].strip()
+            ref = self._extract_reference(id_part)
+            values = self._parse_values(values_part)
+            return {'id': ref, 'values': values}
+
+        # Just values
+        values = self._parse_values(inner)
+        return {'values': values}
+
+    def _find_colon_outside_quotes(self, text: str) -> int:
+        """Find the position of a colon that's not inside quotes."""
+        in_single = False
+        in_double = False
+
+        for i, char in enumerate(text):
+            if char == "'" and not in_double:
+                in_single = not in_single
+            elif char == '"' and not in_single:
+                in_double = not in_double
+            elif char == ':' and not in_single and not in_double:
+                return i
+
+        return -1
+
+    def _parse_values(self, text: str) -> List[Dict]:
+        """Parse a space-separated list of values."""
+        if not text:
+            return []
+
+        values = []
+        current = ""
+        in_single = False
+        in_double = False
+        paren_depth = 0
+
+        i = 0
+        while i < len(text):
+            char = text[i]
+
+            if char == "'" and not in_double:
+                in_single = not in_single
+                current += char
+            elif char == '"' and not in_single:
+                in_double = not in_double
+                current += char
+            elif char == '(' and not in_single and not in_double:
+                paren_depth += 1
+                current += char
+            elif char == ')' and not in_single and not in_double:
+                paren_depth -= 1
+                current += char
+            elif char == ' ' and not in_single and not in_double and paren_depth == 0:
+                # End of current value
+                if current.strip():
+                    values.append(self._parse_value(current.strip()))
+                current = ""
+            else:
+                current += char
+
+            i += 1
+
+        # Add last value
+        if current.strip():
+            values.append(self._parse_value(current.strip()))
+
+        return values
+
+    def _parse_value(self, value: str) -> Dict:
+        """Parse a single value (could be a reference or nested link)."""
+        # Nested link in parentheses
+        if value.startswith('(') and value.endswith(')'):
+            inner = value[1:-1].strip()
+            return self._parse_parenthesized(inner)
+
+        # Simple reference
+        ref = self._extract_reference(value)
+        return {'id': ref}
+
+    def _extract_reference(self, text: str) -> str:
+        """Extract reference, handling quoted strings."""
+        text = text.strip()
+
+        # Double quoted
+        if text.startswith('"') and text.endswith('"'):
+            return text[1:-1]
+
+        # Single quoted
+        if text.startswith("'") and text.endswith("'"):
+            return text[1:-1]
+
+        # Unquoted
+        return text
+
+    def _transform_result(self, raw_result: List[Dict]) -> List[Link]:
+        """Transform raw parse result into Link objects."""
+        links = []
+
+        for item in raw_result:
+            if item:
+                self._collect_links(item, [], links)
+
+        return links
+
+    def _collect_links(self, item: Dict, parent_path: List[Link], result: List[Link]) -> None:
+        """
+        Recursively collect links from parse tree.
+
+        Handles both inline and indented syntax, flattening the hierarchy
+        appropriately.
+        """
+        if not item:
+            return
+
+        children = item.get('children', [])
+
+        # Special case: indented ID syntax (id: followed by children)
+        if item.get('is_indented_id') and item.get('id') and not item.get('values') and children:
+            child_values = []
+            for child in children:
+                # Extract the reference from child's values
+                if child.get('values') and len(child['values']) == 1:
+                    child_values.append(self._transform_link(child['values'][0]))
+                else:
+                    child_values.append(self._transform_link(child))
+
+            link_with_children = {
+                'id': item['id'],
+                'values': child_values
+            }
+            current_link = self._transform_link(link_with_children)
+
+            if not parent_path:
+                result.append(current_link)
+            else:
+                result.append(self._combine_path_elements(parent_path, current_link))
+
+        # Regular indented structure
+        elif children:
+            current_link = self._transform_link(item)
+
+            # Add the link combined with parent path
+            if not parent_path:
+                result.append(current_link)
+            else:
+                result.append(self._combine_path_elements(parent_path, current_link))
+
+            # Process each child with this item in the path
+            new_path = parent_path + [current_link]
+
+            for child in children:
+                self._collect_links(child, new_path, result)
+
+        # Leaf item or item with inline values
+        else:
+            current_link = self._transform_link(item)
+
+            if not parent_path:
+                result.append(current_link)
+            else:
+                result.append(self._combine_path_elements(parent_path, current_link))
+
+    def _combine_path_elements(self, path_elements: List[Link], current: Link) -> Link:
+        """Combine path elements into a single link."""
+        if not path_elements:
+            return current
+
+        if len(path_elements) == 1:
+            combined = Link(None, [path_elements[0], current])
+            combined._is_from_path_combination = True
+            return combined
+
+        # For multiple path elements, build proper nesting
+        parent_path = path_elements[:-1]
+        last_element = path_elements[-1]
+
+        # Build the parent structure
+        parent = self._combine_path_elements(parent_path, last_element)
+
+        # Add current element to the built structure
+        combined = Link(None, [parent, current])
+        combined._is_from_path_combination = True
+        return combined
+
+    def _transform_link(self, item: Any) -> Link:
+        """Transform a parsed item into a Link object."""
+        if isinstance(item, Link):
+            return item
+
+        if not isinstance(item, dict):
+            return Link(str(item))
+
+        # Simple reference
+        if 'id' in item and 'values' not in item:
+            return Link(item['id'])
+
+        # Link with values
+        if 'values' in item:
+            link_id = item.get('id')
+            values = [self._transform_link(v) for v in item['values']]
+            return Link(link_id, values)
+
+        # Default
+        return Link(item.get('id'))

links_notation-0.9.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: links-notation
+Version: 0.9.0
+Summary: Python implementation of the Lino protocol parser
+Author-email: LinksPlatform <noreply@linksplatform.com>
+License: Unlicense
+Project-URL: Homepage, https://github.com/link-foundation/links-notation
+Project-URL: Repository, https://github.com/link-foundation/links-notation
+Project-URL: Issues, https://github.com/link-foundation/links-notation/issues
+Keywords: lino,parser,links,notation,protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Public Domain
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Platform.Protocols.Lino - Python
+
+[![PyPI version](https://img.shields.io/pypi/v/platform-lino.svg)](https://pypi.org/project/platform-lino/)
+[![Python versions](https://img.shields.io/pypi/pyversions/platform-lino.svg)](https://pypi.org/project/platform-lino/)
+[![License](https://img.shields.io/badge/license-Unlicense-blue.svg)](../LICENSE)
+
+Python implementation of the Lino (Links Notation) protocol parser.
+
+## Installation
+
+```bash
+pip install platform-lino
+```
+
+## Quick Start
+
+```python
+from platform_lino import Parser
+
+parser = Parser()
+links = parser.parse("papa (lovesMama: loves mama)")
+
+# Access parsed links
+for link in links:
+    print(link)
+```
+
+## Usage
+
+### Basic Parsing
+
+```python
+from platform_lino import Parser, format_links
+
+parser = Parser()
+
+# Parse simple links
+links = parser.parse("(papa: loves mama)")
+print(links[0].id)  # 'papa'
+print(len(links[0].values))  # 2
+
+# Format links back to string
+output = format_links(links)
+print(output)  # (papa: loves mama)
+```
+
+### Working with Link Objects
+
+```python
+from platform_lino import Link
+
+# Create links programmatically
+link = Link('parent', [Link('child1'), Link('child2')])
+print(str(link))  # (parent: child1 child2)
+
+# Access link properties
+print(link.id)  # 'parent'
+print(link.values[0].id)  # 'child1'
+
+# Combine links
+combined = link.combine(Link('another'))
+print(str(combined))  # ((parent: child1 child2) another)
+```
+
+### Indented Syntax
+
+```python
+parser = Parser()
+
+# Parse indented notation
+text = """3:
+  papa
+  loves
+  mama"""
+
+links = parser.parse(text)
+# Produces: (3: papa loves mama)
+```
+
+## API Reference
+
+### Parser
+
+The main parser class for Lino notation.
+
+- `parse(input_text: str) -> List[Link]`: Parse Lino text into Link objects
+
+### Link
+
+Represents a link in Lino notation.
+
+- `__init__(id: Optional[str] = None, values: Optional[List[Link]] = None)`
+- `format(less_parentheses: bool = False) -> str`: Format as string
+- `simplify() -> Link`: Simplify link structure
+- `combine(other: Link) -> Link`: Combine with another link
+
+### format_links
+
+Format a list of links into Lino notation.
+
+- `format_links(links: List[Link], less_parentheses: bool = False) -> str`
+
+## Examples
+
+### Doublets (2-tuple)
+
+```python
+parser = Parser()
+text = """
+papa (lovesMama: loves mama)
+son lovesMama
+daughter lovesMama
+"""
+links = parser.parse(text)
+```
+
+### Triplets (3-tuple)
+
+```python
+text = """
+papa has car
+mama has house
+(papa and mama) are happy
+"""
+links = parser.parse(text)
+```
+
+### Quoted References
+
+```python
+# References with special characters need quotes
+text = '("has space": "value with: colon")'
+links = parser.parse(text)
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Install development dependencies
+pip install pytest
+
+# Run tests
+pytest
+```
+
+### Building
+
+```bash
+pip install build
+python -m build
+```
+
+## License
+
+This project is released into the public domain under the [Unlicense](../LICENSE).
+
+## Links
+
+- [Main Repository](https://github.com/link-foundation/links-notation)
+- [PyPI Package](https://pypi.org/project/platform-lino/)
+- [Documentation](https://link-foundation.github.io/links-notation/)

links_notation-0.9.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+links_notation/__init__.py,sha256=PYY7mi-4h7kb-J7skq0WejhadC3-3oPTCy55_kMshTE,327
+links_notation/formatter.py,sha256=yj_xgdaszHslJxTnuq2WSpKpsSruhez9zn6pO5QcZjo,589
+links_notation/link.py,sha256=JjVDBEzOT8RRWXLbtl39DDMqqQCETWuHbPm_h5M3IiA,6193
+links_notation/parser.py,sha256=O_mhTS9vjYP6CYfh2fuRDLSFFyBauMSHt4ujZbIfrcI,11252
+links_notation-0.9.0.dist-info/METADATA,sha256=ep2_nwnU2mXU_pQGQQo_VzZHlVzs1Dtpi5CU559TTH8,4199
+links_notation-0.9.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+links_notation-0.9.0.dist-info/top_level.txt,sha256=KyOejsXELNXBmuP4E4qBB8bRmuQWi4iwfpvprt2J8ZI,15
+links_notation-0.9.0.dist-info/RECORD,,

links_notation-0.9.0.dist-info/WHEEL

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

links_notation-0.9.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+links_notation