Commits

Oben Sonne committed 5ef0d36

Use a more compact name (`hx`) for the HTML escaping utility function.

However, the old one (`htmlspecialchars`) is still available.

Comments (0)

Files changed (2)

 
 Currently, there is only one builtin macro available.
 
-`htmlspecialchars(s)`
+`hx(s)`
 
 > Replace the characters that are special within HTML (`&`, `<`, `>` and `"`)
 > with their equivalent character entity (e.g., `&amp;`). This should be
 > called whenever an arbitrary string is inserted into HTML (i.e. use
-> `{{ htmlspecialchars(variable) }}` instead of `{{ variable }}`).
+> `{{ hx(variable) }}` instead of `{{ variable }}`). You do not need this
+> within a markdown context.
 >
 > Note that `"` is not special in most HTML, only within attributes.
 > However, since escaping it does not hurt within normal HTML, it is
 "page.html": """<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 <head>
-    <meta http-equiv="Content-Type" content="text/html; charset={{ htmlspecialchars(__encoding__) }}" />
-    <title>poole - {{ htmlspecialchars(page["title"]) }}</title>
-    <meta name="description" content="{{ htmlspecialchars(page.get("description", "a poole site")) }}" />
-    <meta name="keywords" content="{{ htmlspecialchars(page.get("keywords", "poole")) }}" />
+    <meta http-equiv="Content-Type" content="text/html; charset={{ __encoding__ }}" />
+    <title>poole - {{ hx(page["title"]) }}</title>
+    <meta name="description" content="{{ hx(page.get("description", "a poole site")) }}" />
+    <meta name="keywords" content="{{ hx(page.get("keywords", "poole")) }}" />
     <style type="text/css">
         body {
             font-family: sans;
     <div id="box">
     <div id="header">
          <h1>a poole site</h1>
-         <h2>{{ htmlspecialchars(page["title"]) }}</h2>
+         <h2>{{ hx(page["title"]) }}</h2>
     </div>
     <div id="menu">
     <!--%
         mpages.sort(key=lambda p: int(p["menu-position"]))
         entry = '<span class="%s"><a href="%s">%s</a></span>'
         for p in mpages:
-            style = p["title"] == page["title"] and "current" or ""
-            print(entry % (style, htmlspecialchars(p["url"]), htmlspecialchars(p["title"])))
+            style = "current" if p["title"] == page["title"] else ""
+            print(entry % (style, p["url"], hx(p["title"])))
     %-->
     </div>
     <div id="content">{{ __content__ }}</div>
 
 MKD_PATT = r'\.(?:md|mkd|mdown|markdown)$'
 
+def hx(s):
+    """
+    Replace the characters that are special within HTML (&, <, > and ")
+    with their equivalent character entity (e.g., &amp;). This should be
+    called whenever an arbitrary string is inserted into HTML (so in most
+    places where you use {{ variable }} in your templates).
+
+    Note that " is not special in most HTML, only within attributes.
+    However, since escaping it does not hurt within normal HTML, it is
+    just escaped unconditionally.
+    """
+    if getattr(s, 'escaped', False):
+        return s
+
+    escape = {
+        "&": "&amp;",
+        '"': "&quot;",
+        ">": "&gt;",
+        "<": "&lt;",
+    }
+    return ''.join(escape.get(c, c) for c in s)
+
 class Page(dict):
     """Abstraction of a source page."""
 
     macros["input"] = dir_in
     macros["output"] = dir_out
 
-    # "builtin" functions for use in macros and templates
-    macros["htmlspecialchars"] = htmlspecialchars
+    # "builtin" items for use in macros and templates
+    macros["hx"] = hx
+    macros["htmlspecialchars"] = hx # legacy name of `htmlx` function
     macros["Page"] = Page
 
     # -------------------------------------------------------------------------
     return opts
 
 # =============================================================================
-# template helper functions
-# =============================================================================
-
-def htmlspecialchars(s):
-    """
-    Replace the characters that are special within HTML (&, <, > and ")
-    with their equivalent character entity (e.g., &amp;). This should be
-    called whenever an arbitrary string is inserted into HTML (so in most
-    places where you use {{ variable }} in your templates).
-
-    Note that " is not special in most HTML, only within attributes.
-    However, since escaping it does not hurt within normal HTML, it is
-    just escaped unconditionally.
-    """
-    escape = {
-        "&": "&amp;",
-        '"': "&quot;",
-        ">": "&gt;",
-        "<": "&lt;",
-    }
-
-    # Look up the translation for every character in s (defaulting to
-    # the character itself if no translation is available).
-    return ''.join([escape.get(c,c) for c in s])
-
-# =============================================================================
 # main
 # =============================================================================