lhtml-markup 2.0.0__py3-none-any.whl

lhtml/__init__.py

@@ -0,0 +1,97 @@
+"""LHTML — Lightweight HTML markup language.
+
+A simple markup language that extends HTML with shorthand syntax
+for styling, layout, and content formatting.
+
+Usage:
+    import lhtml
+    html = lhtml.run(text)
+    html = lhtml.run(text, {'wrap-auto': True, 'title': 'My Page'})
+"""
+
+from .element_extract import extract_bracket_elements
+from .insert_in_text import insert_element_from_index, remove_element_to_index
+from .wrap_html import wrap_auto
+
+from .process import (
+    process_yaml, process_verbatim_to_index, process_verbatim_back_from_index,
+    process_remove_comment, process_include, find_file,
+    process_bold, process_italic, process_code_inline,
+    process_title, process_tag, process_code,
+    process_listing,
+)
+
+from .errors import (
+    LHTMLError, LHTMLParseError, LHTMLFileNotFound,
+    LHTMLTagStackError, LHTMLIncludeLoopError,
+)
+
+from .ast_nodes import (
+    LHTMLDocument, TextNode, TagElement, HeadingNode,
+    ListNode, ListItem, InlineFormat, CodeBlock,
+    VerbatimBlock, IncludeDirective, Comment, SpacerNode, ClosingTag,
+)
+
+from .pipeline import ProcessingPipeline, tag_registry, lexer_registry
+
+
+# ---------------------------------------------------------------------------
+# Public API (backward-compatible with the old lhtml.py module)
+# ---------------------------------------------------------------------------
+
+_pipeline = ProcessingPipeline()
+
+
+def run(text, meta_arg=None):
+    """Process LHTML text and return HTML.
+
+    Args:
+        text: LHTML markup string.
+        meta_arg: Optional dict overriding default configuration.
+            Keys: wrap-auto, title, css, js, directory_include, etc.
+
+    Returns:
+        HTML string.
+    """
+    return _pipeline.run(text, meta_arg)
+
+
+def analyse_tag(text_in):
+    """Parse a single :: tag expression (utility)."""
+    return extract_bracket_elements(text_in, text_in.find('::') + 2)
+
+
+def read_yaml(text_in):
+    """Extract YAML front matter from text (utility)."""
+    _, yaml_parameter = process_yaml(text_in)
+    return yaml_parameter
+
+
+def main():
+    """CLI entry point (delegates to cli.main)."""
+    from .cli import main as _cli_main
+    _cli_main()
+
+
+__all__ = [
+    # Core API
+    'run', 'analyse_tag', 'read_yaml', 'main',
+    # Processing functions
+    'extract_bracket_elements',
+    'process_yaml', 'process_verbatim_to_index', 'process_verbatim_back_from_index',
+    'process_remove_comment', 'process_include', 'find_file',
+    'process_bold', 'process_italic', 'process_code_inline',
+    'process_title', 'process_tag', 'process_code',
+    'process_listing',
+    'insert_element_from_index', 'remove_element_to_index',
+    'wrap_auto',
+    # Pipeline & plugins
+    'ProcessingPipeline', 'tag_registry', 'lexer_registry',
+    # AST
+    'LHTMLDocument', 'TextNode', 'TagElement', 'HeadingNode',
+    'ListNode', 'ListItem', 'InlineFormat', 'CodeBlock',
+    'VerbatimBlock', 'IncludeDirective', 'Comment', 'SpacerNode', 'ClosingTag',
+    # Errors
+    'LHTMLError', 'LHTMLParseError', 'LHTMLFileNotFound',
+    'LHTMLTagStackError', 'LHTMLIncludeLoopError',
+]

