hyml 1.0.0__py3-none-any.whl

hyml/__init__.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""HyML - XML / (X)HTML generator for Hy.
+
+The markup macros live in Hy modules::
+
+    (require hyml.minimal *)   ; ml
+    (require hyml.macros *)    ; xml, xhtml, xhtml5, html4, html5
+
+From Python, HyML source text can be rendered with :func:`render`.
+"""
+
+import hy  # noqa: F401  (makes the .hy modules importable)
+
+__version__ = "1.0.0"
+
+DIALECTS = ("ml", "xml", "xhtml", "xhtml5", "html4", "html5")
+
+
+def render(source, dialect="ml", variables=None):
+    """Render HyML source text to a markup string.
+
+    >>> render('(p :class "x" "Hello")', "html5")
+    '<p class=x>Hello</p>'
+
+    ``variables`` is a dictionary available to unquoted code (``~name``)
+    in addition to the ``defvar`` / ``deffun`` registry.
+    """
+    if dialect not in DIALECTS:
+        raise ValueError("dialect must be one of: " + ", ".join(DIALECTS))
+    forms = list(hy.read_many(source))
+    if dialect == "ml":
+        from hyml.minimal import parse_mnml
+        return "".join(parse_mnml(form, variables) for form in forms)
+    from hyml.macros import render as render_forms
+    return render_forms(dialect, forms, variables)

hyml/core.hy

@@ -0,0 +1,113 @@
+;; -*- coding: utf-8 -*-
+;;
+;; Copyright (c) 2017-2026 Marko Manninen
+;;
+;; Permission is hereby granted, free of charge, to any person obtaining a copy
+;; of this software and associated documentation files (the "Software"), to deal
+;; in the Software without restriction, including without limitation the rights
+;; to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+;; copies of the Software, and to permit persons to whom the Software is
+;; furnished to do so, subject to the following conditions:
+;;
+;; The above copyright notice and this permission notice shall be included in
+;; all copies or substantial portions of the Software.
+;;
+;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+;; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+;; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+;; AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+;; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+;; OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+;; THE SOFTWARE.
+
+;----------------------------------------------
+; Helpers shared by the MiNiMaL and ML parsers
+;----------------------------------------------
+; ML macros render markup at macro-expansion time, so everything here
+; must exist at compile time too
+(eval-and-compile
+
+  (defclass HyMLError [Exception])
+
+  ; global registry for variables and functions set by defvar and deffun
+  (setv variables-and-functions {})
+
+  (defn keyword? [x] (isinstance x hy.models.Keyword))
+
+  ; tag expressions and spliced lists. strings are not collections here
+  (defn coll? [x] (and (isinstance x #(list tuple)) (not (isinstance x str))))
+
+  ; name of the symbol heading an expression: (unquote x) -> "unquote"
+  (defn head-name [code]
+    (when (and (isinstance code hy.models.Expression)
+               code
+               (isinstance (get code 0) hy.models.Symbol))
+      (str (get code 0))))
+
+  ; plain text of an atom. str of a numeric model gives its repr,
+  ; and keywords should lose their colon
+  (defn ->str [x]
+    (cond (is x None) ""
+          (keyword? x) x.name
+          (isinstance x hy.models.Integer) (str (int x))
+          (isinstance x hy.models.Float) (str (float x))
+          (isinstance x hy.models.Complex) (str (complex x))
+          True (str x)))
+
+  ; Hy reads h1.main.header as (. h1 main header) and .main as (. None main).
+  ; join them back to the shorthand string the (x)html parsers understand
+  (defn dotted-tag [code]
+    (.join "." (gfor part (cut code 1 None)
+                 (if (= (str part) "None") "" (->str part)))))
+
+  ; fresh namespace for evaluating unquoted code. the registry comes first
+  ; and later dictionaries override earlier ones. keys are mangled so that
+  ; {"first-name" ...} is found by ~first-name. hy must be a global, or
+  ; functions defined in the namespace can't run quasiquoted code later
+  (defn namespace [#* dicts]
+    (setv ns (dict :hy hy #** variables-and-functions))
+    (for [d dicts]
+      (when d
+        (for [[k v] (.items d)]
+          (setv (get ns (hy.mangle (->str k))) v))))
+    ns)
+
+  ; evaluate code with macros looked up from the given module
+  (defn eval-in [code module #* dicts]
+    (hy.eval code (namespace #* dicts) :module module))
+
+  ; tag name from the head of an expression. symbols and strings are names
+  ; as such. ~(code) is evaluated, 'tag and `tag are unquoted
+  (defn catch-tag [code evaluate]
+    (setv head (head-name code))
+    (cond (isinstance code hy.models.Symbol) (str code)
+          (= head "unquote") (->str (evaluate (get code 1)))
+          (in head #("quote" "quasiquote")) (->str (hy.eval code))
+          (= head ".") (dotted-tag code)
+          True (->str code)))
+
+  ; result of unquoted code: keywords and expressions stay as code to be
+  ; parsed further, everything else becomes text
+  (defn unquoted [value]
+    (if (or (keyword? value) (isinstance value hy.models.Expression))
+        value
+        (->str value)))
+
+  ; evaluate ~ and ~@ items of a tag body. spliced lists are flattened in
+  ; place, recursively, because include returns a splice itself
+  (defn expand [items evaluate]
+    (setv result [])
+    (for [item items]
+      (setv head (head-name item))
+      (cond (= head "unquote-splice")
+            (.extend result (expand (evaluate (get item 1)) evaluate))
+            (= head "unquote")
+            (.append result (unquoted (evaluate (get item 1))))
+            True
+            (.append result item)))
+    result)
+
+  ; quote an attribute value. & and < are left alone so that already
+  ; escaped values and template placeholders keep working
+  (defn escape-attribute [value]
+    (.replace (str value) "\"" "&quot;")))

hyml/ext.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+# ---------------------------------------------------------
+# Copyright (c) Marko Manninen <elonmedia@gmail.com>, 2017-2026
+# ---------------------------------------------------------
+#
+# Babel message extractor for Hy and HyML files.
+#
+# The package registers it as an entry point:
+#
+#   [project.entry-points."babel.extractors"]
+#   hyml = "hyml.ext:babel_extract"
+#
+# and then in babel.cfg:
+#
+#   [hyml: **.hyml]
+#   [hyml: **.hy]
+#
+# -----------------------------------------------------------------------
+# LOCALIZATION ROUTINE
+# -----------------------------------------------------------------------
+# 1. extract messages:
+# pybabel extract -F babel.cfg -o messages.pot .
+# 2. initialize language file:
+# pybabel init -i messages.pot -d translations -l en
+# 3. make changes to the language file (manually or via third party app)
+# 4. update translation messages:
+# pybabel update -i messages.pot -d translations
+# 5. compile translations
+# pybabel compile -d translations
+# -----------------------------------------------------------------------
+
+import hy
+from hy.models import Expression, String, Symbol
+from hy.reader import HyReader
+
+# accepted gettext / babel keywords
+KEYWORDS = ("_", "gettext", "ngettext", "N_", "lgettext", "lngettext", "lazy_gettext")
+
+
+def _reader():
+    """Hy reader that knows the HyML reader macros.
+
+    #i"message" is the shorthand for (_ "message") from hyml.minimal, and
+    #㎖ only renders markup, so its form is read as such.
+    """
+    reader = HyReader()
+    reader.reader_macros["i"] = lambda r, key: Expression([Symbol("_"), r.parse_one_form()])
+    reader.reader_macros["㎖"] = lambda r, key: r.parse_one_form()
+    return reader
+
+
+def _messages(model, keywords):
+    """Yield (lineno, funcname, messages, comments) for gettext calls in model."""
+    if (isinstance(model, Expression) and model and isinstance(model[0], Symbol)
+            and str(model[0]) in keywords):
+        args = model[1:]
+        strings = [arg for arg in args if isinstance(arg, String)]
+        if strings:
+            messages = tuple(str(arg) if isinstance(arg, String) else None for arg in args)
+            lineno = getattr(model, "start_line", None) or strings[0].start_line
+            # lazy_gettext is flask-babel's lazy form of gettext
+            funcname = "gettext" if str(model[0]) == "lazy_gettext" else str(model[0])
+            yield lineno, funcname, messages[0] if len(messages) == 1 else messages, []
+    if isinstance(model, tuple):
+        for child in model:
+            yield from _messages(child, keywords)
+
+
+def extract_from_source(text, keywords=KEYWORDS, filename="<string>"):
+    """Return the list of babel message tuples found in Hy source text."""
+    keywords = set(keywords)
+    return [message
+            for form in hy.read_many(text, filename=filename, reader=_reader())
+            for message in _messages(form, keywords)]
+
+
+def babel_extract(fileobj, keywords=None, comment_tags=None, options=None):
+    """Babel extraction method for Hy and HyML files."""
+    options = options or {}
+    text = fileobj.read()
+    if isinstance(text, bytes):
+        text = text.decode(options.get("encoding", "utf-8"))
+    return iter(extract_from_source(text, set(KEYWORDS) | set(keywords or ()),
+                                    getattr(fileobj, "name", "<string>")))

hyml/globals.hy

@@ -0,0 +1,30 @@
+;; -*- coding: utf-8 -*-
+;;
+;; Copyright (c) 2017-2026 Marko Manninen
+;;
+;; Permission is hereby granted, free of charge, to any person obtaining a copy
+;; of this software and associated documentation files (the "Software"), to deal
+;; in the Software without restriction, including without limitation the rights
+;; to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+;; copies of the Software, and to permit persons to whom the Software is
+;; furnished to do so, subject to the following conditions:
+;;
+;; The above copyright notice and this permission notice shall be included in
+;; all copies or substantial portions of the Software.
+;;
+;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+;; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+;; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+;; AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+;; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+;; OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+;; THE SOFTWARE.
+
+;------------------------------------------------------------------
+; Backwards compatibility: ML macros (hyml.macros) used to keep
+; their own registry here. Both parsers now share hyml.variables
+;------------------------------------------------------------------
+(require hyml.variables [defvar deffun])
+(import hyml.core [HyMLError variables-and-functions])
+
+(setv variables variables-and-functions)

hyml/helpers.hy

@@ -0,0 +1,95 @@
+;; -*- coding: utf-8 -*-
+;;
+;; Copyright (c) 2017-2026 Marko Manninen
+;;
+;; Permission is hereby granted, free of charge, to any person obtaining a copy
+;; of this software and associated documentation files (the "Software"), to deal
+;; in the Software without restriction, including without limitation the rights
+;; to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+;; copies of the Software, and to permit persons to whom the Software is
+;; furnished to do so, subject to the following conditions:
+;;
+;; The above copyright notice and this permission notice shall be included in
+;; all copies or substantial portions of the Software.
+;;
+;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+;; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+;; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+;; AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+;; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+;; OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+;; THE SOFTWARE.
+
+(import xml.dom.minidom)
+(import hyml.core [HyMLError])
+
+;----------------------------------------
+; print multiple statements on new lines
+;----------------------------------------
+
+(defmacro println [#* args]
+  `(do ~@(gfor arg args `(print ~arg))))
+
+;----------------------------------------------
+; render html for the Jupyter Notebook document
+; this is not mandatory for HyML other macros
+; this is just for the html render in NB
+;----------------------------------------------
+; IPython is imported only when the expanded code runs, and the ML
+; macros are called through hy.R so they need not be required by the user
+
+(defmacro ml> [#* code]
+  `(hy.I.IPython/display.HTML (hy.R.hyml/minimal.ml ~@code)))
+
+(defmacro xml> [#* code]
+  `(hy.I.IPython/display.HTML (hy.R.hyml/macros.xml ~@code)))
+
+(defmacro xhtml> [#* code]
+  `(hy.I.IPython/display.HTML (hy.R.hyml/macros.xhtml ~@code)))
+
+(defmacro xhtml5> [#* code]
+  `(hy.I.IPython/display.HTML (hy.R.hyml/macros.xhtml5 ~@code)))
+
+(defmacro html4> [#* code]
+  `(hy.I.IPython/display.HTML (hy.R.hyml/macros.html4 ~@code)))
+
+(defmacro html5> [#* code]
+  `(hy.I.IPython/display.HTML (hy.R.hyml/macros.html5 ~@code)))
+
+;----------------------------------------------------
+; Indent xml code
+; Works only with well defined root node xml content!
+;----------------------------------------------------
+
+(defn indent [xmldoc]
+  (try
+    (setv pretty (.toprettyxml (xml.dom.minidom.parseString xmldoc)))
+    (except [e Exception]
+      (raise (HyMLError (+ "indent needs well-formed xml with a single root node: "
+                           (str e))))))
+  ; minidom always adds its own xml declaration. drop it and restore
+  ; the original one if the document had it
+  (setv pretty (.join "\n" (cut (.splitlines pretty) 1 None)))
+  (if (.startswith xmldoc "<?xml")
+      (+ (cut xmldoc 0 (+ (.index xmldoc "?>") 2)) "\n" pretty)
+      pretty))
+
+;-----------------------------------------------------------------------
+; List comprehension
+; Use ordinary list and expression (list-comp expr args) arguments order
+; vice versa: (list-comp* args expr). This serves as a kind of for each
+; loop where list items and variables are introdused first, and then
+; expression to handle each of items.
+;-----------------------------------------------------------------------
+
+; Hy 0.13 style list-comp kept for existing templates:
+; (list-comp expr [x xs y ys] condition) -> (lfor x xs y ys :if condition expr)
+(defmacro list-comp [expr bindings [condition None]]
+  (if (is condition None)
+      `(lfor ~@bindings ~expr)
+      `(lfor ~@bindings :if ~condition ~expr)))
+
+(defmacro list-comp* [bindings expr [condition None]]
+  (if (is condition None)
+      `(lfor ~@bindings ~expr)
+      `(lfor ~@bindings :if ~condition ~expr)))

hyml/ipython.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+"""IPython / Jupyter extension for running Hy code in notebook cells.
+
+There is no maintained Hy kernel, so HyML notebooks use the standard
+Python kernel with this extension::
+
+    %load_ext hyml.ipython
+
+    %%hy
+    (require hyml.minimal *)
+    (ml (p :class "x" "Hello"))
+
+The value of the last form of a cell is the cell's output. Macros and
+reader macros required in one cell are available in later cells.
+"""
+
+import hy
+from hy.reader import HyReader
+from IPython.core.magic import Magics, cell_magic, line_magic, magics_class
+
+
+@magics_class
+class HyMagics(Magics):
+
+    def __init__(self, shell):
+        super().__init__(shell)
+        # one reader for the whole session, so that reader macros stay enabled
+        self.reader = HyReader()
+
+    def run(self, source):
+        module = self.shell.user_module
+        result = None
+        # forms are read one at a time, so a reader macro required by one
+        # form can be used by the next one in the same cell
+        for form in hy.read_many(source, filename="<hy-cell>", reader=self.reader):
+            result = hy.eval(form, self.shell.user_ns, module=module)
+            self.reader.reader_macros.update(vars(module).get("_hy_reader_macros", {}))
+        return result
+
+    @cell_magic
+    def hy(self, line, cell):
+        """Run the cell as Hy code."""
+        return self.run(cell)
+
+    @line_magic("hy")
+    def hy_line(self, line):
+        """Run the rest of the line as Hy code."""
+        return self.run(line)
+
+
+def load_ipython_extension(ipython):
+    ipython.register_magics(HyMagics)