lhtml-markup 2.4.1__tar.gz → 2.5.0__tar.gz

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lhtml-markup
-Version: 2.4.1
+Version: 2.5.0
 Summary: Lightweight HTML markup language — simplifies HTML authoring with shorthand syntax
 License: MIT
 Project-URL: Homepage, https://github.com/drohmer/lhtml
@@ -62,6 +62,7 @@ lhtml input.l.html                    # Convert to stdout
 lhtml input.l.html -o output.html     # Convert to file
 lhtml input.l.html -w                 # Wrap in full HTML document (--wrapAuto)
 lhtml input.l.html -b                 # Render source line breaks as <br> (--line-breaks)
+lhtml input.l.html -m macros.yaml     # Declare macros, custom :: tags (--macros)
 lhtml a.l.html b.l.html               # Several files: a.html, b.html next to sources
 lhtml a.l.html b.l.html -o build/     # Several files into a directory
 python -m lhtml input.l.html          # Alternative invocation
@@ -112,6 +113,12 @@ html = lhtml.run(text, {
     'css': ['style.css'],
     'js': ['script.js'],
 })
+
+# Macros (custom :: tags, see Macros below)
+html = lhtml.run('box:: x ::\n', {'macros': {'box': {'class': 'box'}}})
+macros = lhtml.load_macros('macros.yaml')            # definitions from files or dicts
+registry = lhtml.registry_with_macros(macros)        # validates them (LHTMLMacroError)
+info = lhtml.describe_macro('box', macros['box'])    # what a definition renders, for docs
 ```
 
 
@@ -414,6 +421,85 @@ include::components/nav.html
 Included files are recursively processed (up to 20 levels); their own YAML front matter is ignored. An included file looks for its own includes first in its own directory, then in `directory_include`. A circular include raises `LHTMLIncludeLoopError`.
 
 
+### Macros (custom tags from a configuration)
+
+A macro is a named `::` tag declared in YAML (or a dict): a shortcut for an
+HTML element with default classes, style and attributes. The styling stays
+in CSS, so a deck or a site changes its look in one place.
+
+```yaml
+# macros.yaml (the definitions may also be at the top level)
+macros:
+  small:  {class: small}
+  credit: {tag: span, class: credit}
+  aside:  {class: aside}
+  box:    {class: box}
+  gap:    {class: gap, empty: true, variant: [s, m, l], default: m}
+  demo:   {tag: iframe, class: demo, empty: true, url: src, attrs: 'frameborder="0"'}
+```
+
+```
+aside::[top:400px;]
+img::assets/figure.png[width:450px;]
+::
+
+box::(.good) **Correct** ::
+gap::l
+credit:: Image: Wikimedia Commons ::
+demo::assets/demo/index.html
+```
+
+Output:
+```html
+<div class="aside" style="top:400px;">
+<img style="width:450px;" src="assets/figure.png" alt="assets/figure.png">
+</div>
+
+<div class="box good"> <strong>Correct</strong> </div>
+<div class="gap gap-l"></div>
+<span class="credit"> Image: Wikimedia Commons </span>
+<iframe class="demo" src="assets/demo/index.html" frameborder="0"></iframe>
+```
+
+| Field | Description |
+|-------|-------------|
+| `tag` | HTML element (default `div`) |
+| `class` | Default classes (space separated) |
+| `style` | Default inline style, placed before the style of the source |
+| `attrs` | Default HTML attributes |
+| `empty` | No content: the element is closed at once (`gap::`, `demo::url`) |
+| `url` | The text after `::` is the value of this attribute (`src`, `data-src`, ...). Not needed for `tag: img`, `video`, `videoplay`, `link`: their text is already the URL |
+| `variant` | The text after `::` selects a variant, added as the class `<first class>-<variant>`; a list restricts the allowed values (an unknown one gives a warning) |
+| `default` | Variant used when none is given (one of the variants) |
+| `doc` | Description, ignored by LHTML (for documentation tools; `lhtml.describe_macro(name, spec)` gives what a definition renders) |
+
+The classes, style and attributes written in the source are added to the
+defaults, then the element is rendered like any element: a macro whose `tag`
+is an LHTML tag (`img`, `video`, `videoplay`, `link`, ...) uses that tag
+(`photo: {tag: img, class: photo}` gives `photo::a.png` an `alt`, `videoplay`
+keeps its codec variants, the `style` of a `link` macro is an attribute since
+`[]` is the link text); a macro never renders through another macro. A macro is closed by `::` or by its name (`::box[-]`). Macros are
+not active inside inline code (`` `box::` `` stays text), and a macro cannot
+replace a built-in tag (`div`, `img`, ...). Unlike `img::`, the URL of a `url`
+macro is not protected from inline formatting (avoid `__` in it).
+
+A variant may be closed at once like any element: `gap::l::`.
+
+Declare them with `-m` / `--macros` (repeatable, later files win), with the
+`macros` key of the front matter (file names relative to the page, or
+definitions), or with `lhtml.run(text, {'macros': ...})` (a dict, a file
+name, or a list of them). The macros of the front matter are added to the
+others (a macro of the same name is replaced, `name: null` removes it). A
+file holds the definitions at its top level or under its only key `macros`
+(`macros` is thus not a macro name). An HTML void element
+(`tag: hr`, `br`, ...) is always empty. Invalid definitions (unknown field,
+wrong type) raise `LHTMLMacroError`.
+
+```bash
+lhtml -m macros.yaml slide.l.html
+```
+
+
 ### YAML Front Matter
 
 The front matter must be at the very beginning of the file (`---` separators elsewhere are kept as text). Input text is normalized first: a leading BOM is removed and CRLF line endings become LF.
@@ -439,6 +525,7 @@ Supported metadata keys:
 | `wrap-auto` | boolean | Wrap output in full HTML document |
 | `line-breaks` | boolean | Render source line breaks as `<br>` |
 | `directory_include` | list | Directories to search for includes |
+| `macros` | string, list or mapping | Macros: YAML file(s) relative to the page, or definitions (see [Macros](#macros-custom-tags-from-a-configuration)) |
 
 
 ## Using LHTML with Jinja2
@@ -553,6 +640,7 @@ All keys for the `meta` dict passed to `lhtml.run()`:
     'js': [],                  # JS files (string or list)
     'directory_include': [cwd],  # Search paths for include:: (default: current directory)
     'current_directory': '',   # Base directory for video codec detection
+    'macros': None,            # Macros: dict, YAML file name, or list of them
 }
 ```
 
