Add logging.lua, documentation, examples etc.

Author: wlupton

Makefile

@@ -0,0 +1,2 @@
+test:
+	$(MAKE) --directory=examples test

README.md

@@ -0,0 +1,171 @@
+# Pandoc lua logging
+
+This library provides pandoc-aware functions for dumping and logging lua objects. It can be used standalone but is primarily intended for using within pandoc lua filters.
+
+# Getting started
+
+Put `logging.lua` somewhere where pandoc can access it, e.g., in the same directory as your lua filters. Then try this `simple.lua` filter:
+
+```lua
+local logging = require 'logging'
+
+function Pandoc(pandoc)
+    logging.temp('pandoc', pandoc)
+end
+```
+
+...with this `simple.md` input:
+
+```markdown
+text
+```
+
+...to get this output on `stderr`:
+
+```text
+(#) pandoc Pandoc {
+  blocks: Blocks {
+    [1] Para {
+      content: Inlines {
+        [1] Str text: "text"
+      }
+    }
+  }
+  meta: Meta {}
+}
+```
+
+The `logging.temp()` function is intended for temporary debug output (hence its name) and always generates output. You can use `logging.error()`, `logging.warning()`, `logging.info()` etc. to generate output that's conditional on the log level.
+
+The initial log level is derived from the pandoc `--quiet`, `--verbose` and `--trace` command-line options. By default (i.e., if none of these options are specified) the log level is `0` and only errors and warnings will be output.
+
+With this `para.lua` filter:
+
+```lua
+local logging = require 'logging'
+
+function Para(para)
+    logging.info('para', para)
+end
+```
+
+...by default there's no output:
+
+```text
+% pandoc simple.md -L para.lua >/dev/null
+```
+
+...but `--verbose` sets the log level to `1` (`info`):
+
+```text
+% pandoc simple.md -L para.lua >/dev/null --verbose
+[INFO] Running filter para.lua
+(I) para Para {, content: Inlines {[1] Str text: "text"}}
+[INFO] Completed filter para.lua in 8 ms
+```
+
+All lua objects can be passed to `logging.info()` etc., and they will be output in a form that should be useful for lua filter development and debugging. The output is intended to be a faithful representation of the [pandoc lua types](https://pandoc.org/lua-filters.html#module-pandoc) and should make it easy to "dig down". For example, you can see that:
+
+* `para` is a [Para](https://pandoc.org/lua-filters.html#type-para) instance
+* `para.content` is an [Inlines](https://pandoc.org/lua-filters.html#type-inlines) instance
+* `para.content[1]` is a [Str](https://pandoc.org/lua-filters.html#type-str) instance
+* `para.content[1].text` is a string
+
+...and you could reference all of these directly in the filter. For example, with this `para2.lua` filter:
+
+```lua
+local logging = require 'logging'
+
+function Para(para)
+    logging.info('para', para)
+    logging.info('para.content', para.content)
+    logging.info('para.content[1]', para.content[1])
+    logging.info('para.content[1].text', para.content[1].text)
+end
+```
+
+...you get this:
+
+```text
+% pandoc simple.md -L para2.lua >/dev/null --verbose
+[INFO] Running filter para2.lua
+(I) para Para {, content: Inlines {[1] Str text: "text"}}
+(I) para.content Inlines {[1] Str text: "text"}
+(I) para.content[1] Str text: "text"
+(I) para.content[1].text text
+[INFO] Completed filter para2.lua in 8 ms
+```
+
+# Module contents
+
+## logging.type(value)
+
+Returns whatever [`pandoc.utils.type()`](https://pandoc.org/lua-filters.html#pandoc.utils.type) returns, modified as follows:
+
+* Spaces are replaced with periods, e.g., `pandoc Row` becomes `pandoc.Row`
+* `Inline` and `Block` are replaced with the corresponding `tag` value, e.g. `Emph` or `Table`
+
+## logging.dump(value [, maxlen])
+
+Returns a pandoc-aware string representation of `value`, which can be an arbitrary lua object.
+
+The returned string is a single line if not longer than `maxlen` (default `70`), and is otherwise multiple lines (with two character indentation). The string is not terminated with a newline.
+
+Map keys are sorted alphabetically in order to ensure that output is repeatable.
+
+
+
+See the *Getting started* section for examples, and note that 
+
+## logging.output(...)
+
+Pass each argument to `logging.dump()` and output the results to `stderr`, separated by single spaces and terminated (if necessary) with a newline.
+
+Note: Actually (as a slight optimization) only `table` and `userdata` arguments are passed to `logging.dump()`. Other arguments are passed to the built-in `tostring()` function.
+
+## logging.loglevel
+
+Integer log level, which controls which of `logging.error()`, `logging.warning()`, `logging.info()` will generate output when called.
+
+* `-2` : (or less) suppress all logging (apart from `logging.temp()`)
+* `-1` : output only error messages
+* `0` : output error and warning messages
+* `1` : output error, warning and info messages
+* `2` : output error, warning, info and debug messages
+* `3` : (or more) output error, warning, info, debug and trace messages
+
+The initial log level is `0`, unless the following pandoc command-line options are specified:
+
+* `--trace` : `3` if `--verbose` is also specified; otherwise `2`
+* `--verbose` : `1`
+* `--quiet` : `-1`
+
+## logging.setloglevel(loglevel)
+
+Sets the log level and returns the previous level.
+
+Calling this function is preferable to setting `logging.loglevel` directly.
+
+## logging.error(...)
+
+If the log level is >= `-1`, calls `logging.output()` with `(E)` and the supplied arguments.
+
+## logging.warning(...)
+
+If the log level is >= `0`, calls `logging.output()` with `(W)` and the supplied arguments.
+
+## logging.info(...)
+
+If the log level is >= `1`, calls `logging.output()` with `(I)` and the supplied arguments.
+
+## logging.debug(...)
+
+If the log level is >= `2`, calls `logging.output()` with `(D)` and the supplied arguments.
+
+## logging.trace(...)
+
+If the log level is >= `3`, calls `logging.output()` with `(T)` and the supplied arguments.
+
+## logging.temp(...)
+
+Unconditionally calls `logging.output()` with `(#)` and the supplied arguments.

examples/Makefile

@@ -0,0 +1,26 @@
+DIFF ?= diff --strip-trailing-cr --unified
+LUA ?= lua
+PANDOC ?= pandoc
+
+STANDALONE = dumpex.lua levels.lua
+FILTER = para.lua para2.lua simple.lua table.lua
+
+# make COMPARE= to run tools without redirection or comparison
+# make SNAPSHOT=true to create .expected files
+ifneq "$(SNAPSHOT)" ""
+  COMPARE = 2>$*.expected >/dev/null
+else
+  COMPARE = 2>&1 >/dev/null | $(DIFF) $*.expected -
+endif
+
+test: test-standalone test-filter
+
+test-standalone: $(STANDALONE:%=test-standalone-%)
+
+test-filter: $(FILTER:%=test-filter-%)
+
+test-standalone-%: %
+	$(LUA) $* $(COMPARE)
+
+test-filter-%: %
+	$(PANDOC) $(wildcard *.md) -L $* $(COMPARE)

examples/README.md

@@ -0,0 +1,7 @@
+# Pandoc lua logging examples
+
+This directory contains example lua files (standalone and pandoc filters) and some sample markdown files.
+
+These files were used when generating the examples in the top-level README file.
+
+There's also a `Makefile` that runs lua and pandoc (as appropriate) and compares the output with the expected output.

examples/basic.md

@@ -0,0 +1,14 @@
+---
+foo: '*emph*'
+goo: '[underline]{.underline}'
+---
+
+# Header {#header .new-page a=b}
+
+Paragraph with *emphasized* and **bold** text.
+
+```
+Code
+```
+
+* and a list.

examples/dumpex.lua

@@ -0,0 +1,17 @@
+local logging = require 'logging'
+
+local function output(value)
+    io.stderr:write(value .. '\n')
+end
+
+output(logging.dump(nil))
+output(logging.dump(1))
+output(logging.dump(false))
+output(logging.dump('string'))
+output(logging.dump({}))
+output(logging.dump({1, 2, 3}))
+output(logging.dump({a=1, b=2, c=3}))
+output(logging.dump({a=1, b=2, c=3, 4, 5}))
+output(logging.dump({a=1, b=2, c=3, 4, 5, 6, 7, 8, 9, 10}))
+output(logging.dump({a=1, b=2, c=3, 4, 5, 6, 7, 8, 9, 10, 11}))
+output(logging.dump({1, 2, {3, 4, {a=1, b=2, c=3, d=4, e=5, f=6}}}))

examples/dumpex.lua.expected

@@ -0,0 +1,38 @@
+nil
+1
+false
+"string"
+{}
+{[1] 1, [2] 2, [3] 3}
+{a: 1, b: 2, c: 3}
+{[1] 4, [2] 5, a: 1, b: 2, c: 3}
+{[1] 4, [2] 5, [3] 6, [4] 7, [5] 8, [6] 9, [7] 10, a: 1, b: 2, c: 3}
+{
+  [1] 4
+  [2] 5
+  [3] 6
+  [4] 7
+  [5] 8
+  [6] 9
+  [7] 10
+  [8] 11
+  a: 1
+  b: 2
+  c: 3
+}
+{
+  [1] 1
+  [2] 2
+  [3] {
+    [1] 3
+    [2] 4
+    [3] {
+      a: 1
+      b: 2
+      c: 3
+      d: 4
+      e: 5
+      f: 6
+    }
+  }
+}

examples/levels.lua

@@ -0,0 +1,19 @@
+local logging = require 'logging'
+
+if #arg > 0 then
+    logging.setloglevel(tonumber(arg[1]) or 0)
+end
+
+logging.temp('loglevel is', logging.loglevel, '(this is always output)')
+logging.error('this is output if loglevel >= -1')
+logging.warning('this is output if loglevel >= 0')
+logging.info('this is output if loglevel >= 1')
+logging.debug('this is output if loglevel >= 2')
+logging.debug2('this is output if loglevel >= 3')
+
+logging.temp('args', 'are', 'automatically', 'separated', 'with',
+             'spaces and a newline is added if necessary')
+logging.temp('args can be of any type, e.g.', {maps='like', this='one'},
+             'or', {'lists', 'like', 'this', 'one'})
+logging.temp('if an arg is too long it will be output on multiple lines',
+             {'aardvark', 'bison', 'camel', 'dingo', 'echnidna'}, 'like this')

examples/levels.lua.expected

@@ -0,0 +1,12 @@
+(#) loglevel is 0 (this is always output)
+(E) this is output if loglevel >= -1
+(W) this is output if loglevel >= 0
+(#) args are automatically separated with spaces and a newline is added if necessary
+(#) args can be of any type, e.g. {maps: "like", this: "one"} or {[1] "lists", [2] "like", [3] "this", [4] "one"}
+(#) if an arg is too long it will be output on multiple lines {
+  [1] "aardvark"
+  [2] "bison"
+  [3] "camel"
+  [4] "dingo"
+  [5] "echnidna"
+} like this

examples/logging.lua

@@ -0,0 +1 @@
+../logging.lua