Add spairs() to the logging namespace, and update docs accordingly

Also fix some bugs:

1. Improve logic to ignore functions in pandoc objects (they were
   confusing attribute-counting logic).

2. Fix bug that affected reporting in (rare) cases where objects
   have both numeric and non-numeric keys.

3. Avoid passing values to string.format(). This was previously
   done with the %q formatting string, but this didn't work with
   multi-byte characters.

Author: wlupton

README.md

@@ -27,7 +27,7 @@ text
   blocks: Blocks {
     [1] Para {
       content: Inlines {
-        [1] Str text: "text"
+        [1] Str "text"
       }
     }
   }
@@ -60,7 +60,7 @@ end
 ```text
 % pandoc simple.md -L para.lua >/dev/null --verbose
 [INFO] Running filter para.lua
-(I) para Para {, content: Inlines {[1] Str text: "text"}}
+(I) para Para {content: Inlines {[1] Str "text"}}
 [INFO] Completed filter para.lua in 8 ms
 ```
 
@@ -89,13 +89,15 @@ end
 ```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 Para {content: Inlines {[1] Str "text"}}
+(I) para.content Inlines {[1] Str "text"}
+(I) para.content[1] Str "text"
 (I) para.content[1].text text
 [INFO] Completed filter para2.lua in 8 ms
 ```
 
+Why is the last `text` not quoted?
+
 # Module contents
 
 ## logging.type(value)