@@ -571,10 +659,11 @@ All keys for the `meta` dict passed to `lhtml.run()`:
 
 ```
 src/lhtml/
-  __init__.py          # Public API: run(), analyse_tag(), read_yaml()
+  __init__.py          # Public API: run(), analyse_tag(), read_yaml(), macro functions
   __main__.py          # python -m lhtml
   cli.py               # Command-line interface
   pipeline.py          # ProcessingPipeline, TagRegistry, LexerRegistry
+  macros.py            # Macros: custom :: tags declared in YAML
   process.py           # Core transformation functions
   patterns.py          # Centralized regex patterns and utilities
   tag_parser.py        # Lark-based parser for :: bracket syntax

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/README.md

@@ -43,6 +43,7 @@ lhtml input.l.html                    # Convert to stdout
 lhtml input.l.html -o output.html     # Convert to file
 lhtml input.l.html -w                 # Wrap in full HTML document (--wrapAuto)
 lhtml input.l.html -b                 # Render source line breaks as <br> (--line-breaks)
+lhtml input.l.html -m macros.yaml     # Declare macros, custom :: tags (--macros)
 lhtml a.l.html b.l.html               # Several files: a.html, b.html next to sources
 lhtml a.l.html b.l.html -o build/     # Several files into a directory
 python -m lhtml input.l.html          # Alternative invocation
@@ -93,6 +94,12 @@ html = lhtml.run(text, {
     'css': ['style.css'],
     'js': ['script.js'],
 })
+
+# Macros (custom :: tags, see Macros below)
+html = lhtml.run('box:: x ::\n', {'macros': {'box': {'class': 'box'}}})
+macros = lhtml.load_macros('macros.yaml')            # definitions from files or dicts
+registry = lhtml.registry_with_macros(macros)        # validates them (LHTMLMacroError)
+info = lhtml.describe_macro('box', macros['box'])    # what a definition renders, for docs
 ```
 
 
@@ -395,6 +402,85 @@ include::components/nav.html
 Included files are recursively processed (up to 20 levels); their own YAML front matter is ignored. An included file looks for its own includes first in its own directory, then in `directory_include`. A circular include raises `LHTMLIncludeLoopError`.
 
 
+### Macros (custom tags from a configuration)
+
+A macro is a named `::` tag declared in YAML (or a dict): a shortcut for an
+HTML element with default classes, style and attributes. The styling stays
+in CSS, so a deck or a site changes its look in one place.
+
+```yaml
+# macros.yaml (the definitions may also be at the top level)
+macros:
+  small:  {class: small}
+  credit: {tag: span, class: credit}
+  aside:  {class: aside}
+  box:    {class: box}
+  gap:    {class: gap, empty: true, variant: [s, m, l], default: m}
+  demo:   {tag: iframe, class: demo, empty: true, url: src, attrs: 'frameborder="0"'}
+```
+
+```
+aside::[top:400px;]
+img::assets/figure.png[width:450px;]
+::
+
+box::(.good) **Correct** ::
+gap::l
+credit:: Image: Wikimedia Commons ::
+demo::assets/demo/index.html
+```
+
+Output:
+```html
+<div class="aside" style="top:400px;">
+<img style="width:450px;" src="assets/figure.png" alt="assets/figure.png">
+</div>
+
+<div class="box good"> <strong>Correct</strong> </div>
+<div class="gap gap-l"></div>
+<span class="credit"> Image: Wikimedia Commons </span>
+<iframe class="demo" src="assets/demo/index.html" frameborder="0"></iframe>
+```
+
+| Field | Description |
+|-------|-------------|
+| `tag` | HTML element (default `div`) |
+| `class` | Default classes (space separated) |
+| `style` | Default inline style, placed before the style of the source |
+| `attrs` | Default HTML attributes |
+| `empty` | No content: the element is closed at once (`gap::`, `demo::url`) |
+| `url` | The text after `::` is the value of this attribute (`src`, `data-src`, ...). Not needed for `tag: img`, `video`, `videoplay`, `link`: their text is already the URL |
+| `variant` | The text after `::` selects a variant, added as the class `<first class>-<variant>`; a list restricts the allowed values (an unknown one gives a warning) |
+| `default` | Variant used when none is given (one of the variants) |
+| `doc` | Description, ignored by LHTML (for documentation tools; `lhtml.describe_macro(name, spec)` gives what a definition renders) |
+
+The classes, style and attributes written in the source are added to the
+defaults, then the element is rendered like any element: a macro whose `tag`
+is an LHTML tag (`img`, `video`, `videoplay`, `link`, ...) uses that tag
+(`photo: {tag: img, class: photo}` gives `photo::a.png` an `alt`, `videoplay`
+keeps its codec variants, the `style` of a `link` macro is an attribute since
+`[]` is the link text); a macro never renders through another macro. A macro is closed by `::` or by its name (`::box[-]`). Macros are
+not active inside inline code (`` `box::` `` stays text), and a macro cannot
+replace a built-in tag (`div`, `img`, ...). Unlike `img::`, the URL of a `url`
+macro is not protected from inline formatting (avoid `__` in it).
+
+A variant may be closed at once like any element: `gap::l::`.
+
+Declare them with `-m` / `--macros` (repeatable, later files win), with the
+`macros` key of the front matter (file names relative to the page, or
+definitions), or with `lhtml.run(text, {'macros': ...})` (a dict, a file
+name, or a list of them). The macros of the front matter are added to the
+others (a macro of the same name is replaced, `name: null` removes it). A
+file holds the definitions at its top level or under its only key `macros`
+(`macros` is thus not a macro name). An HTML void element
+(`tag: hr`, `br`, ...) is always empty. Invalid definitions (unknown field,
+wrong type) raise `LHTMLMacroError`.
+
+```bash
+lhtml -m macros.yaml slide.l.html
+```
+
+
 ### YAML Front Matter
 
 The front matter must be at the very beginning of the file (`---` separators elsewhere are kept as text). Input text is normalized first: a leading BOM is removed and CRLF line endings become LF.
@@ -420,6 +506,7 @@ Supported metadata keys:
 | `wrap-auto` | boolean | Wrap output in full HTML document |
 | `line-breaks` | boolean | Render source line breaks as `<br>` |
 | `directory_include` | list | Directories to search for includes |
