Module nested

Nested data file format and nested tables functionality.

Fields

_VERSION Current version string
POSTORDER Postorder key to be passed to iterate options ('postorder')
POSTORDER_ONLY Postorder only value to be passed to iterate options ('only')
TABLE_ONLY Table only key to be passed to iterate options ('table_only')
INCLUDE_KV Include key-value key to be passed to iterate options ('include_kv')
SKIP_ROOT Skip root key to be passed to iterate options ('skip_root')

Decoding

decode (text[, options]) Decode a nested structure from text.
decode_file (file_or_filename[, options]) Decode a nested structure from file.
decode_iterate (text) Iterator function that parses nested structure from text input, yielding meaningful tokens.

Encoding

encode (t[, indent=2[, apply_tostring_to_tables]]) Encode a nested table structure to text.
encode_to_file (t, file_or_filename[, indent[, apply_tostring_to_tables]]) Encode a nested table structure to file.

Iterating over tables

kpairs (t) Iterate over non-numeric key-value pairs.
iterate (t[, options]) Iterate in depth over a nested table.

Getting and setting nested values

get (t, ...) Get the value of a nested table.
get_or_create (t, ...) Similar to get, but creates the nested structure if it doesn't exist yet.
set (t, ...) Set the value of a nested table.
set_or_create (t, ...) Similar to set, but creates the nested structure if it doesn't exist yet.

Default filters

bool_number_filter (text[, quotation_mark]) Simple text filter that reads unquoted boolean and number values, meant to be passed to decode.


Fields

_VERSION
Current version string
  • _VERSION
POSTORDER
Postorder key to be passed to iterate options ('postorder')
  • POSTORDER
POSTORDER_ONLY
Postorder only value to be passed to iterate options ('only')
  • POSTORDER_ONLY
TABLE_ONLY
Table only key to be passed to iterate options ('table_only')
  • TABLE_ONLY
INCLUDE_KV
Include key-value key to be passed to iterate options ('include_kv')
  • INCLUDE_KV
SKIP_ROOT
Skip root key to be passed to iterate options ('skip_root')
  • SKIP_ROOT

Decoding

decode (text[, options])
Decode a nested structure from text.

In case of unmatched quotes or unbalanced block delimiters, returns nil plus error message.

