The Core Library

The Core Library is a list of declarations (a distribution) full of generally useful transforms.

In the future it may just be packaged directly with sUTL itself, but for now it is separate; you can find the sUTL Core Library here on github. You can see just the core library distribution itself here directly.

In the examples below, the transforms are named using "_core", eg "map_core". This is to disambiguate them from other names in context (eg: many of the example declaration names start with the name of the transform being demonstrated). Using the "_core" suffix is good practice, and may save you some debugging heartache.

The Core Library transforms are written in pure sUTL, and are well worth a look as examples of more advanced techniques in the language.

map

The map transform visits every element in list, and transforms it using the transform t. Inside transform t, the current element is available in the scope as "^@.item".

{
    "&": "map_core",
    "list": <list>,
    "t": {":": <transform> }
}

eg:

reverse

The reverse transform reverses a list.

{
    "&": "reverse_core",
    "list": <list>
}

eg:

removenulls

This transform removes all null items from a list

{
    "&": "removenulls_core",
    "list": <list>
}

eg:

count

The count transform counts how many items are in a list, including recursively counting sub-lists. It calculates this as follows:

Is the obj a list?
- yes: call count recursively on each element of the list; the final result is the sum of these results.
- no: the result is 1.

{
    "&": "count_core",
    "obj": <data>
}

In this example, you see count compared to the builtin len:

zip

This is the classic zip function. It performs a convolution on a list of lists. Note that the behaviour where sublists are of varying lengths is currently undefined.

The python interpreter has a builtin called "zip", which you can use instead of "zip" in the core library. It's a native python implementation, and runs much faster than the pure sUTL version.

{
    "&": "zip",
    "list": <list of lists>
}

In this example you see zip being applied once, and then being applied twice (which gets you back to the original input).

addmaps

This transform combines two dictionaries (the term "map" is used as a synonym for dictionary here). It takes two arguments, map1 and map2; the items in map2 take precedence over those in map1.

{
    "&": "addmaps",
    "map1": <dict>,
    "map2": <dict>
}

eg:

mapget

mapget is a simple transform that lets you select a key from a dictionary, where the key can be referenced from somewhere else.

{
    "&": "mapget",
    "map": <dictionary>,
    "key": <string>
}

Note that this isn't a terribly useful transform, in that you really just want to do what it's underlying implementation does; use the list version of the path operator:

[
    "&@",
    "map",
    "^@.key"
]

You can see both approaches in the example:

keys2map

keys2map takes a list of strings, and turns them into a dictionary, using them as keys, with the value true. This is a straightforward way to turn a list into a structure that functions like a set.

{
  "&": "keys2map",
  "list": <list of strings>
}

eg:

isinlist

isinlist takes a list and an item, and evaluates to a boolean indicating whether the item it in the list.

{
  "&": "isinlist",
  "list": <list>,
  "item": <value>
}

eg:

idlisttomap

This takes a list of objects and a path to a key inside each object, and return a dictionary of those objects indexed by the specified keys.

{
  "&": "idlisttomap",
  "list": <list>,
  "keypath": <list of indices into dictionaries and lists>
}

eg:

filter

This transform applies a filter transform to each element of a list, and resolves to a list. If that filter transform is truthy for an element, it appears in the result list, otherwise it does not.

{
  "&": "filter",
  "list": <list>,
  "filter-t": <filter transform>
}

eg:

join

This transform joins together a list of strings with a separator, also allowing a special final separator.

{
  "&": "join",
  "list": <list>,
  "separator": <string>, // defaults to ", "
  "lastseparator": <string>, // defaults to " and "
}

eg:

to be continued