+| `macros` | string, list or mapping | Macros: YAML file(s) relative to the page, or definitions (see [Macros](#macros-custom-tags-from-a-configuration)) |
 
 
 ## Using LHTML with Jinja2
@@ -534,6 +621,7 @@ All keys for the `meta` dict passed to `lhtml.run()`:
     'js': [],                  # JS files (string or list)
     'directory_include': [cwd],  # Search paths for include:: (default: current directory)
     'current_directory': '',   # Base directory for video codec detection
+    'macros': None,            # Macros: dict, YAML file name, or list of them
 }
 ```
 
@@ -552,10 +640,11 @@ All keys for the `meta` dict passed to `lhtml.run()`:
 
 ```
 src/lhtml/
-  __init__.py          # Public API: run(), analyse_tag(), read_yaml()
+  __init__.py          # Public API: run(), analyse_tag(), read_yaml(), macro functions
   __main__.py          # python -m lhtml
   cli.py               # Command-line interface
   pipeline.py          # ProcessingPipeline, TagRegistry, LexerRegistry
+  macros.py            # Macros: custom :: tags declared in YAML
   process.py           # Core transformation functions
   patterns.py          # Centralized regex patterns and utilities
   tag_parser.py        # Lark-based parser for :: bracket syntax

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/src/lhtml/__init__.py

@@ -9,7 +9,7 @@ Usage:
     html = lhtml.run(text, {'wrap-auto': True, 'title': 'My Page'})
 """
 
-__version__ = '2.4.1'
+__version__ = '2.5.0'
 
 from .element_extract import extract_bracket_elements
 from .insert_in_text import insert_element_from_index, remove_element_to_index
@@ -26,10 +26,11 @@ from .process import (
 
 from .errors import (
     LHTMLError, LHTMLParseError, LHTMLFileNotFound,
-    LHTMLTagStackError, LHTMLIncludeLoopError, LHTMLWarning,
+    LHTMLTagStackError, LHTMLIncludeLoopError, LHTMLWarning, LHTMLMacroError,
 )
 
 from .pipeline import ProcessingPipeline, tag_registry, lexer_registry
+from .macros import describe_macro, load_macros, register_macros, registry_with_macros
 
 
 # ---------------------------------------------------------------------------
@@ -45,7 +46,7 @@ def run(text, meta_arg=None):
     Args:
         text: LHTML markup string.
         meta_arg: Optional dict overriding default configuration.
-            Keys: wrap-auto, title, css, js, directory_include, etc.
+            Keys: wrap-auto, title, css, js, directory_include, macros, etc.
 
     Returns:
         HTML string.
@@ -85,7 +86,8 @@ __all__ = [
     'wrap_auto',
     # Pipeline & plugins
     'ProcessingPipeline', 'tag_registry', 'lexer_registry',
+    'describe_macro', 'load_macros', 'register_macros', 'registry_with_macros',
     # Errors
     'LHTMLError', 'LHTMLParseError', 'LHTMLFileNotFound',
-    'LHTMLTagStackError', 'LHTMLIncludeLoopError', 'LHTMLWarning',
+    'LHTMLTagStackError', 'LHTMLIncludeLoopError', 'LHTMLWarning', 'LHTMLMacroError',
 ]

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/src/lhtml/cli.py

@@ -6,6 +6,7 @@ Usage:
     lhtml [-w] a.l.html b.l.html                  # Multiple files → .html next to sources
     lhtml [-w] a.l.html b.l.html -o build/        # Multiple files → output directory
     lhtml -b file.l.html                          # Source line breaks rendered as <br>
+    lhtml -m macros.yaml file.l.html              # Custom :: tags declared in a YAML file
     lhtml --version
     python -m lhtml [same options]
 """
@@ -17,6 +18,7 @@ import warnings
 
 from . import __version__
 from .errors import LHTMLError
+from .macros import load_macros, registry_with_macros
 from .pipeline import ProcessingPipeline
 from .process import read_source
 
@@ -84,6 +86,8 @@ def main():
     parser.add_argument('-b', '--line-breaks',
                         help='Render the line breaks of the source text as <br>',
                         action='store_true')
+    parser.add_argument('-m', '--macros', action='append', metavar='FILE',
+                        help='YAML file of macros (custom :: tags); may be repeated')
     parser.add_argument('-o', '--output',
                         help='Output file (single input) or directory (multiple inputs)')
     parser.add_argument('-V', '--version', action='version',
@@ -95,6 +99,13 @@ def main():
         meta['wrap-auto'] = True
     if args.line_breaks:
         meta['line-breaks'] = True
+    if args.macros:
+        try:
+            meta['macros'] = load_macros([os.path.abspath(f) for f in args.macros])
+            registry_with_macros(meta['macros'])  # validate before processing files
+        except LHTMLError as e:
+            print(f'lhtml: error: {e}', file=sys.stderr)
+            sys.exit(1)
 
     single_file = len(args.inputFiles) == 1
     single_to_stdout = single_file and args.output is None

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/src/lhtml/errors.py

@@ -71,6 +71,10 @@ class LHTMLIncludeLoopError(LHTMLError):
         super().__init__(message)
 
 
+class LHTMLMacroError(LHTMLError):
+    """Invalid macro definition (name, fields or macros file)."""
+
+
 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):

lhtml_markup-2.5.0/src/lhtml/macros.py

@@ -0,0 +1,276 @@
+"""Macros: custom :: tags declared in a configuration (YAML file or dict).
+
+A macro is a named shortcut for an HTML element with default classes,
+style and attributes:
+
+    macros:
+      small:  {class: small}                     # small:: ... ::  -> <div class="small">
+      credit: {tag: span, class: credit}
+      gap:    {class: gap, empty: true, variant: [s, m, l], default: m}
+      demo:   {tag: iframe, class: demo, empty: true, url: src}
+
+Fields (all optional):
+    tag      HTML element (default: div)
+    class    default classes, separated by spaces
+    style    default inline style, placed before the style of the source
+    attrs    default HTML attributes, e.g. 'frameborder="0"'
+    empty    the element has no content: it is closed immediately
+             (gap::, demo::url) instead of waiting for a closing ::
+             (always the case for HTML void elements such as br, hr)
+    url      the text after :: is the value of this attribute (src,
+             data-src, ...); without it, an img, video or link macro takes
+             its URL like img::, video::, link::
+    variant  the text after :: selects a variant, added as the class
+             '<first class>-<variant>' (gap::l -> class="gap gap-l");
+             a list restricts the allowed variants
+    default  variant used when none is given
+    doc      description, for documentation (ignored)
+
+The classes, style and attributes of the source are added to the defaults
+(box::(.good)[margin:0] -> <div class="box good" style="margin:0">).
+A macro is closed by :: or by its name (::box[-]).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import warnings
+
+from .errors import LHTMLMacroError, LHTMLWarning
+from .export_html import _attr, _build_attrs, export_html_generic
+from .pipeline import TagRegistry, tag_registry
+
+
+NAME_RE = re.compile(r'[A-Za-z][A-Za-z0-9_-]*$')
+FIELDS = {'tag', 'class', 'style', 'attrs', 'empty', 'url', 'variant', 'default', 'doc'}
+# HTML elements without closing tag (a macro using them is always empty)
+VOID_TAGS = {'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta',
+             'source', 'track', 'wbr'}
+BUILTIN_TAGS = ('div', 'span', 'link', 'img', 'video', 'videoplay', 'code', 'verbatim',
+                'include', 'nl')
+# LHTML tags whose text is a URL, and the attribute their handler sets with it
+# (these handlers render a complete element: never opened, never empty)
+URL_TAGS = {'img': 'src', 'video': 'src', 'videoplay': 'src', 'link': 'href'}
+RESERVED_NAMES = ('macros',)    # a file may hold its macros under 'macros:'
+NOT_ELEMENTS = ('nl', 'code', 'verbatim', 'include')     # LHTML tags that are not elements
+
+
+class OpenTag(str):
+    """HTML tag name on the stack of open tags, remembering the macro name
+    so that ::name[-] closes it."""
+
+    def __new__(cls, tag, name):
+        obj = super().__new__(cls, tag)
+        obj.name = name
+        return obj
+
+
+def _check(name, spec):
+    if not isinstance(name, str) or not NAME_RE.match(name):
+        raise LHTMLMacroError(f'invalid macro name {name!r}')
+    if name in BUILTIN_TAGS:
+        raise LHTMLMacroError(f'macro {name!r} would replace a built-in tag')
+    if name in RESERVED_NAMES:
+        raise LHTMLMacroError(f'{name!r} is not a macro name (reserved)')
+    if spec is None:
+        spec = {}
+    if not isinstance(spec, dict):
+        raise LHTMLMacroError(f'macro {name!r}: expected a mapping, got {type(spec).__name__}')
+    unknown = set(spec) - FIELDS
+    if unknown:
+        raise LHTMLMacroError(f'macro {name!r}: unknown field(s) {", ".join(sorted(unknown))}')
+    for key in ('tag', 'class', 'style', 'attrs', 'url'):
+        if spec.get(key) is not None and not isinstance(spec[key], str):
+            raise LHTMLMacroError(f'macro {name!r}: {key} must be a string, got {spec[key]!r}')
+    if spec.get('empty') is not None and not isinstance(spec['empty'], bool):
+        raise LHTMLMacroError(f'macro {name!r}: empty must be true or false, got {spec["empty"]!r}')
+    tag = spec.get('tag') or 'div'
+    if not NAME_RE.match(tag):
+        raise LHTMLMacroError(f'macro {name!r}: invalid tag {tag!r}')
+    if tag in NOT_ELEMENTS:
+        raise LHTMLMacroError(f'macro {name!r}: {tag}:: is not an element (tag: {tag})')
+    if spec.get('empty') is False and (tag.lower() in VOID_TAGS or tag in URL_TAGS):
+        raise LHTMLMacroError(f'macro {name!r}: {tag} has no content (empty cannot be false)')
+    if spec.get('url') is not None and not NAME_RE.match(spec['url']):
+        raise LHTMLMacroError(f'macro {name!r}: url must be an attribute name, got {spec["url"]!r}')
+    variant = spec.get('variant')
+    if variant is not None and not isinstance(variant, (bool, list)):
+        raise LHTMLMacroError(f'macro {name!r}: variant must be true or a list')
+    if isinstance(variant, list) and any(not isinstance(v, (str, int)) or isinstance(v, bool)
+                                         for v in variant):
+        raise LHTMLMacroError(f'macro {name!r}: the variants must be names')
+    if spec.get('default') is not None and not isinstance(spec['default'], (str, int)):
+        raise LHTMLMacroError(f'macro {name!r}: default must be a name')
+    if isinstance(variant, list) and spec.get('default') is not None \
+            and str(spec['default']) not in [str(v) for v in variant]:
+        raise LHTMLMacroError(f'macro {name!r}: default {spec["default"]!r} is not one of the variants')
+    if variant and spec.get('url'):
+        raise LHTMLMacroError(f'macro {name!r}: variant and url cannot be combined')
+    if variant and not str(spec.get('class', '')).split():
+        raise LHTMLMacroError(f'macro {name!r}: a variant needs a class')
+    return spec
+
+
+def _join_styles(*styles):
+    """'color:red', 'margin:0' -> 'color:red; margin:0'"""
+    styles = [s.strip() for s in styles if s and s.strip()]
+    return ' '.join(s if s.endswith(';') or k == len(styles) - 1 else s + ';'
+                    for k, s in enumerate(styles))
+
+
+def make_handler(name, spec, base=None):
+    """Tag handler (see TagRegistry) for one macro definition.
+
+    The macro adds its defaults (classes, style, attributes) to the parsed
+    element, then renders it like any element: with the handler of its tag
+    when LHTML has one (img, video, link, ...: `base` registry, the global one
+    by default), else as a generic element. There is thus one rendering path
+    for an element, whether it is written directly or through a macro."""
+    spec = _check(name, spec)
+    tag = spec.get('tag') or 'div'
+    void = tag.lower() in VOID_TAGS
+    classes = (spec.get('class') or '').split()
+    style = (spec.get('style') or '').strip()
+    attrs = (spec.get('attrs') or '').strip()
+    empty = bool(spec.get('empty', False))
+    url = spec.get('url')
+    variant = spec.get('variant')
+    default = spec.get('default')
+    delegate = (base if base is not None else tag_registry).get(tag)
+    if url and url != URL_TAGS.get(tag):
+        delegate = None     # the handler of the tag does not set this attribute
+    url_delegate = delegate is not None and tag in URL_TAGS    # the text is its URL
+    if url_delegate:
+        url = None
+    if tag == 'link' and delegate is not None and style:
+        # [] is the text of a link: the style of the macro is an attribute
+        attrs = ' '.join(a for a in (attrs, f'style="{_attr(style)}"') if a)
+        style = ''
+
+    def handler(element, tag_to_close, current_directory):
+        text = element['text']
+        all_classes = list(classes)
+        if variant:
+            value = text.strip()
+            closed = value.endswith('::')          # gap::l:: (closed at once)
+            if closed:
+                value = value[:-2].strip()
+            value = value or (str(default) if default is not None else '')
+            if value:
+                if isinstance(variant, list) and value not in [str(v) for v in variant]:
+                    warnings.warn(f'{name}::{value}: unknown variant (expected one of '
+                                  f'{", ".join(str(v) for v in variant)}) '
+                                  f'near {element.get("context", "")!r}',
+                                  LHTMLWarning, stacklevel=4)
+                all_classes.append(f'{classes[0]}-{value}')
+            text = '::' if closed else ''
+        inline = ' '.join(a for a in (attrs, element['{}']) if a)
+        if url:
+            closed = text.rstrip().endswith('::')
+            value = text.rstrip()[:-2] if closed else text
+            inline = ' '.join(a for a in (f'{url}="{_attr(value.strip())}"', inline) if a)
+            text = '::' if closed else ''
+        merged = {**element,
+                  '()': ' '.join(['.' + c for c in all_classes] + ([element['()']] if element['()'] else [])),
+                  '[]': _join_styles(style, element['[]']),
+                  '{}': inline,
+                  'text': text}
+        if void and delegate is None:
+            return f'<{tag}{_build_attrs(merged)}>' + ('' if text == '::' else text), True
+        if empty and not url_delegate and not merged['text'].endswith('::'):
+            merged['text'] += '::'   # closed at once
+        depth = len(tag_to_close)
+        if delegate is not None:
+            html, real = delegate(merged, tag_to_close, current_directory)
+        else:
+            html, real = export_html_generic(merged, tag, tag_to_close), True
+        if len(tag_to_close) > depth:
+            tag_to_close[-1] = OpenTag(tag_to_close[-1], name)
+        return html, real
+
+    return handler
+
+
+HTML_TAGS = {'link': 'a', 'videoplay': 'video'}     # LHTML tag -> HTML element
+
+
+def describe_macro(name, spec):
+    """What a macro definition gives, for documentation tools: its opening
+    HTML, the attribute its text sets (url), whether it has no content
+    (empty), its variants (a list, True for any, or None) and default, doc."""
+    spec = _check(name, spec)
+    tag = spec.get('tag') or 'div'
+    html = '<' + HTML_TAGS.get(tag, tag)
+    for attribute in ('class', 'style'):
+        if spec.get(attribute):
+            html += f' {attribute}="{_attr(spec[attribute])}"'
+    if spec.get('attrs'):
+        html += ' ' + spec['attrs'].strip()
+    variant = spec.get('variant')
+    return {'html': html + '>',
+            'url': spec.get('url') or URL_TAGS.get(tag),
+            'empty': bool(spec.get('empty')) or tag.lower() in VOID_TAGS or tag in URL_TAGS,
+            'variants': [str(v) for v in variant] if isinstance(variant, list) else (True if variant else None),
+            'default': None if spec.get('default') is None else str(spec['default']),
+            'doc': spec.get('doc')}
+
+
+def load_macros(source):
+    """Macro definitions from a dict, a YAML file name, or a list of them
+    (later definitions replace earlier ones, and a definition null removes
+    the macro). A dict or file holds the definitions, directly or as its
+    only key 'macros'."""
+    return {name: spec for name, spec in _load_macros(source).items() if spec is not None}
+
+
+def _load_macros(source):
+    if source is None:
+        return {}
+    if isinstance(source, (list, tuple)):
+        merged = {}
+        for item in source:
+            merged.update(_load_macros(item))
+        return merged
+    if isinstance(source, (str, os.PathLike)):
+        import yaml
+        try:
+            with open(source, encoding='utf-8') as f:
+                data = yaml.safe_load(f) or {}
+        except OSError as e:
+            raise LHTMLMacroError(f'cannot read macros file [{source}]: {e}') from e
+        except yaml.YAMLError as e:
+            raise LHTMLMacroError(f'invalid YAML in macros file [{source}]: {e}') from e
+        source = data
+    if not isinstance(source, dict):
+        raise LHTMLMacroError(f'macros: expected a mapping, got {type(source).__name__}')
+    if set(source) == {'macros'}:
+        macros = source['macros']
+        if macros is None:
+            return {}
+        if not isinstance(macros, dict):
+            raise LHTMLMacroError(f"macros: expected a mapping, got {type(macros).__name__}")
+        return dict(macros)
+    return dict(source)
+
+
+def register_macros(macros, registry: TagRegistry | None = None):
+    """Register macro definitions (see load_macros) in a tag registry
+    (the global one by default). Returns the registry."""
+    registry = registry if registry is not None else tag_registry
+    # Macros render through the tags known before them (not through each other)
+    base = TagRegistry()
+    for tag in registry.registered_tags():
+        base.register(tag, registry.get(tag))
+    for name, spec in load_macros(macros).items():
+        registry.register(name, make_handler(name, spec, base))
+    return registry
+
+
+def registry_with_macros(macros, base: TagRegistry | None = None):
+    """A new registry: the tags of `base` (global registry by default) plus the macros."""
+    base = base if base is not None else tag_registry
+    registry = TagRegistry()
+    for name in base.registered_tags():
+        registry.register(name, base.get(name))
+    return register_macros(macros, registry)

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/src/lhtml/pipeline.py

@@ -139,6 +139,15 @@ _register_builtin_tags()
 # Pipeline
 # ---------------------------------------------------------------------------
 
+def _macro_sources(value):
+    """Macros given as a file name, a mapping or a list of them -> list."""
+    if not value:
+        return []
+    if isinstance(value, (list, tuple)):
+        return list(value)
+    return [value]
+
+
 class ProcessingPipeline:
     """Orchestrates the LHTML-to-HTML transformation pipeline.
 
@@ -178,6 +187,16 @@ class ProcessingPipeline:
             directory_include = [directory_include]
         ctx.meta['directory_include'] = [str(d) for d in directory_include]
 
+        # Macros (custom tags) declared in the meta, then in the front matter:
+        # the front matter adds definitions (and replaces those of same name)
+        registry = self.tag_registry
+        macros = _macro_sources((meta_arg or {}).get('macros')) + _macro_sources(meta_yaml.get('macros'))
+        if macros:
+            from .macros import registry_with_macros
+            macros = [m if not isinstance(m, str) or os.path.isabs(m)
+                      else os.path.join(ctx.current_directory, m) for m in macros]
+            registry = registry_with_macros(macros, self.tag_registry)
+
         # Phase 2: For each file: verbatim/code blocks and protected zones
         # (HTML, inline code, URLs, math) are replaced by placeholders,
         # comments are removed, then includes are expanded (recursive)
@@ -192,11 +211,11 @@ class ProcessingPipeline:
         ctx.text = process_italic(ctx.text)
 
         # Phase 5: Tag elements (uses tag_registry). Inside inline code,
-        # only named tags (e.g. link::) are processed.
+        # only named tags (e.g. link::) are processed, macros excepted.
         def resolve_attributes(s):
             return stores.restore(stores.restore(s, 'A'), 'U')
 
-        ctx.text = process_tag(ctx.text, ctx.current_directory, self.tag_registry,
+        ctx.text = process_tag(ctx.text, ctx.current_directory, registry,
                                resolve=resolve_attributes)
         ctx.text = stores.restore(ctx.text, 'I', lambda content: render_inline_code(
             process_tag(content, ctx.current_directory, self.tag_registry, inline=True)))

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/src/lhtml/process.py

@@ -425,7 +425,8 @@ def _dispatch_tag(element, tag_to_close, current_directory, registry=None):
         closing_name = element['text']
         if not tag_to_close:
             return _warn_unmatched_closing(element)
-        if closing_name and tag_to_close[-1] != closing_name:
+        if closing_name and closing_name not in (tag_to_close[-1],
+                                                 getattr(tag_to_close[-1], 'name', None)):
             warnings.warn(
                 f'Closing ::{closing_name}[-] but last opened tag is <{tag_to_close[-1]}> '
                 f'(near {element.get("context", "")!r})',

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/src/lhtml_markup.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lhtml-markup
-Version: 2.4.1
+Version: 2.5.0
 Summary: Lightweight HTML markup language — simplifies HTML authoring with shorthand syntax
 License: MIT
 Project-URL: Homepage, https://github.com/drohmer/lhtml
@@ -62,6 +62,7 @@ lhtml input.l.html                    # Convert to stdout
 lhtml input.l.html -o output.html     # Convert to file
 lhtml input.l.html -w                 # Wrap in full HTML document (--wrapAuto)
 lhtml input.l.html -b                 # Render source line breaks as <br> (--line-breaks)
+lhtml input.l.html -m macros.yaml     # Declare macros, custom :: tags (--macros)
 lhtml a.l.html b.l.html               # Several files: a.html, b.html next to sources
 lhtml a.l.html b.l.html -o build/     # Several files into a directory
 python -m lhtml input.l.html          # Alternative invocation
@@ -112,6 +113,12 @@ html = lhtml.run(text, {
     'css': ['style.css'],
     'js': ['script.js'],
 })
+
+# Macros (custom :: tags, see Macros below)
+html = lhtml.run('box:: x ::\n', {'macros': {'box': {'class': 'box'}}})
+macros = lhtml.load_macros('macros.yaml')            # definitions from files or dicts
+registry = lhtml.registry_with_macros(macros)        # validates them (LHTMLMacroError)
+info = lhtml.describe_macro('box', macros['box'])    # what a definition renders, for docs
 ```
 
 
@@ -414,6 +421,85 @@ include::components/nav.html
 Included files are recursively processed (up to 20 levels); their own YAML front matter is ignored. An included file looks for its own includes first in its own directory, then in `directory_include`. A circular include raises `LHTMLIncludeLoopError`.
 
 
+### Macros (custom tags from a configuration)
+
+A macro is a named `::` tag declared in YAML (or a dict): a shortcut for an
+HTML element with default classes, style and attributes. The styling stays
+in CSS, so a deck or a site changes its look in one place.
+
+```yaml
+# macros.yaml (the definitions may also be at the top level)
+macros:
+  small:  {class: small}
+  credit: {tag: span, class: credit}
+  aside:  {class: aside}
+  box:    {class: box}
+  gap:    {class: gap, empty: true, variant: [s, m, l], default: m}
+  demo:   {tag: iframe, class: demo, empty: true, url: src, attrs: 'frameborder="0"'}
+```
+
+```
+aside::[top:400px;]
+img::assets/figure.png[width:450px;]
+::
+
+box::(.good) **Correct** ::
+gap::l
+credit:: Image: Wikimedia Commons ::
+demo::assets/demo/index.html
+```
+
+Output:
+```html
+<div class="aside" style="top:400px;">
+<img style="width:450px;" src="assets/figure.png" alt="assets/figure.png">
+</div>
+
+<div class="box good"> <strong>Correct</strong> </div>
+<div class="gap gap-l"></div>
+<span class="credit"> Image: Wikimedia Commons </span>
+<iframe class="demo" src="assets/demo/index.html" frameborder="0"></iframe>
+```
+
+| Field | Description |
+|-------|-------------|
+| `tag` | HTML element (default `div`) |
+| `class` | Default classes (space separated) |
+| `style` | Default inline style, placed before the style of the source |
+| `attrs` | Default HTML attributes |
+| `empty` | No content: the element is closed at once (`gap::`, `demo::url`) |
+| `url` | The text after `::` is the value of this attribute (`src`, `data-src`, ...). Not needed for `tag: img`, `video`, `videoplay`, `link`: their text is already the URL |
+| `variant` | The text after `::` selects a variant, added as the class `<first class>-<variant>`; a list restricts the allowed values (an unknown one gives a warning) |
+| `default` | Variant used when none is given (one of the variants) |
+| `doc` | Description, ignored by LHTML (for documentation tools; `lhtml.describe_macro(name, spec)` gives what a definition renders) |
+
+The classes, style and attributes written in the source are added to the
+defaults, then the element is rendered like any element: a macro whose `tag`
+is an LHTML tag (`img`, `video`, `videoplay`, `link`, ...) uses that tag
+(`photo: {tag: img, class: photo}` gives `photo::a.png` an `alt`, `videoplay`
+keeps its codec variants, the `style` of a `link` macro is an attribute since
+`[]` is the link text); a macro never renders through another macro. A macro is closed by `::` or by its name (`::box[-]`). Macros are
+not active inside inline code (`` `box::` `` stays text), and a macro cannot
+replace a built-in tag (`div`, `img`, ...). Unlike `img::`, the URL of a `url`
+macro is not protected from inline formatting (avoid `__` in it).
+
+A variant may be closed at once like any element: `gap::l::`.
+
+Declare them with `-m` / `--macros` (repeatable, later files win), with the
+`macros` key of the front matter (file names relative to the page, or
+definitions), or with `lhtml.run(text, {'macros': ...})` (a dict, a file
+name, or a list of them). The macros of the front matter are added to the
+others (a macro of the same name is replaced, `name: null` removes it). A
+file holds the definitions at its top level or under its only key `macros`
+(`macros` is thus not a macro name). An HTML void element
+(`tag: hr`, `br`, ...) is always empty. Invalid definitions (unknown field,
+wrong type) raise `LHTMLMacroError`.
+
+```bash
+lhtml -m macros.yaml slide.l.html
+```
+
+
 ### YAML Front Matter
 
 The front matter must be at the very beginning of the file (`---` separators elsewhere are kept as text). Input text is normalized first: a leading BOM is removed and CRLF line endings become LF.
@@ -439,6 +525,7 @@ Supported metadata keys:
 | `wrap-auto` | boolean | Wrap output in full HTML document |
 | `line-breaks` | boolean | Render source line breaks as `<br>` |
 | `directory_include` | list | Directories to search for includes |
+| `macros` | string, list or mapping | Macros: YAML file(s) relative to the page, or definitions (see [Macros](#macros-custom-tags-from-a-configuration)) |
 
 
 ## Using LHTML with Jinja2
@@ -553,6 +640,7 @@ All keys for the `meta` dict passed to `lhtml.run()`:
     'js': [],                  # JS files (string or list)
     'directory_include': [cwd],  # Search paths for include:: (default: current directory)
     'current_directory': '',   # Base directory for video codec detection
+    'macros': None,            # Macros: dict, YAML file name, or list of them
 }
 ```
 
@@ -571,10 +659,11 @@ All keys for the `meta` dict passed to `lhtml.run()`:
 
 ```
 src/lhtml/
-  __init__.py          # Public API: run(), analyse_tag(), read_yaml()
+  __init__.py          # Public API: run(), analyse_tag(), read_yaml(), macro functions
   __main__.py          # python -m lhtml
   cli.py               # Command-line interface
   pipeline.py          # ProcessingPipeline, TagRegistry, LexerRegistry
+  macros.py            # Macros: custom :: tags declared in YAML
   process.py           # Core transformation functions
   patterns.py          # Centralized regex patterns and utilities
   tag_parser.py        # Lark-based parser for :: bracket syntax

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/src/lhtml_markup.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/lhtml/errors.py
 src/lhtml/export_html.py
 src/lhtml/insert_in_text.py
 src/lhtml/listing.py
+src/lhtml/macros.py
 src/lhtml/patterns.py
 src/lhtml/pipeline.py
 src/lhtml/process.py

{lhtml_markup-2.4.1 → lhtml_markup-2.5.0}/test/test_lhtml.py

@@ -1351,3 +1351,222 @@ def test_cli_version(flag, monkeypatch, capsys):
 
 def test_version_format():
     assert re.fullmatch(r'\d+\.\d+\.\d+', lhtml.__version__)
+
+
+# ---------------------------------------------------------------------------
+# Macros (custom :: tags declared in a configuration)
+# ---------------------------------------------------------------------------
+
+MACROS = {
+    'small': {'class': 'small'},
+    'credit': {'tag': 'span', 'class': 'credit'},
+    'aside': {'class': 'aside', 'style': 'top:150px;'},
+    'box': {'class': 'box'},
+    'gap': {'class': 'gap', 'empty': True, 'variant': ['s', 'm', 'l'], 'default': 'm'},
+    'demo': {'tag': 'iframe', 'class': 'demo', 'empty': True, 'url': 'src',
+             'attrs': 'frameborder="0"'},
+}
+
+
+def _run_macros(text, macros=MACROS):
+    return lhtml.run(text, {'macros': macros})
+
+
+class TestMacros:
+
+    def test_container(self):
+        assert _run_macros('box::\nx\n::\n') == '<div class="box">\nx\n</div>\n'
+
+    def test_inline_and_other_tag(self):
+        assert _run_macros('credit:: Milo ::\n') == '<span class="credit"> Milo </span>\n'
+
+    def test_classes_and_style_are_added(self):
+        out = _run_macros('aside::(.wide #f)[top:400px;] x ::\n')
+        assert out == '<div class="aside wide" id="f" style="top:150px; top:400px;"> x </div>\n'
+
+    def test_explicit_closing_by_macro_name(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter('error')
+            out = _run_macros('small::\nbox::\nx\n::box[-]\n::small[-]\n')
+        assert out == '<div class="small">\n<div class="box">\nx\n</div>\n</div>\n'
+
+    def test_explicit_closing_by_html_name(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter('error')
+            assert _run_macros('small::\nx\n::div[-]\n') == '<div class="small">\nx\n</div>\n'
+
+    def test_wrong_explicit_closing_warns(self):
+        with pytest.warns(lhtml.LHTMLWarning, match='last opened tag'):
+            _run_macros('small::\nx\n::box[-]\n')
+
+    def test_empty_with_variant(self):
+        assert _run_macros('gap::\ngap::l\n') == ('<div class="gap gap-m"></div>\n'
+                                                  '<div class="gap gap-l"></div>\n')
+
+    def test_unknown_variant_warns(self):
+        with pytest.warns(lhtml.LHTMLWarning, match='unknown variant'):
+            out = _run_macros('gap::xl\n')
+        assert out == '<div class="gap gap-xl"></div>\n'
+
+    def test_url(self):
+        out = _run_macros('demo::assets/ik/index.html#d2[height:700px;]\n')
+        assert out == ('<iframe class="demo" style="height:700px;" '
+                       'src="assets/ik/index.html#d2" frameborder="0"></iframe>\n')
+
+    def test_not_active_inside_inline_code(self):
+        assert _run_macros('`box:: gap::`\n') == '<code class="code-inline">box:: gap::</code>\n'
+
+    def test_unknown_without_macros(self):
+        assert lhtml.run('gap::\n') == 'gap::\n'
+
+    def test_global_registry_unchanged(self):
+        _run_macros('gap::\n')
+        assert not lhtml.tag_registry.has('gap')
+
+    def test_front_matter_file(self, tmp_path):
+        (tmp_path / 'design.yaml').write_text('macros:\n  note: {class: note}\n', encoding='utf-8')
+        out = lhtml.run('---\nmacros: design.yaml\n---\nnote:: hi ::\n',
+                        {'current_directory': str(tmp_path) + '/'})
+        assert out.strip() == '<div class="note"> hi </div>'
+
+    def test_later_definition_wins(self):
+        out = lhtml.run('box:: x ::\n', {'macros': [MACROS, {'box': {'class': 'frame'}}]})
+        assert out == '<div class="frame"> x </div>\n'
+
+    @pytest.mark.parametrize('macros', [
+        {'div': {}}, {'nl': {}}, {'2x': {}}, {'box': {'colour': 'red'}},
+        {'box': 'small'}, {'gap': {'variant': True}},
+        {'box': {'class': ['a', 'b']}}, {'box': {'url': True}}, {'box': {'url': 'a b'}},
+        {'box': {'empty': 'false'}}, {'box': {'tag': 'br', 'empty': False}},
+        {'gap': {'class': 'gap', 'variant': [['s']]}}, {'macros': ['box']},
+    ])
+    def test_invalid_definitions(self, macros):
+        with pytest.raises(lhtml.LHTMLMacroError):
+            lhtml.run('x\n', {'macros': macros})
+
+    def test_cli(self, tmp_path, monkeypatch, capsys):
+        from lhtml import cli
+        (tmp_path / 'm.yaml').write_text('box: {class: box}\n', encoding='utf-8')
+        (tmp_path / 'p.l.html').write_text('box:: x ::\n', encoding='utf-8')
+        monkeypatch.setattr('sys.argv', ['lhtml', '-m', str(tmp_path / 'm.yaml'),
+                                         str(tmp_path / 'p.l.html')])
+        cli.main()
+        assert capsys.readouterr().out == '<div class="box"> x </div>\n'
+
+
+class TestMacrosRegressions:
+
+    def test_front_matter_adds_to_meta_macros(self):
+        out = lhtml.run('---\nmacros: {note: {class: note}}\n---\nbox:: x ::\nnote:: y ::\n',
+                        {'macros': MACROS})
+        assert out.strip() == '<div class="box"> x </div>\n<div class="note"> y </div>'
+
+    def test_front_matter_replaces_same_name(self):
+        out = lhtml.run('---\nmacros: {box: {class: frame}}\n---\nbox:: x ::\n', {'macros': MACROS})
+        assert out.strip() == '<div class="frame"> x </div>'
+
+    def test_void_tag(self):
+        out = lhtml.run('a rule::\nb\n', {'macros': {'rule': {'tag': 'hr', 'class': 'rule'}}})
+        assert out == 'a <hr class="rule">\nb\n'
+
+    def test_macros_key_null(self):
+        assert lhtml.load_macros({'macros': None}) == {}
+
+
+class TestMacrosDelegation:
+    """A macro renders through the handler of its tag (one rendering path)."""
+
+    def test_img_macro_uses_img_handler(self):
+        out = lhtml.run('photo::a.png[width:10px;]\n',
+                        {'macros': {'photo': {'tag': 'img', 'class': 'photo', 'url': 'src'}}})
+        assert out == '<img class="photo" style="width:10px;" src="a.png" alt="a.png">\n'
+
+    def test_videoplay_macro_keeps_video_attributes(self):
+        out = lhtml.run('clip::v.mp4\n', {'macros': {'clip': {'tag': 'videoplay', 'class': 'clip'}}})
+        assert out.startswith('<video autoplay loop muted class="clip">')
+        assert '<source src="v.mp4" type="video/mp4">' in out
+
+    def test_macro_does_not_render_through_another_macro(self):
+        out = lhtml.run('a:: x ::\n', {'macros': {'b': {'class': 'b'}, 'a': {'tag': 'b', 'class': 'a'}}})
+        assert out == '<b class="a"> x </b>\n'
+
+
+class TestMacrosRound2:
+
+    def test_variant_closed_inline(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter('error')
+            assert _run_macros('gap::l::\n') == '<div class="gap gap-l"></div>\n'
+            out = lhtml.run('box::warn:: x\n', {'macros': {'box': {'class': 'box', 'variant': ['warn']}}})
+        assert out == '<div class="box box-warn"></div> x\n'
+
+    def test_macros_key(self, tmp_path):
+        (tmp_path / 'm.yaml').write_text('macros:\n  note: {class: note}\n', encoding='utf-8')
+        assert lhtml.load_macros(str(tmp_path / 'm.yaml')) == {'note': {'class': 'note'}}
+
+    def test_null_removes_macro(self):
+        with pytest.warns(lhtml.LHTMLWarning, match='no matching opening tag'):
+            out = lhtml.run('---\nmacros: {box: null}\n---\nbox:: x ::\n', {'macros': MACROS})
+        assert out.strip() == 'box:: x ::'
+
+    def test_default_must_be_a_variant(self):
+        with pytest.raises(lhtml.LHTMLMacroError):
+            lhtml.run('x\n', {'macros': {'gap': {'class': 'gap', 'variant': ['s'], 'default': 'm'}}})
+
+
+class TestMacrosRound3:
+
+    def test_url_on_container(self):
+        out = lhtml.run('dx::hello\nx\n::\n', {'macros': {'dx': {'class': 'dx', 'url': 'data-x'}}})
+        assert out == '<div class="dx" data-x="hello">\nx\n</div>\n'
+
+    def test_url_on_span_closed_inline(self):
+        out = lhtml.run('t::Tip:: x\n', {'macros': {'t': {'tag': 'span', 'url': 'title'}}})
+        assert out == '<span title="Tip"></span> x\n'
+
+    def test_url_other_than_the_handler_attribute(self):
+        out = lhtml.run('lazy::a.png\n', {'macros': {'lazy': {'tag': 'img', 'class': 'lazy',
+                                                                 'url': 'data-src'}}})
+        assert out == '<img class="lazy" data-src="a.png">\n'
+
+    @pytest.mark.parametrize('tag, expected', [
+        ('img', '<img class="pic" src="a.png" alt="a.png">\n'),
+        ('link', '<a class="pic" href="a.png"></a>\n'),
+    ])
+    def test_empty_url_tag(self, tag, expected):
+        out = lhtml.run('pic::a.png\n', {'macros': {'pic': {'tag': tag, 'class': 'pic', 'empty': True}}})
+        assert out == expected
+
+    def test_link_style_is_an_attribute(self):
+        macros = {'ext': {'tag': 'link', 'class': 'ext', 'style': 'color:red'}}
+        assert lhtml.run('ext::http://a.org[Doc]\n', {'macros': macros}) == \
+            '<a class="ext" style="color:red" href="http://a.org">Doc</a>\n'
+
+    def test_design_keys_are_not_special(self):
+        with pytest.raises(lhtml.LHTMLMacroError, match="'tokens'"):
+            lhtml.run('x\n', {'macros': {'tokens': {'font': {'small': '85%'}}}})
+
+    def test_macros_is_reserved(self):
+        with pytest.raises(lhtml.LHTMLMacroError, match='reserved'):
+            lhtml.run('x\n', {'macros': {'macros': {'macros': {'class': 'm'}}}})
+
+    def test_css_is_not_a_field(self):
+        with pytest.raises(lhtml.LHTMLMacroError, match='css'):
+            lhtml.run('x\n', {'macros': {'box': {'class': 'box', 'css': '.box {}'}}})
+
+    def test_describe_macro(self):
+        assert lhtml.describe_macro('gap', MACROS['gap']) == {
+            'html': '<div class="gap">', 'url': None, 'empty': True, 'variants': ['s', 'm', 'l'],
+            'default': 'm', 'doc': None}
+        info = lhtml.describe_macro('ext', {'tag': 'link', 'class': 'ext'})
+        assert (info['html'], info['url'], info['empty']) == ('<a class="ext">', 'href', True)
+
+    def test_styles_are_separated(self):
+        out = lhtml.run('m::[margin:0] x ::\n', {'macros': {'m': {'style': 'color:red'}}})
+        assert out == '<div style="color:red; margin:0"> x </div>\n'
+
+    @pytest.mark.parametrize('tag', ['nl', 'code', 'verbatim', 'include'])
+    def test_pseudo_tags_are_rejected(self, tag):
+        with pytest.raises(lhtml.LHTMLMacroError, match='not an element'):
+            lhtml.run('x\n', {'macros': {'m': {'tag': tag}}})
+