Parameters:

  • text Text to be decoded
  • options

    Table with any of the optional following fields:

    • text_filter: Function to filter data from text values. Receives the text, quotation mark, starting line and column as parameters. If it returns a non-nil value, the text is replaced by it in the resulting table.
    • table_constructor: Function used for constructing tables. Receives as parameter the opening character: '' for toplevel tables, (, [ or {, the starting line and column as parameters Must return a table. This is useful for injecting metatables into resulting nested structure.
    • root_constructor: Function used for constructing the root table. Defaults to table_constructor, if specified.
    (optional)

Returns:

    nested table decoded

Or

  1. nil
  2. error message
decode_file (file_or_filename[, options])
Decode a nested structure from file.

This uses decode, so the same caveats apply.

Parameters:

  • file_or_filename File or filename to read from, opened with io.input
  • options Forwarded to decode (optional)

Returns:

    nested table decoded

Or

  1. nil
  2. error message

See also:

decode_iterate (text)
Iterator function that parses nested structure from text input, yielding meaningful tokens.

This allows one to fully customize the results from parsing, for example stopping before reading the whole text and ignoring whole branches from the input.

Each time the coroutine is resumed, it yields the current line and column, the parsing event and additional information if needed. Check out the usage example for possible values and meaning of each value.

Check out the implementation of decode for a concrete example of usage.

Unless the given parameter is not a string, the coroutine should not error.

Parameters:

  • text Text to be decoded

Returns:

    function Coroutine function for parsing

Usage:

    for line, column, event, token, quote in nested.decode_iterate(text) do
    if event == 'TEXT' then
        -- token: string representing the text value
        -- quote: nil if text is not quoted, or one of ' " ` otherwise
    elseif event == 'KEY' then
        -- token: the key used in a key-value form "key:"
        -- quote: nil if the key is not quoted, or one of ' " ` otherwise
    elseif event == 'OPEN_NESTED' then
        -- token: the opening token for nested tables, one of [ { (
    elseif event == 'CLOSE_NESTED' then
        -- token: the closing token for nested tables, one of ] } )
    elseif event == 'ERROR' then
        -- token: the error message
        -- iteration ends after the first error, no need for break
    end
until not event

Encoding

encode (t[, indent=2[, apply_tostring_to_tables]])
Encode a nested table structure to text.

Non-table values are encoded using tostring, so __tostring metamethods may be called for userdata.

Althought the nested textual format doesn't support references between tables other than parent/child relations, Lua does. For this matter, anchors of the form &N, where N is a number, are placed in tables that are referenced somewhere else, with the references for the table written in the form *N with the same numerical N used before.

In the same line, although the nested textual format only supports text as keys, table keys in Lua might be booleans, functions, userdata or other tables. This function will encode them, but be aware that the resulting text might error when read again with decode, and that nested is not a complete serialization scheme for Lua tables.

Parameters:

  • t Table
  • indent Indentation level to use, in spaces. If > 0, each value will be placed in a new line, prefixed by the given number of space characters. If == 0, no new lines will be used and values will be written separated by a single space character. If < 0, no new lines will be used and values will be written in a compacted and probably illegible way. (default 2)
  • apply_tostring_to_tables If truthy, if a table has a __tostring metamethod, it will be applied instead of the default nested traversal. (optional)

Returns:

    string Encoded nested structure
encode_to_file (t, file_or_filename[, indent[, apply_tostring_to_tables]])
Encode a nested table structure to file.

This uses encode, so the same caveats apply.

Parameters:

  • t Table
  • file_or_filename File or filename to write to, opened with io.output
  • indent Forwarded to encode. (optional)
  • apply_tostring_to_tables Forwarded to encode. (optional)

Returns:

    true

Or

  1. nil
  2. Error message if writing to file failed

Iterating over tables

kpairs (t)
Iterate over non-numeric key-value pairs.

This is a shallow iteration. For iterating over nested tables, use iterate instead.

This uses pairs, so the __pairs metamethod may be called in Lua 5.2+

Parameters:

  • t Table

Usage:

    for k, v in nested.kpairs(t) do
    ...
end
iterate (t[, options])
Iterate in depth over a nested table.

On each call, returns a sequence table with the current key path, value, parent table and boolean flag signaling if going deeper (preorder traversal) into the nested structure or not (postorder traversal).

Parameters:

  • t Table
  • options

    Table with any of the following fields:

    • postorder: if truthy, also yield values when traversing back from the default preorder traversal. If equal to "only", perform only the postorder traversal.
    • table_only: if truthy, yield table values only.
    • include_kv: if truthy, iterate on key-value pairs as well as numeric indices.
    • skip_root: if truthy, iterate on key-value pairs as well as numeric indices.
    (optional)

Usage:

    for keypath, value, parent, going_deeper in nested.iterate(t) do
    ...
end

Getting and setting nested values

get (t, ...)
Get the value of a nested table.

If the given key path cannot be indexed, returns nil plus a message with where on the key path indexing failed.

Parameters:

  • t Table
  • ... Values passed in form the key path, with which each nested table will be indexed. If only one value is passed and it is a table, it is treated as the keypath.

Returns:

    value

Or

  1. nil
  2. error message
get_or_create (t, ...)
Similar to get, but creates the nested structure if it doesn't exist yet.

Parameters:

  • t Table
  • ... Values that form the key path, just like in get.

Returns:

    value

Or

  1. nil
  2. error message

See also:

set (t, ...)
Set the value of a nested table.

If the given key path cannot be indexed, returns nil plus a message with where on the key path indexing failed.

Parameters:

  • t Table
  • ... The first values passed in form the key path, and the last one is the value to be set. If the key path has only one table value, then it is treated as the keypath.

    To unset a value, nil have to be passed explicitly as the last argument.

Returns:

    t

Or

  1. nil
  2. error message
set_or_create (t, ...)
Similar to set, but creates the nested structure if it doesn't exist yet.

Parameters:

  • t Table
  • ... Values to form the key path and value to be set, just like in set.

Returns:

    t

Or

  1. nil
  2. error message

See also:

Default filters

bool_number_filter (text[, quotation_mark])
Simple text filter that reads unquoted boolean and number values, meant to be passed to decode.

Literal true and false values are recognized as the boolean true and false lua values. Quoted versions, like "true" and 'false' are not parsed and treated as strings.

Numbers are read with tonumber. Similar to booleans, quoted numbers like '1' or "0.5" are not parsed and treated as strings.

Parameters:

  • text
  • quotation_mark (optional)

Usage:

    local data = nested.decode(text, { text_filter = nested.bool_number_filter })
generated by LDoc 1.4.6 Last updated 2021-07-20 01:00:30