diff options
| -rw-r--r-- | README.md | 58 |
1 files changed, 51 insertions, 7 deletions
@@ -3,15 +3,59 @@ marigold-cgi A Lua CGI scripting toolkit. -usage ------ -### retrieving meta-variables +functions +--------- -`marigold.get_metavars()` - returns a table. The keys are the (lowercase) names of the meta-variables described in section 4.1 of RFC 3875 and are associated with their (string) values. +#### `marigold.get_metavars()` #### -### generating html +Returns a table containing all of the meta-variables described in section 4.1 +of [RFC 3875]. The keys are the lowercase metavariable names (e.g. ` +request_method`) and the values are strings containing their values. -`marigold.h(tag, attributes_and_children)` - returns a `marigold.html` table. `tag` is a string; `attributes_and_children` is a table containing, uh, tag attributes and children. Attributes are string keys with string values and represent the tag's attributes (e.g. `{id='tag1', class='large blinking'}` converts to `<[tag] id="tag1" class="large blinking"></[tag]>`). Children are the array elements of the table and should contain `marigold.html` tables as values. -The only thing that is special about `marigold.html` tables is that they can be passed to `marigold.render_html(tbl, indent_level=0)` in order to produce actual string output. +#### `marigold.h(tag_type [string], content [string, opt], tbl [table, opt])` #### + +Builds a table to be used with `marigold.html`. + + * `tag_type`: the type of the tag, e.g. `<p>`, `<div>`, etc + * `content`: any text content within the tag. may be omitted and *still include tbl* + * `tbl`: table containing both tag attributes and children. Values with + string keys are considered attributes, while values with numeric keys are + added as children in the same order as the keys. + +Returns a table with stringly-typed `tag` and `content` keys, and table-typed ` +attributes` and `children` keys. There is no reason you can't generate a table +like this by hand and pass it to `marigold.html`; this function is provided for convenience. + + +#### `marigold.html(tbl [table], indent_level [number, opt])` #### + +Reads a `marigold.h`-formatted table and returns a pretty-printed HTML fragment representing it. + + * `tbl`: a table as described above + * `indent_level`: 0 by default, but if you're rendering a document piecemeal you might set this + +Returns a string with nicely formatted HTML. To render a whole document, pass +it a `marigold.h('html', ...)` result. + + +#### `marigold.decode_percent(str [string])` #### + +Decodes percent-encoded strings. + + * `str`: a string with percent-encoded values embedded + +Returns the clean string, with the percent-encoded values decoded. Note that it will NOT do things like replace '+' with ' ' for `application/x-www-form-urlencoded` data. + + +#### `marigold.decode_query(str [string])` #### + +Decodes `application/x-www-form-urlencoded` data into a table. + + * `str`: the string containing the data to decode + +Returns a table containing all the key-value pairs that could be extracted from the string, with all percent-encoding removed and appropriate '+' replaced with ' '. + + +[RFC 3875]: https://www.rfc-editor.org/rfc/rfc3875.html |