Update documentation and add styles for html_table

Author: Frityet

README.md

@@ -0,0 +1,146 @@
+# LuaXMLGenerator
+
+Library to easily generate XML with a clean Lua DSL.
+
+## Installation
+
+```bash
+luarocks insatll luaxmlgenerator
+```
+
+## Usage
+
+```lua
+local xml_gen = require("xml-generator")
+local xml = xml_gen.xml
+
+local doc = xml.html {charset="utf-8", lang="en"} {
+    xml.head {
+        xml.title "Hello World"
+    },
+    xml.body {
+        xml.h1 "Hello World",
+
+        xml.div {id="numbers"} {
+            function() --run as a coroutine
+                for i = 1, 10 do
+                    coroutine.yield(xml.p(i))
+                end
+            end
+        }
+    }
+}
+
+print(doc)
+```
+
+## Options
+
+### `xml_gen.no_sanitize`
+Table of tags that should not be sanitized. By default, it contains `script` and `style`.
+
+```lua
+local xml_gen = require("xml-generator")
+xml_gen.no_sanitize["mytag"] = true
+
+local doc = xml_gen.xml {
+    xml.mytag [[
+        Thsi will not be sanitized! <><><><><><%%%<>%<>%<>% you can use all of this!
+    ]]
+}
+
+```
+
+### `xml_gen.lua_is_global`
+
+By default, within `xml_gen.xml` there is a special key called `lua` which just allows for `_G` to be accessed. This is useful if you use `xml_gen.declare_generator`, which overloads the `_ENV` (`setfenv` on 5.1), where the `_G` would not be ordinarily accessible.
+
+```lua
+local xml_gen = require("xml-generator")
+
+local gen = xml_gen.declare_generator(function()
+    return html {
+        head {
+            title "Hello World";
+        };
+
+        body {
+            p { "The time of generation is ", lua.os.date() }
+        };
+    }
+end)
+
+print(gen())
+```
+
+## Utilities
+
+### `xml_gen,declare_generator`
+```lua
+---@generic T
+---@param func fun(...: T): XML.Node
+---@return fun(...: T): XML.Node
+function export.declare_generator(func)
+```
+
+Allows you to create a function in which the `_ENV` is overloaded with the `xml` table. This allows you to write XML more concisely (see example above).
+
+### `xml_gen.html_table`
+```lua
+---@generic TKey, TValue
+---@param tbl { [TKey] : TValue },
+---@param order TKey[]?
+---@param classes { table: string?, tr: string?, td: string? }?
+---@return XML.Node
+function export.html_table(tbl, order, classes)
+```
+
+Creates an HTML table based off a lua table. This is unstyled, so you will need to add your own CSS.
+
+```lua
+
+local my_table = {
+    key = "value",
+    sub = {
+        key = "value",
+    }
+}
+
+local tbl = xml_gen.html_table(my_table, { "key", "sub" }, {
+    table = "my-table",
+    tr = "my-table-row",
+    td = "my-table-cell",
+})
+
+print(tbl)
+
+```
+
+### `xml_gen.style`
+```lua
+---@param css { [string | string[]] : { [string | string[]] : (number | string | string[]) } }
+---@return XML.Node
+function export.style(css)
+```
+
+Creates an HTML `style` tag with the given table
+
+```lua
+local xml_gen = require("xml-generator")
+
+local style = xml_gen.style {
+    [{ "body", "html" }] = {
+        margin = 0,
+        padding = 0,
+    },
+
+    body = {
+        background = "#000",
+        color = "#fff",
+    }
+
+    --etc
+}
+
+print(style)
+```

test.lua

@@ -1,6 +1,54 @@
 local xml_gen = require("xml-generator")
 local xml = xml_gen.xml
 
-local test = xml.div {key="value"}
+local doc = xml.html {charset="utf-8", lang="en"} {
+    xml.head {
+        xml.title "Hello World"
+    },
+    xml.body {
+        xml.h1 "Hello World",
 
-print(xml_gen.node_to_string(test))
+        xml.div {id="numbers"} {
+            function() --run as a coroutine
+                for i = 1, 10 do
+                    coroutine.yield(xml.p(i))
+                end
+            end
+        }
+    }
+}
+
+print(doc)
+
+local my_table = {
+    key = "value",
+    sub = {
+        key = "value",
+    }
+}
+
+local tbl = xml_gen.html_table(my_table, { "key", "sub" }, {
+    table = "my-table",
+    tr = "my-table-row",
+    td = "my-table-cell",
+})
+
+print(tbl)
+
+local xml_gen = require("xml-generator")
+
+local style = xml_gen.style {
+    [{ "body", "html" }] = {
+        margin = 0,
+        padding = 0,
+    },
+
+    body = {
+        background = "#000",
+        color = "#fff",
+    }
+
+    --etc
+}
+
+print(style)

xml-generator.lua

@@ -168,10 +168,12 @@ function export.declare_generator(func) return setfenv(func, export.xml) end
 ---@generic TKey, TValue
 ---@param tbl { [TKey] : TValue },
 ---@param order TKey[]?
+---@param classes { table: string?, tr: string?, td: string? }?
 ---@return XML.Node
-function export.html_table(tbl, order)
+function export.html_table(tbl, order, classes)
+    local classes = classes or {}
     local xml = export.xml
-    return xml.table {
+    return xml.table {class=classes.table} {
         function ()
             local function getval(v)
                 local tname = typename(v)
@@ -188,18 +190,18 @@ function export.html_table(tbl, order)
                 for i, v in ipairs(order) do
                     local val = tbl[v]
                     coroutine.yield (
-                        xml.tr {
-                            xml.td(tostring(v)),
-                            xml.td(getval(val))
+                        xml.tr {class=classes.table} {
+                            xml.td {class=classes.td} (tostring(v)),
+                            xml.td {class=classes.td} (getval(val))
                         }
                     )
                 end
             else
                 for i, v in ipairs(tbl) do
                     coroutine.yield (
-                        xml.tr {
-                            xml.td(tostring(i)),
-                            xml.td(getval(v)),
+                        xml.tr {class=classes.tr} {
+                            xml.td {class=classes.td} (tostring(i)),
+                            xml.td {class=classes.td} (getval(v)),
                         }
                     )
 
@@ -208,9 +210,9 @@ function export.html_table(tbl, order)
 
                 for k, v in pairs(tbl) do
                     coroutine.yield (
-                        xml.tr {
-                            xml.td(tostring(k)),
-                            xml.td(getval(v)),
+                        xml.tr {class=classes.tr} {
+                            xml.td {class=classes.td} (tostring(k)),
+                            xml.td {class=classes.td} (getval(v)),
                         }
                     )
                 end
@@ -220,8 +222,7 @@ function export.html_table(tbl, order)
 end
 
 ---Creates a style tag with the given lua table
----@alias OptionalStringCollection string | string[]
----@param css { [OptionalStringCollection] : { [OptionalStringCollection] : (OptionalStringCollection) } }
+---@param css { [string | string[]] : { [string | string[]] : (number | string | string[]) } }
 ---@return XML.Node
 function export.style(css)
     local css_str = ""