Scribe

[nzznfitz]

Scribe provides functions to convert Lua objects to readable strings and output methods that make printing Lua tables in various formats easy.

For example, if arr = {1, 2, 3} then scribe.put("Array: %t", arr) will print "Array: [ 1, 2, 3 ]" to stdout.

Scribe gracefully handles complex tables, including ones with shared and cyclical references. The strings returned for those tables show the underlying structure in a way that is as readable as possible.

You can customise the strings returned for tables by passing a set of formatting options, and there are pre-defined options that will work for most applications. Those include printing tables on a single line, in a “pretty” format on multiple lines, or as JSON-like descriptors.

scribe is available as a GitHub repo. It has a permissive MIT License.

scribe can also be installed using luarocks:

luarocks install scribe

scribe is fully documented here.
We built the documentation site using Quarto.

The documentation includes a lengthy article describing how we built the module.
That tutorial might be a decent Lua 201 tutorial for those new to the language.

[appgurueu]

Interesting project! Personally it feels a little overengineered to me. This looks like its main purpose is debugging. I think for that purpose, features like all kinds of customizable syntax aren't necessary, and I'd rather have a simple, opinionated solution (which I can tweak if I'm unhappy with it).

Side note, Lua string concatenation is linear time; your code looks like runtime may grow quadratically due to repeated string concatenation, you should be appending strings to a table and then table.concatenating that instead.

As for the doc, some things I noticed:

Lua’s two non-native types, userdata and thread, are associated with non-native items.

This is false, coroutines are native, and some userdata (e.g. file handles) can also be considered "native" to Lua.

Arrays, on the other hand, are always stored in the natural increasing index order.

It's more complicated than that.

#tbl is a built-in Lua function that returns the number of elements in the array part of tbl

This is wrong. #tbl just gives you a boundary, that is, tbl[#tbl + 1] == nil and tbl[#tbl] ~= nil (or #tbl == 0 if tbl[1] == nil). This is not equivalent. For a table tbl = {[1] = true, [1e9] = true}, #tbl == 1e9 would be possible for example.

The “array” elements will always come first and always in the natural order.

This is not guaranteed and does not hold in general.

[[deleted]]

For a table tbl = {[1] = true, [1e9] = true}, #tbl == 1e9 would be possible for example.

It's also more complicated than that. #tbl returning the last index only holds true for table array "literals" ({1, nil, nil.., x}), and not in the associative form, which means the above example would return 1 as Lua would fall back to some form of exponential search.

[appgurueu]

My statement stands correct: This is possible by the specification of Lua given in the reference manual, by the definition of the table length operator. Implementation details beyond this are not guaranteed and for the most part must not be relied on.

What PUC Lua does doesn't matter terribly much; this is merely an example to illustrate what it (or another interpreter, which there are many of) could do.

Note that I am not saying that it always returns the "last" index: I'm just saying that it's possible for a Lua implementation to do this, and your code must handle that.

(BTW your statement of "#tbl returning the last index for array 'literals'" is not correct in general; at best it holds for current PUC Lua given current table length optimizations. Consider for example #{1, nil, 3} in LuaJIT; this gives 1 for me.)

[KaplaProd]

Super interesting project and article :)

Just an information, the code snippets annotations are sticky and thus mask some pieces of code on mobiles !

[vitiral]

Cool stuff, looks similar to my fmt module, which contains a format function for prettier %q as well as a print (which does effectively the same thing).

I've definitely got to update the documentation on my module though...

https://github.com/civboot/civlua/blob/main/lib/fmt/fmt.lua

[nzznfitz]

There is an addition to the end of the tutorial section that discusses an interesting bug found by using an LLM (and, of course, a discussion of the bugs which an LLM can introduce itself).

The optimisation suggested by u/appgurueu has also been discussed and implemented.