links-notation 0.9.0__tar.gz

links_notation-0.9.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include platform_lino *.py

links_notation-0.9.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,163 @@
+# 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/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-0.9.0/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-0.9.0/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 [' ', ':', '(', ')'])