deepprops

A set of utility routines used to operate on deep proplists.

A set of utility routines used to operate on deep proplists.

This single module has been designed to hit three primary goals: allow you to access deeply nested properties inside proplists; admit you to mutate proplists; allow you to access a group of properties with a single call.

DATA TYPES

path() = term() | [term()]

Functions

get(Path, Proplist) -> Result

  • Path = path()
  • Proplist = proplist() (see module proplists)
  • Result = term() | undefined

get(Path, Proplist, Default) -> Result

  • Path = path()
  • Proplist = proplist() (see module proplists)
  • Result = term() | Default
  • Default = term()

Retrieves value of a property located and possibly deeply nested inside the property list Proplist under path Path.

Path may be a single Key thus denoting that the property located on the top level of a property list. As well as a list of keys it may be noting that the property is located inside a property list which is located inside another property list and so on until the top level Proplist is finally reached.

When there is no property under the Path the Default shall be the result of a call or undefined if Default has been not specified.

Finally for the sake of clarity the following code will run with no exceptions: 

  Proplist = [ {top, [ {level, [ {thing, 2}, {where, 3} ]}, {middle, 4} ]}, {last, 5} ],
  Result = 4,
  Result = deepprops:get([top, middle], Proplist).

require(Path, Proplist) -> Result

  • Path = path()
  • Proplist = proplist() (see module proplists)
  • Result = term() | no_return()

Retrieves mandatory value of a property located and possibly deeply nested inside the property list Proplist under path Path.

The only difference with get/2 is in the case when no value is present under the given key. In such situations {novalue, Path} exception will be thrown.

See also: get/2.

set(Path, Value, Proplist) -> Result

  • Path = path()
  • Value = term()
  • Proplist = proplist() (see module proplists)
  • Result = proplist() (see module proplists)

Sets value of a property to the Value and returns new property list.

Property located and possibly deeply nested inside the property list Proplist under path Path.

Path may be a single key Key thus denoting that the property located on the top level of a property list. As well as a list of keys it may be noting that the property is located inside a property list which is located inside another property list and so on until the top level Proplist is finally reached.

If there is already such property exists the one's value will be replaced with new Value. Otherwise the property will be appended to the deepest enclosing proplist addressed by the Path.

And finally let us clarify with the following valid example: 

  Proplist = [ {top, [ {level, [ {thing, 2}, {where, 3} ]}, {middle, 4} ]}, {last, 5} ],
  Result = [ {top, [ {level, [ {thing, new}, {where, 3} ]}, {middle, 4} ]}, {last, 5} ],
  Result = deepprops:set([top, level, thing], new, Proplist).

append(Path, Value, Proplist) -> Result

  • Path = path()
  • Value = property() (see module proplists)
  • Proplist = proplist() (see module proplists)
  • Result = proplist() (see module proplists)

Appends the new entry Value to the list located under a property and returns new property list.

Property located and possibly deeply nested inside the property list Proplist under path Path.

Path may be a single key Key thus denoting that the property located on the top level of a property list. As well as a list of keys it may be noting that the property is located inside a property list which is located inside another property list and so on until the top level Proplist is finally reached.

If there is no such property under Path the new one will be created and set to the [Value]. Otherwise the Value will be appended to the head of the list which is value of the property. Please be careful when appending value to anything but a list because malformed list will then be created

