Using sUTL in Python

Install via pip using the package "sutl", like so:

pip install sutl

Here's me installing sUTL on my development machine, then using it in python 2.7 :

I do a lot of work with Python on AppEngine, so please excuse my use of this ancient version.

So what's going on?

Once I've started python, the first thing I do is to import sUTL. The "sUTL.sUTL" is due to me not quite getting the package structure right; this will be fixed in a future version, but I'll retain backward compatibility for this form.

Then, I'm calling the evaluate function. It takes a source JSON data structure (ie: python dicts, lists, simple types), a transform, and a library. You can see I've passed in a dictionary with "x":5 as the source, then used the path transform "^@.x" to select the value of "x" from it, so the result is 5.

The library here is empty.

I can load my transforms from files if I prefer. Say my transform is stored in a file called trans1.json, then I can do this:

Using libraries

Say you'd like to include the core library in your python work. 

You can get the core library from github, or you can get the core library from sUTL Studio. These are probably slightly out of sync! I'll add the core library to the sUTL package or to its own package in the near future, but for now either of these will work.

Grab the core library, save it in a file. In the following code I've saved it in the file "sUTLcore.json".

Then, grab this declaration from this link:

and save it into the file "trans2.json".

Note that this declaration has a requires section. We need the required declaration, "join_core", to be in the library when we call evaluate. To get this library, we'll use compilelib.

compilelib

In python, I load both these files into JSON data structures as so:

(note that I should have called the file decl2.json, not trans2.json, because it contains a declaration, not a transform, sorry!)

Now, we pass the declaration and the core library distribution to the compilelib function:

This is the compilelib function:

• decls: A list of declarations that you want to create a library for. 
• dists: A list of distributions that you want to draw from for the library
• test: Something that's going away :-). Just pass false.

What compilelib returns is a dictionary with one key, "lib". In that key is the library you need to pass to the declaration when transforming it.

compilelib takes a bit of work. Once calculated, feel free to cache the resulting lib and use it for the given declaration as necessary. You could even precalculate this outside your code, then save the lib in a file and use it at runtime.

Note that compilelib allows you to pass a list of decls. It will compile a library that is suitable for use for all the given decls (basically a union of all their minimum libraries). If you've got a bunch of decls you want to use, choose whether you want to compile one larger library, or lots of smaller ones.

then evaluate

Now you've got the lib, you can call evaluate:

Note the use of decl["transform-t"] . Remember that the declaration isn't a transform, but contains the transform in the attribute "transform-t". 

And compare that result to the result in the try page above.

So that should be enough to get you going with sUTL in Python.