@@ -105,6 +107,12 @@ Returns whatever [`pandoc.utils.type()`](https://pandoc.org/lua-filters.html#pan
 * 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.spairs(list [, comp])
+
+Like `pairs()` but with sorted keys. Keys are converted to strings and sorted
+using `table.sort(keys, comp)` so by default they're visited in alphabetical
+order.
+
 ## logging.dump(value [, maxlen])
 
 Returns a pandoc-aware string representation of `value`, which can be an arbitrary lua object.
@@ -113,15 +121,16 @@ The returned string is a single line if not longer than `maxlen` (default `70`),
 
 Map keys are sorted alphabetically in order to ensure that output is repeatable.
 
-
-
-See the *Getting started* section for examples, and note that 
+See the *Getting started* section for examples.
 
 ## 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.
+Note: Only `table` and `userdata` arguments are passed to
+`logging.dump()`. Other arguments are passed to the built-in `tostring()`
+function. This is partly an optimization and partly to prevent string arguments
+from being quoted.
 
 ## logging.loglevel
 

examples/Makefile

@@ -2,15 +2,21 @@ DIFF ?= diff --strip-trailing-cr --unified
 LUA ?= lua
 PANDOC ?= pandoc
 
+PANDOCFLAGS +=
+
 STANDALONE = dumpex.lua levels.lua
 FILTER = para.lua para2.lua simple.lua table.lua
 
+test-filter-para.lua test-filter-para2.lua: \
+	PANDOCFLAGS += --verbose
+
 # make COMPARE= to run tools without redirection or comparison
 # make SNAPSHOT=true to create .expected files
+FIX = sed -e 's/in [0-9]* ms/in NN ms/'
 ifneq "$(SNAPSHOT)" ""
-  COMPARE = 2>$*.expected >/dev/null
+  COMPARE = 2>&1 >/dev/null | $(FIX) >$*.expected
 else
-  COMPARE = 2>&1 >/dev/null | $(DIFF) $*.expected -
+  COMPARE = 2>&1 >/dev/null | $(FIX) | $(DIFF) $*.expected -
 endif
 
 test: test-standalone test-filter
@@ -23,4 +29,4 @@ test-standalone-%: %
 	$(LUA) $* $(COMPARE)
 
 test-filter-%: %
-	$(PANDOC) $(wildcard *.md) -L $* $(COMPARE)
+	$(PANDOC) $(PANDOCFLAGS) $(wildcard *.md) -L $* $(COMPARE)

examples/dumpex.lua

@@ -8,6 +8,7 @@ output(logging.dump(nil))
 output(logging.dump(1))
 output(logging.dump(false))
 output(logging.dump('string'))
+output(logging.dump('Here’s a non-ASCII character.'))
 output(logging.dump({}))
 output(logging.dump({1, 2, 3}))
 output(logging.dump({a=1, b=2, c=3}))

examples/dumpex.lua.expected

@@ -2,6 +2,7 @@ nil
 1
 false
 "string"
+"Here’s a non-ASCII character."
 {}
 {[1] 1, [2] 2, [3] 3}
 {a: 1, b: 2, c: 3}

examples/para.lua.expected

@@ -0,0 +1,137 @@
+[INFO] Running filter para.lua
+(I) para Para {
+  content: Inlines {
+    [1] Str "This"
+    [2] Space
+    [3] Str "directory"
+    [4] Space
+    [5] Str "contains"
+    [6] Space
+    [7] Str "example"
+    [8] Space
+    [9] Str "lua"
+    [10] Space
+    [11] Str "files"
+    [12] Space
+    [13] Str "(standalone"
+    [14] Space
+    [15] Str "and"
+    [16] Space
+    [17] Str "pandoc"
+    [18] Space
+    [19] Str "filters)"
+    [20] Space
+    [21] Str "and"
+    [22] Space
+    [23] Str "some"
+    [24] Space
+    [25] Str "sample"
+    [26] Space
+    [27] Str "markdown"
+    [28] Space
+    [29] Str "files."
+  }
+}
+(I) para Para {
+  content: Inlines {
+    [1] Str "These"
+    [2] Space
+    [3] Str "files"
+    [4] Space
+    [5] Str "were"
+    [6] Space
+    [7] Str "used"
+    [8] Space
+    [9] Str "when"
+    [10] Space
+    [11] Str "generating"
+    [12] Space
+    [13] Str "the"
+    [14] Space
+    [15] Str "examples"
+    [16] Space
+    [17] Str "in"
+    [18] Space
+    [19] Str "the"
+    [20] Space
+    [21] Str "top-level"
+    [22] Space
+    [23] Str "README"
+    [24] Space
+    [25] Str "file."
+  }
+}
+(I) para Para {
+  content: Inlines {
+    [1] Str "There’s"
+    [2] Space
+    [3] Str "also"
+    [4] Space
+    [5] Str "a"
+    [6] Space
+    [7] Code {
+      attr: Attr {
+        attributes: AttributeList {}
+        classes: List {}
+        identifier: ""
+      }
+      text: "Makefile"
+    }
+    [8] Space
+    [9] Str "that"
+    [10] Space
+    [11] Str "runs"
+    [12] Space
+    [13] Str "lua"
+    [14] Space
+    [15] Str "and"
+    [16] Space
+    [17] Str "pandoc"
+    [18] Space
+    [19] Str "(as"
+    [20] Space
+    [21] Str "appropriate)"
+    [22] Space
+    [23] Str "and"
+    [24] Space
+    [25] Str "compares"
+    [26] Space
+    [27] Str "the"
+    [28] Space
+    [29] Str "output"
+    [30] Space
+    [31] Str "with"
+    [32] Space
+    [33] Str "the"
+    [34] Space
+    [35] Str "expected"
+    [36] Space
+    [37] Str "output."
+  }
+}
+(I) para Para {
+  content: Inlines {
+    [1] Str "Paragraph"
+    [2] Space
+    [3] Str "with"
+    [4] Space
+    [5] Emph {
+      content: Inlines {
+        [1] Str "emphasized"
+      }
+    }
+    [6] Space
+    [7] Str "and"
+    [8] Space
+    [9] Strong {
+      content: Inlines {
+        [1] Str "bold"
+      }
+    }
+    [10] Space
+    [11] Str "text."
+  }
+}
+(I) para Para {content: Inlines {[1] Str "text"}}
+(I) para Para {content: Inlines {[1] Str "smart-quote-’"}}
+[INFO] Completed filter para.lua in NN ms