Custom Formatting Options

Introduction

As described in the Standard Formats page, you can directly access any of the pre-canned set of formatting options and change them at will.

For example, if you would prefer that putln("%t", tbl) always produces very compact output you might have preliminary code like:

local scribe = require 'scribe'
scribe.options.inline.inline_spacer =  ''
scribe.options.inline.sep           =  ','
scribe.options.inline.key_end       =  '='

After that, any call like putln("Table: %t", {name = "Mary"}) produces the output {name="Mary"} instead of the prior result { name = "Mary" }. This tighter style then remains in effect until you change those options back to their original settings.

In the Object-to-String page we pointed out that the call scribe.inline(obj) can take an optional second argument. You might use it as:

local tbl = { name = "Mary" }
local overrides = { inline_spacer = '', sep = ',', key_end = '='}
print(scribe.inline(tbl, overrides))

which will produce the output {name="Mary"}.

However, in this case:

The scribe.options.inline table is unchanged.
On return, the overrides table will be fully fleshed out from scribe.options.inline.

This can be very handy when you are trying some experiments to hit on the precise output style you are after. Continue to tweak the overrides table until you are happy and only then use it to replace scribe.options.inline.

Example

Here is an example where we choose to show all keys including array indices. We also change the way keys are shown by putting them in square braces. Finally we change the styling for shared references:

local my_options = {
    show_indices = true,
    key_begin    = '[',
    key_end      = '] = ',
    path_root    = 'ROOT',
    path_sep     = ':'
}

Let’s use my_options to override the standard pretty-printing method:

local list = { p1 = { name = 'Alice' }, p2 = { name = 'Maria' } }
list.p1.next = list.p2
list.p2.prev = list.p1
list.friends = { 'Tom', 'Dick', 'Harry' }
list.home    = list
print(scribe.pretty(list, my_options))

This gives the output:

<ROOT> = {
    [friends] = [ [1] = "Tom", [2] = "Dick", [3] = "Harry" ],
    [home] = <ROOT>,
    [p1] = { [name] = "Alice", [next] = <p2> },
    [p2] = { [name] = "Maria", [prev] = <p1> }
}

After the call, we can look at the full version of my_options by pretty-printing it:

print(scribe.classic(my_options))

to get:

{
    COMPLETE = true,
    array_begin = "[",
    array_end = "]",
    comparator = <function>,
    indent = "    ",
1    inline_size = inf,
    inline_spacer = " ",
    key_begin = "[",
    key_end = "] = ",
    path_begin = "<",
    path_end = ">",
    path_root = "ROOT",
    path_sep = ":",
    sep = ",",
    show_indices = true,
    table_begin = "{",
    table_end = "}",
    use_metatable = true
}

1: Here inf refers to infinity and corresponds to the Lua value math.huge.

Cloning Options

You can also clone an options table to create a new one with the same settings:

local my_options = scribe.clone(scribe.options.inline)

This is useful if you want to create a new options table with the same settings as an existing one, but with some modifications.

One application of this is create a __tostring metamethod for a class MyClass that defers most of the work to scribe.inline:

local my_inline_options = scribe.clone(scribe.options.inline)
my_inline_options.use_metatable = false

function MyClass:__tostring()
    return scribe.inline(self, my_inline_options)
end

This will create a new options table with exactly the same settings as scribe.options.inline, but with use_metatable set to false which prevents infinite recursion when printing objects of class MyClass.

Introduction

Example

Cloning Options

See Also