Module utils.path

Path utils.

Definition of path used by this file:

• it is not Lua path, Lua path meaning the way Lua provide table indexing.
  • especially, 'table[ ]' notation is not supported
• element separator is '.' (dot)
• provided path is always cleaned before being processed:
  • if the path starts and/or ends with one or several dots, there are automatically removed.
    e.g.: '...toto.tutu....' means 'toto.tutu'
  • internal repetitions of successives dots are replaced by a single dot.
    e.g.: 'toto...tutu.tata..foo.bar' means 'toto.tutu.tata.foo.bar'
• if a path element can be converted to a number, then it is returned as a number, otherwise all elements or paths are returned as strings.
  e.g.: split('a.2', 1) -> ('a', 2) (where 2 is returned as a number)
  e.g.: split('a.b.2e3.c', 1) -> ('a', 'b.2000.c')

Type utils.path

utils.path.clean(path)	Cleans a path.
utils.path.concat(varargs)	Concatenates a sequence of path strings together.
utils.path.find(t, path, force)	Retrieves the element in a sub-table corresponding to the path.
utils.path.get(t, path)	Gets the value of a table field.
utils.path.gsplit(path)	Enumerates path partitions in a for-loop generator, starting from the right.
utils.path.segments(path)	Splits a path into segments.
utils.path.set(t, path, value)	Sets a value in a tree-like table structure.
utils.path.split(path, n)	Splits a path into two halves, can be used to get path root, tail etc.

Type utils.path

Field(s)

utils.path.clean(path)

Cleans a path.

Removes trailing/preceding/doubling '.'.

Parameter

• path : string containing the path to clean.

Return value

cleaned path as a string.

utils.path.concat(varargs)

Concatenates a sequence of path strings together.

Parameter

• varargs : list of strings to concatenate into a valid path

Return value

resulting path as a string

utils.path.find(t, path, force)

Retrieves the element in a sub-table corresponding to the path.

Parameters

• t : is the table to look into.

• path : can be either a string (see segments) or an array where path[1] is the root and path[n] is the leaf.

• force : parameter allows to create intermediate tables as specified by the path, if necessary.

Return value

returned values depend on force value:

• if force is false (or nil), find returns the table if it finds one, or it returns nil followed by the subpath that points to non table value

• if force is true, find overwrites or create tables as necessary so it always returns a table.

• if force is 'noowr', find creates tables as necessary but does not overwrite non-table values. So as with force=false, it only returns a table if possible, and nil followed by the path that points to the first neither-table-nor-nil value otherwise.

Usage:

config = {toto={titi={tutu = 5}}}
    find(config, "toto.titi") -- will return the table titi

utils.path.get(t, path)

Gets the value of a table field.

The field can be in a sub table.

The field to get is indicated by a path relative to the table.

Parameters

• t : table where to get the value.

• path : can be either a string (see split) or an array where path[1] is the root and path[n] is the leaf.

Return values

1. value if the field is found.

2. nil otherwise.

utils.path.gsplit(path)

Enumerates path partitions in a for-loop generator, starting from the right.

For instance, gsplit "a.b.c" will generate successively ("a.b.c", ""), ("a.b", "c"), ("a", "b.c"), ("", "a.b.c").

Parameter

• path : the path as a string

Return value

the for-loop iterator function

utils.path.segments(path)

Splits a path into segments.

Each segment is delimited by '.' pattern.

Parameter

• path : string containing the path to split.

Return value

list of split path elements.

utils.path.set(t, path, value)

Sets a value in a tree-like table structure.

The value to set is indicated by the path relative to the table. This function creates the table structure to store the value, unless the value to set is nil. If the value to set is nil and the table structure already exists then the value is set to nil. If the value is not nil, then the table structure is always created/overwritten and the value set.

Parameters

• t : table where to set the value.

• path : can be either a string (see utils.path.split) or an array where path[1] is the root and path[n] is the leaf.

• value : the value to set.

utils.path.split(path, n)

Splits a path into two halves, can be used to get path root, tail etc.

The content of the two halves depends on 'n' param: there will be n segments in the first half if n>0, -n segments in the second half if n<0.

If there are less then n segments, returns the path argument followed by an empty path.

If there are less then -n segments, returns an empty path followed by the path argument.

Note that if a half is a single element and that this element can be converted into a number, it is returned as a number.

Parameters

• path : the path as a string

• n : number defining how the path is splitted (see above description).

Return value

the two halves

Usage:

local root, tail = split('a.b.c', 1)
->root contains 'a', tail contains 'b.c'