Module jls.util.tables

Provide table helper functions.

This module allows deep table manipulation.

Functions

tables.parse (value) Returns the value corresponding to the specifed string.
tables.stringify (value[, space[, lenient]]) Returns a string representing the specifed value.
tables.merge (target, source, keep) Copies the value from the source table into the target.
tables.compare (oldTable, newTable[, list]) Returns a table containing the differences between the two specified tables.
tables.patch (oldTable, diff) Returns a table patched according to the specified differences.
tables.get (t, ...) Returns the value at the indices in the deep table
tables.set (t, value, ...) Sets the value at the indices in the deep table The intermediary indices are created if necessary.
tables.getPath (t, path, defaultValue[, separator]) Returns the value at the specified path in the specified table.
tables.setPath (t, path, value[, separator]) Sets the specified value at the specified path in the specified table.
tables.removePath (t, path[, separator]) Removes the value at the specified path in the specified table.
tables.getSchemaValue (schema, value[, populate[, onError]]) Returns the value validated by the JSON schema or nil.
tables.createArgumentTable (arguments[, options]) Returns a table containing an entry for each argument name.
tables.getArgument (t, name[, def[, i[, asString[, sep]]]]) Returns the argument value for the specified argument name.


Functions

tables.parse (value)
Returns the value corresponding to the specifed string.

Parameters:

  • value string the Lua value to parse as a string.

Returns:

    the value corresponding to the specifed string.
tables.stringify (value[, space[, lenient]])
Returns a string representing the specifed value. The value must be of type boolean, number, string or table. Lenient mode allows to ignore cycles and invalid types.

Parameters:

  • value the value to convert.
  • space string The indent value to use. (optional)
  • lenient boolean whether or not be lenient. (optional)

Returns:

    string a string representing the specifed table value.
tables.merge (target, source, keep)
Copies the value from the source table into the target. This is a deep copy, sub table are also merged.

Parameters:

  • target table the table to copy.
  • source table a modified table.
  • keep boolean true to indicate that existing target value should be kept, default is false.

Returns:

    table the target table.
tables.compare (oldTable, newTable[, list])
Returns a table containing the differences between the two specified tables. The additions or modifications are availables, the same values are discarded and the deleted keys are listed in a specific table entry named "_deleted". The list mode aims to be compatible with JSON by using string keys.

Parameters:

  • oldTable table a base table.
  • newTable table a modified table.
  • list boolean true to use strings for list keys and a specific table entry named "_list". (optional)

Returns:

    table the differences or nil if there is no such difference.
tables.patch (oldTable, diff)
Returns a table patched according to the specified differences.

Parameters:

  • oldTable table a base table.
  • diff table the differences to apply to the base table.

Returns:

    table a new patched table.
tables.get (t, ...)
Returns the value at the indices in the deep table

Parameters:

  • t table a table
  • ... The indices to get the deep table value.

Returns:

    the value or nil if any intermediary index does not match a table.

Usage:

    local tables = require('jls.util.tables')
tables.get({a = {b = 'Hi'}}, 'a', 'b') -- Returns 'Hi'
tables.set (t, value, ...)
Sets the value at the indices in the deep table The intermediary indices are created if necessary.

Parameters:

  • t table a table
  • value The value to set.
  • ... The indices to set the deep table value.

Returns:

  1. table the table or nil if any intermediary index does not match a table.
  2. the value or nil if any intermediary index does not match a table.
tables.getPath (t, path, defaultValue[, separator])
Returns the value at the specified path in the specified table. A path consists in table keys separated by slashes. A key is interpreted as a boolean, a number then a string. A key could be protected in brackets, without separator, ["1"] is interpreted as a string, not a number. The key are considered as string, number or boolean. Table or userdata keys are not supported.

Parameters:

  • t table a table.
  • path string the path to look in the table.
  • defaultValue the default value to return if there is no value for the path.
  • separator string the path separator, default is /. (optional)

Returns:

    the value
tables.setPath (t, path, value[, separator])
Sets the specified value at the specified path in the specified table.

Parameters:

  • t table a table.
  • path string the path to set in the table.
  • value the value to set.
  • separator string the path separator. (optional)

Returns:

    the previous value.
tables.removePath (t, path[, separator])
Removes the value at the specified path in the specified table.

Parameters:

  • t table a table.
  • path string the path to remove in the table.
  • separator string the path separator. (optional)

Returns:

    the removed value.
tables.getSchemaValue (schema, value[, populate[, onError]])
Returns the value validated by the JSON schema or nil. See https://json-schema.org/

Parameters:

  • schema table the JSON schema.
  • value the value to get from.
  • populate boolean true to parse string values and populate objects, default is false. (optional)
  • onError function a function that will be called when a validation error has been found. the function is called with the arguments: code, schema, value, path. (optional)

Returns:

    the value validated against the schema.
tables.createArgumentTable (arguments[, options])
Returns a table containing an entry for each argument name. An entry contains a string or a list of string. An argument name is prefixed by one or two commas ('-') and starts with a letter. An argument value could be prefixed by three commas to escape a starting comma, '---a' means '-a'. A missing argument value results in the value 'true', multiple argument values result in a table value.

Parameters:

  • arguments string the command line containing the arguments.
  • options the options.
    • separator string the path separator, default is the dot ('.'). (optional)
    • emptyPath string the path used for arguments without name, default is zero ('0'). (optional)
    • defaultValues table the default values, could be a module name. (optional)
    • helpPath string the path used to print the help from the schema. (optional)
    • help string the help text to display. (optional)
    • configPath string the path for a configuration file. (optional)
    • configLoader function the function to load the configuration file, could be a module name. (optional)
    • schema table the schema to validate the argument table, could be a module name. (optional)

Returns:

  1. table the arguments as a table.
  2. table the custom arguments from command line and configuration file.
tables.getArgument (t, name[, def[, i[, asString[, sep]]]])
Returns the argument value for the specified argument name.

Parameters:

  • t table the argument table.
  • name string the argument name.
  • def any the value to return when the argument name is not found, default is nil. (optional)
  • i number the index to return when the value is a table, default is 1. (optional)
  • asString boolean true to return a string. (optional)
  • sep string the path separator, default is '.'. (optional)

Returns:

    the argument value or the default value.
generated by LDoc 1.4.6