lhtml/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running lhtml as a module: python -m lhtml"""
+
+from .cli import main
+
+main()

lhtml/ast_nodes.py

@@ -0,0 +1,124 @@
+"""AST node definitions for LHTML.
+
+These dataclasses represent the intermediate representation produced
+by the LHTML parser before HTML emission. Each node corresponds to
+an LHTML language construct as defined in grammar.ebnf.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Union
+
+
+# Type alias for any LHTML node
+LHTMLNode = Union[
+    'TextNode', 'TagElement', 'HeadingNode', 'ListNode',
+    'InlineFormat', 'CodeBlock', 'VerbatimBlock',
+    'IncludeDirective', 'Comment', 'SpacerNode', 'ClosingTag'
+]
+
+
+@dataclass
+class LHTMLDocument:
+    """Root node representing a full LHTML document."""
+    meta: dict = field(default_factory=dict)
+    children: list[LHTMLNode] = field(default_factory=list)
+
+
+@dataclass
+class TextNode:
+    """Passthrough text (raw HTML, Jinja2 templates, prose).
+    Not transformed by LHTML — emitted as-is."""
+    content: str
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class TagElement:
+    """An LHTML tag element: tag::(.class #id)[style]{attrs} content ::
+
+    For special tags (link, img, video), the 'text' field holds the
+    URL or file path that appears between :: and the first bracket.
+    """
+    tag: str                        # "div", "span", "link", "img", "video", "videoplay", ""
+    classes: list[str] = field(default_factory=list)
+    id: str | None = None
+    style: str = ''
+    inline_attrs: str = ''
+    text: str = ''                  # URL for link, path for img/video, content for self-closing
+    self_closing: bool = False      # True if content ends with ::
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class HeadingNode:
+    """A heading: =() Title, ==() Subtitle, etc."""
+    level: int                      # 1-6
+    text: str = ''
+    classes: list[str] = field(default_factory=list)
+    id: str | None = None
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class ListItem:
+    """A single list item with its nesting level."""
+    level: int                      # 1 for *, 2 for **, etc.
+    content: str = ''
+
+
+@dataclass
+class ListNode:
+    """A sequence of list items (* item, ** subitem)."""
+    items: list[ListItem] = field(default_factory=list)
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class InlineFormat:
+    """Inline formatting: **bold**, __italic__, `code`."""
+    kind: str                       # "bold" | "italic" | "code"
+    content: str = ''
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class CodeBlock:
+    """A code block: code::[language] ... code::[-]."""
+    language: str = ''
+    content: str = ''
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class VerbatimBlock:
+    """A verbatim block: verbatim::[] ... verbatim::[-].
+    Content is preserved without any LHTML processing."""
+    content: str = ''
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class IncludeDirective:
+    """An include directive: include::filename."""
+    filename: str = ''
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class Comment:
+    """An LHTML comment: ::#comment text."""
+    text: str = ''
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class SpacerNode:
+    """A spacer element: ::nl."""
+    source_span: tuple[int, int] = (0, 0)
+
+
+@dataclass
+class ClosingTag:
+    """A bare closing tag: :: (closes the most recent open tag)."""
+    source_span: tuple[int, int] = (0, 0)

lhtml/cli.py

@@ -0,0 +1,62 @@
+"""LHTML command-line interface.
+
+Usage:
+    lhtml [-w] inputFile [-o outputFile]
+    python -m lhtml [-w] inputFile [-o outputFile]
+"""
+
+import os
+import argparse
+
+from .pipeline import ProcessingPipeline
+
+
+_pipeline = ProcessingPipeline()
+
+
+def _ensure_trailing_newline(text):
+    if text and text[-1] != '\n':
+        return text + '\n'
+    return text
+
+
+def main():
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(description='Lightweight HTML')
+    parser.add_argument('inputFile', help='Input filepath')
+    parser.add_argument('-w', '--wrapAuto',
+                        help='Wrap content in basic HTML template',
+                        action='store_true')
+    parser.add_argument('-o', '--outputFile', help='Output filepath')
+    args = parser.parse_args()
+
+    meta = {}
+    if args.wrapAuto:
+        meta['wrap-auto'] = True
+
+    meta['directory_include'] = [os.getcwd() + '/']
+    f_in = args.inputFile
+
+    if os.path.isfile(f_in):
+        dir_to_include = os.path.dirname(f_in)
+        if dir_to_include:
+            meta['directory_include'].append(
+                os.path.join(os.getcwd(), dir_to_include) + '/'
+            )
+
+        with open(f_in) as fid:
+            txt = _ensure_trailing_newline(fid.read())
+
+        html = _ensure_trailing_newline(_pipeline.run(txt, meta))
+
+        if args.outputFile:
+            with open(args.outputFile, 'w') as f_out:
+                f_out.write(html)
+        else:
+            print(html)
+    else:
+        print(f'Error: unrecognized input file [{f_in}]')
+
+
+if __name__ == '__main__':
+    main()