And finally let us clarify everything with the following valid example: 

  Proplist = [ {top, [ {middle, [4]} ]}, {last, 5} ],
  Result = [ {top, [ {middle, [new, 4]}, {last, 5} ],
  Result = deepprops:append([top, middle], new, Proplist).

extract(Path, Proplist) -> Result

  • Path = path()
  • Proplist = proplist() (see module proplists)
  • Result = {Value, proplist() (see module proplists)}
  • Value = term()

extract(Path, Proplist, Default) -> Result

  • Path = path()
  • Proplist = proplist() (see module proplists)
  • Result = {Value, proplist() (see module proplists)}
  • Value = term() | Default
  • Default = term()

Extracts the property from the property list Proplist and return its value and new property list with the property removed.

Property located and possibly deeply nested inside the property list Proplist under path Path.

Path may be a single key Key thus denoting that the property located on the top level of a property list. As well as a list of keys it may be noting that the property is located inside a property list which is located inside another property list and so on until the top level Proplist is finally reached.

If there is such property found then the result will be the tuple {Value, Rest} where Value is value of the propery and Rest is property list formed after the original with found property removed from the deepest enclosing property list addressed by the `Path.

On the other hand if no such property actually the tuple {Default, Proplist} returned where Proplist is the original property list untoched and Default is equal to undefined when no Default value have been passed.

And finally let us clarify everything with the following: 

  Proplist = [ {top, [ {level, [ {thing, 2}, {where, 3} ]} ]}, {last, 5} ],
  Result = 3,
  Rest = [ {top, [ {level, [ {thing, 2} ]} ]}, {last, 5} ],
  {Result, Rest} = deepprops:extract([top, level, where], Proplist).

values(Paths, Proplist) -> Results

  • Proplist = proplist() (see module proplists)
  • Paths = [Path]
  • Path = PurePath | {PurePath, Default}
  • PurePath = path()
  • Default = term()
  • Results = [Result]
  • Result = term() | Default | undefined

Retrieves values of one or more properties with a single invocation. These values form a list which strictly preserve order of properties accessed.

This function performs much like group get call. In other words the result of this function will be equal to sequential application of deepprops:get/3 in the way close to folding.

Properties located and possibly deeply nested inside the property list Proplist addressed by one or more paths in Paths. A path then may be a single PurePath (explained further) which is semantically equal to {PurePath, undefined}. As well as a tuple {PurePath, Default} may be specified thus denoting that in the case of absence of the property the Default will be the value in the list of values. Therefore undefined will be that value when Default is not specified.

PurePath may be a single key Key thus denoting that the property located on the top level of a property list. As well as a list of keys it may be noting that the property is located inside a property list which is located inside another property list and so on until the top level Proplist is finally reached.

Then following final clarification example: 

  Proplist = [ {top, [ {level, [ {thing, 2}, {where, 3} ]}, {middle, 4} ]}, {last, 5} ],
  Result = [ 2, def, 5 ],
  Result = deepprops:values([ [top, level, thing], {[top, down], def}, last ], Proplist).

In the latter example the value def was returned for path [top, down]. If the default value was not specified through {[top, down], def} then the undefined would be returned instead.

See also: get/3.

split(Paths, Proplist) -> Result

  • Proplist = proplist() (see module proplists)
  • Paths = [Path]
  • Path = PurePath | {PurePath, Default}
  • PurePath = path()
  • Default = term()
  • Result = {[Value], Rest}
  • Value = term()
  • Rest = proplist() (see module proplists)

Extracts values of one or more properties with a single invocation and returns them along with new property list with these properties removed. These values form a list which strictly preserve order of properties accessed.

This function performs much like group extract call. In other words the result of this function will be equal to sequential application of deepprops:extract/3 in the way close to folding.

Properties located and possibly deeply nested inside the property list Proplist addressed by one or more paths in Paths. A path then may be a single PurePathas well as a tuple {PurePath, Default} thus denoting that in the case of absence of the property the Default will be the value in the list of values. Therefore undefined will be that value when Default is not specified.

The function call will return tuple {Values, Rest} where Values is list of values being explained and the Rest is property list with properties addressed by Paths removed from the corresponding deepest enclosing property lists. Obviously the absent properties are not removed.

PurePath may be a single key Key thus denoting that the property located on the top level of a property list. As well as a list of keys it may be noting that the property is located inside a property list which is located inside another property list and so on until the top level Proplist is finally reached.

Finally goes the clarification example: 

  Proplist = [ {top, [ {level, [ {thing, 2}, {where, 3} ]}, {middle, 4} ]}, {last, 5} ],
  Result = [ 2, def, 5 ],
  Rest = [ {top, [ {level, [ {where, 3} ]}, {middle, 4} ]} ],
  {Result, Rest} = deepprops:split([ [top, level, thing], {[top, down], def}, last ], Proplist).

See also: extract/3.

list(Paths, Proplist) -> Result

  • Proplist = proplist() (see module proplists)
  • Paths = [path()]
  • Result = [Prop]
  • Prop = property() (see module proplists)

Returns plain sublist of the property list with properties under Paths being retrieved.

Properties located and possibly deeply nested inside the property list Proplist addressed by one or more paths in Paths. A Path then may be a single key Key thus denoting that the property located on the top level of a property list. As well as a list of keys it may be noting that the property is located inside a property list which is located inside another property list and so on until the top level Proplist is finally reached.

Worth noting that when property is not present under specific Path the resulting list misses this property totally. Thus length of the result may be less than the length of Paths. But the ordering is still preserved even in such cases.

Finally for the sake of clarity it is guaranteed that the following code will run with no exceptions: 

  Proplist = [ {top, [ {level, [ {thing, 2}, {where, 3} ]}, {middle, 4} ]}, {last, 5} ],
  Result = [ {[top, level, thing], 2}, {last, 5} ],
  Result = deepprops:list([ [top, level, thing], [top, down], last ], Proplist).

defaults(Defaults, Proplist) -> Result

  • Proplist = proplist() (see module proplists)
  • Defaults = proplist() (see module proplists)
  • Result = proplist() (see module proplists)

Retrieves the property list formed by substitution any missing properties with default ones from Defaults.

If Defaults contains a property which is present in Proplist too last one left untouched. Otherwise the Proplist is populated with property from Defaults. It may seem like merging of two proplists with respect to values in the Proplist.

View Functions