lhtml/code.py

@@ -0,0 +1,74 @@
+"""Code block syntax highlighting for LHTML.
+
+Uses Pygments for highlighting. Custom lexers can be registered
+via the lexer_registry in pipeline.py.
+"""
+
+from pygments import highlight
+from pygments.lexers import get_lexer_by_name
+from pygments.formatters import HtmlFormatter
+from pygments.lexer import words, inherit
+import pygments.lexers
+
+
+# ---------------------------------------------------------------------------
+# Built-in custom lexer: C++ with CGP library types
+# ---------------------------------------------------------------------------
+
+class CppCgpLexer(pygments.lexers.CppLexer):
+    """Extended C++ lexer with CGP library types and functions."""
+    name = 'C++ (CGP)'
+    tokens = {
+        'statements': [
+            (words((
+                'vec2', 'vec3', 'vec4', 'mat2', 'mat3', 'mat4',
+                'numarray_stack', 'numarray', 'mesh', 'mesh_drawable',
+                'rotation_transform', 'affine_rt', 'affine_rts', 'affine',
+                'quaternion', 'string', 'ostream',
+            ), suffix=r'\b'), pygments.token.Keyword.Type),
+            (words((
+                'dot', 'cross', 'norm', 'normalize',
+                'draw', 'draw_wireframe', 'transpose', 'det', 'inverse',
+            ), suffix=r'\b'), pygments.token.Keyword.Function),
+            (r'gl\w*', pygments.token.Keyword.Function),
+            (r'const\&', pygments.token.Number),
+            (r'std::', pygments.token.Number),
+            (r'cgp::', pygments.token.Number),
+            inherit,
+        ]
+    }
+
+
+# Default custom lexer mapping
+_BUILTIN_LEXERS = {
+    'c++': CppCgpLexer,
+}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def export_html_code(text, language, cssclass='code'):
+    """Highlight a code block and return HTML."""
+    # Check plugin registry first, then built-in lexers
+    lexer_class = None
+    try:
+        from .pipeline import lexer_registry
+        lexer_class = lexer_registry.get(language)
+    except ImportError:
+        pass
+
+    if lexer_class is None:
+        lexer_class = _BUILTIN_LEXERS.get(language)
+
+    if lexer_class is not None:
+        lexer = lexer_class()
+    else:
+        lexer = get_lexer_by_name(
+            language, stripall=False, stripnl=True,
+            ensurenl='True', tabsize=2, encoding='utf-8',
+        )
+
+    formatter = HtmlFormatter(linenos=False, cssclass=cssclass)
+    return highlight(text, lexer, formatter)

lhtml/element_extract.py

@@ -0,0 +1,21 @@
+"""LHTML element extraction from :: tag syntax.
+
+Delegates to the Lark-based parser in tag_parser.py for robust
+bracket parsing with proper nesting support.
+"""
+
+from .tag_parser import extract_bracket_elements_lark
+
+
+def extract_bracket_elements(text, index_start):
+    """Extract bracket elements from an LHTML :: tag expression.
+
+    Args:
+        text: Full document text.
+        index_start: Position right after :: (first char to parse).
+
+    Returns:
+        Dict with keys: '[]', '()', '{}', 'text', 'tag',
+        'index_start', 'index_end'
+    """
+    return extract_bracket_elements_lark(text, index_start)

lhtml/errors.py

@@ -0,0 +1,58 @@
+"""Structured error types for LHTML parsing.
+
+These exceptions carry source location information to help
+users diagnose problems in their LHTML markup.
+"""
+
+
+class LHTMLError(Exception):
+    """Base class for all LHTML errors."""
+
+    def __init__(self, message: str, source_pos: int = -1, source_line: int = -1):
+        self.source_pos = source_pos
+        self.source_line = source_line
+        if source_line >= 0:
+            full_message = f'Line {source_line}: {message}'
+        elif source_pos >= 0:
+            full_message = f'Position {source_pos}: {message}'
+        else:
+            full_message = message
+        super().__init__(full_message)
+
+
+class LHTMLParseError(LHTMLError):
+    """Error during parsing of LHTML markup (unclosed brackets, etc.)."""
+    pass
+
+
+class LHTMLFileNotFound(LHTMLError):
+    """An include:: directive references a file that cannot be found."""
+
+    def __init__(self, filename: str, directories: list[str], source_pos: int = -1, source_line: int = -1):
+        self.filename = filename
+        self.directories = directories
+        message = f'Could not find file [{filename}] in directories {directories}'
+        super().__init__(message, source_pos, source_line)
+
+
+class LHTMLTagStackError(LHTMLError):
+    """A closing :: tag has no matching opening tag."""
+
+    def __init__(self, source_pos: int = -1, source_line: int = -1):
+        message = 'Closing tag :: has no matching opening tag'
+        super().__init__(message, source_pos, source_line)
+
+
+class LHTMLIncludeLoopError(LHTMLError):
+    """Too many include iterations — likely a circular include."""
+
+    def __init__(self, max_iterations: int = 20):
+        message = f'Too many include iterations (>{max_iterations}), possible circular include'
+        super().__init__(message)
+
+
+def pos_to_line(text: str, pos: int) -> int:
+    """Convert a character position to a 1-based line number."""
+    if pos < 0 or pos > len(text):
+        return -1
+    return text[:pos].count('\n') + 1

lhtml/export_html.py

@@ -0,0 +1,147 @@
+"""HTML generation functions for LHTML tag elements.
+
+Each export_html_* function converts a parsed element dict into
+an HTML string. The element dict has keys: '[]' (style), '()'
+(class/id), '{}' (inline attrs), 'text', 'tag'.
+"""
+
+import os
+
+
+# ---------------------------------------------------------------------------
+# Attribute helpers
+# ---------------------------------------------------------------------------
+
+def _build_attrs(elements):
+    """Build the common HTML attribute string from an element dict."""
+    parts = []
+    parts.append(export_html_element_class_and_id(elements['()']))
+    parts.append(export_html_element_style(elements['[]']))
+    parts.append(export_html_element_inline(elements['{}']))
+    return ''.join(parts)
+
+
+def export_html_element_style(text):
+    if not text:
+        return ''
+    return f' style="{text}"'
+
+
+def export_html_element_class_and_id(text):
+    """Parse '.class1 .class2 #id' into class="..." id="..." attributes."""
+    if not text:
+        return ''
+    classes = []
+    ids = []
+    for token in text.split():
+        if token.startswith('.'):
+            classes.append(token[1:])
+        elif token.startswith('#'):
+            ids.append(token[1:])
+    parts = []
+    if classes:
+        parts.append(f' class="{" ".join(classes)}"')
+    if ids:
+        parts.append(f' id="{" ".join(ids)}"')
+    return ''.join(parts)
+
+
+def export_html_element_inline(text):
+    if not text:
+        return ''
+    return ' ' + text
+
+
+# ---------------------------------------------------------------------------
+# Tag element renderers
+# ---------------------------------------------------------------------------
+
+def export_html_generic(elements, tag, tag_to_close):
+    """Render a generic div/span element."""
+    html = f'<{tag}{_build_attrs(elements)}>'
+
+    text = elements['text']
+    if text:
+        if text.endswith('::'):
+            text = text[:-2]
+            html += text + f'</{tag}>'
+            return html
+        html += text
+
+    tag_to_close.append(tag)
+    return html
+
+
+def export_html_link(elements):
+    """Render a link:: element as <a href="...">text</a>."""
+    attrs = export_html_element_class_and_id(elements['()'])
+    attrs += export_html_element_inline(elements['{}'])
+    return f'<a{attrs} href="{elements["text"]}">{elements["[]"]}</a>'
+
+
+def export_html_img(elements):
+    """Render an img:: element as <img src="..." alt="...">."""
+    src = elements['text']
+    return f'<img{_build_attrs(elements)} src="{src}" alt="{src}">'
+
+
+# ---------------------------------------------------------------------------
+# Video rendering with codec detection
+# ---------------------------------------------------------------------------
+
+CACHE_VIDEO_DIR = 'cache_video_codecs/'
+
+VIDEO_CODECS = [
+    ('-vp9.webm',  'video/webm'),
+    ('-h265.mp4',  'video/mp4'),
+    ('-h264.mp4',  'video/mp4'),
+]
+
+
+def export_html_video(elements, default_inline='', current_directory=''):
+    """Render a video:: or videoplay:: element with codec variants."""
+    source = elements['text']
+    extension = source.rsplit('.', 1)[-1]
+    poster_candidate = source.rsplit(f'.{extension}', 1)[0] + '-poster.jpg'
+
+    parts = ['<video']
+    parts.append(export_html_element_inline(elements['{}']))
+    if default_inline:
+        parts.append(f' {default_inline} ')
+    parts.append(export_html_element_class_and_id(elements['()']))
+    parts.append(export_html_element_style(elements['[]']))
+    if os.path.isfile(poster_candidate):
+        parts.append(f' poster="{poster_candidate}"')
+    parts.append('>\n')
+
+    # Look for transcoded codec variants
+    source_name, _ = os.path.splitext(source)
+    source_basename = os.path.basename(source_name)
+    source_dirname = os.path.dirname(source_name)
+
+    found_codecs = False
+    if current_directory and os.path.basename(source_dirname) == 'assets':
+        codec_dir = os.path.join(source_dirname, CACHE_VIDEO_DIR)
+        full_codec_dir = os.path.join(current_directory, codec_dir)
+        if os.path.isdir(full_codec_dir):
+            for suffix, mime in VIDEO_CODECS:
+                candidate = os.path.join(codec_dir, source_basename + suffix)
+                if os.path.isfile(os.path.join(current_directory, candidate)):
+                    parts.append(f'\t<source src="{candidate}" type="{mime}">\n')
+                    found_codecs = True
+
+    if not found_codecs:
+        parts.append(f'\t<source src="{source}" type="video/{extension}">\n')
+
+    parts.append(f'\t Cannot play video {source}\n')
+    parts.append('</video>')
+    return ''.join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Closing tag detection
+# ---------------------------------------------------------------------------
+
+def check_is_closing_tag(elements):
+    """A bare :: (empty tag, span of exactly 2) is a closing tag."""
+    return elements['tag'] == '' and elements['index_end'] - elements['index_start'] == 2

lhtml/insert_in_text.py

@@ -0,0 +1,7 @@
+"""Backward-compatible aliases for store/restore functions.
+
+The actual implementations are in patterns.py.
+"""
+
+from .patterns import store_to_index as remove_element_to_index
+from .patterns import restore_from_index as insert_element_from_index

lhtml/listing.py

@@ -0,0 +1,54 @@
+"""List processing for LHTML.
+
+Converts * item / ** subitem syntax to nested <ul><li> HTML.
+"""
+
+import io
+import re
+
+_LIST_ITEM = re.compile(r'^(\*+) (.*)')
+
+
+def _analyse_line(line):
+    """Extract nesting level and content from a line."""
+    m = _LIST_ITEM.search(line)
+    if m:
+        return len(m.group(1)), m.group(2) + '\n'
+    return 0, line
+
+
+def process_listing(text):
+    """Convert * / ** / *** list items to nested <ul><li> HTML."""
+    lines = []
+    buf = io.StringIO(text)
+    for line in buf:
+        lines.append(_analyse_line(line))
+
+    parts = []
+    level = 0
+
+    for k, (line_level, content) in enumerate(lines):
+        # Open deeper levels
+        while level < line_level:
+            level += 1
+            if level > 1:
+                parts.append('<li>\n')
+            parts.append('<ul>\n')
+
+        if level > 0:
+            parts.append('<li>\n')
+
+        parts.append(content)
+
+        if level > 0:
+            parts.append('</li>\n')
+
+        # Close shallower levels (peek at next line)
+        next_level = lines[k + 1][0] if k < len(lines) - 1 else 0
+        while level > next_level:
+            level -= 1
+            parts.append('</ul>\n')
+            if level >= 1:
+                parts.append('</li>\n')
+
+    return ''.join(parts)