sUTL Studio is an online editor for sUTL

sUTL Studio is a powerful tool for working with sUTL, but it's not completely self explanatory. This How-To guide will help you get started.

1. Log in with your google account

Just click the login button.

It'll ask you to login with your google account. If you have multiple accounts, choose your account carefully, because your sUTL work will be associated with this account.

Once you've logged in via google, you'll see a new empty sUTL Studio workspace, like this:

2. Add a distribution

To work with transforms, you need a distribution to place them in. A distribution is collection of declarations (and declarations are where you actually write sUTL transforms).

On the left you can see a tree. Select the root node in the tree, and then from the "Tree" menu at the top select Add Distribution:

You'll see a new node called "newdist". Click on it, and you'll see a page for editing a distribution. 

For now, we'll leave everything alone except for the name. This distribution is just for experimenting with sUTL, so let's call it "scratch". Type "scratch" into the name field, then click outside the field, and it'll save, and update in the tree, like this:

3. Add a declaration

Now that we've got a distribution, we can add declarations to it. 

While still selected on "scratch" in the tree, choose "Add declaration" from the Tree menu:

You'll see a node called newdecl added under scratch. Click on newdecl and you'll see the following:

This is where you write sUTL! There are four sections, each of which can be opened or closed by clicking on it:

• Properties: This includes the name, and all kinds of other details which aren't code.
• Transform: This is where you create a sUTL transform, which will transform the Source.
• Source: You can enter some sample source data here. The Transform will be evaluated against this Source, and the result will go in Result
• Result: This is the result of evaluating Transform against Source.

Let's give it a go, with a Hello World transform.

First, let's enter some source data; how about the string "Hello World!"? Just click on Source and type in "Hello World!", including the double quotes, like this:

Next, we'll add a transform. Here it is:

The transform will take whatever the source is, and add a prefix to it. If you want to know more about how it works, have a look at the + builtin in the language reference.

Enter it as follows:

Now open the Result pane, and have a look at the transformed result. Try leaving Transform open, but closing Source, like this:

There's your first sUTL Transform, working! Congratulations!

No Save Button

You'll notice that there's no save button. sUTL Studio just autosaves as you go.

Live Editing

Now try editing the transform, and look at what happens to the result. Try editing the string "sUTL says", and watch the result change, like this:

Publish your transform

Your transform is so great, you need to share it with the world!

Click on Properties. Give it the name "MyHelloWorld" (or whatever you like, but don't include any spaces), and then click the Published toggle, like this:

That's all it takes to make your declaration visible to others. So let's see how other people might use it.

Share your "Try" page

Your public Try page is now available. In Properties, click Try Page and you'll be taken to it. Here's the Try Page for my version of the transform above

http://sutl-studio.appspot.com/try?id=82e824aa-cccc-661c-c6af-0a2dd4074c02

but you'll have your own. If you share it with someone, they can try it out, and edit it (without saving over your original work) without authenticating; it's totally public.

Because of this, it's also excellent for embedding; in fact, this is how the live language samples are created in this site. I use code as follows to embed an iframe:

and it looks like this:

Get the sUTL Declaration JSON

To get the sUTL Declaration JSON that you would use in an actual javascript or python project, go to Properties and click Declaration JSON. You'll see a plain text page like the following:

You can copy and paste this into anything that expects JSON, or just save it as a JSON file.

Use your declaration in another declaration

sUTL gets interesting when you start including using one transform from another. You can build up very complex programs in sUTL Studio using the following technique.

First add a new declaration.

Click on scratch, and choose "Add declaration" from the Tree menu. You'll see a new declaration. Name it MySecondDecl in Properties, then add MyHelloWorld to the Requires field. Like this:

The Requires section determines what's available to the transform in its library. We can see that by using the transform

(this means "select everything from the library), then looking at Result. It should look like this:

(if Result doesn't update, try clicking in the Result's code window)

See "MyHelloWorld" in there? This means you can use MyHelloWorld inside MySecondDecl! Let's try it.

Change the MySecondDecl Transform to this:

and let's make the source:

You should get the following:

What's going on here? We're pulling in MyHelloWorld. It's being evaluated, and the whole thing is wrapped in a dictionary, under the key message. Finally, the message is slightly different, because we're passing in a different source.

Using the core library

We've been writing basic sUTL. How about we try doing something a bit trickier?

Instead of just outputting one message, what if we wanted to output a list of them? There's a great transform called map in the core library, which lets you iterate over a list and transform it. Let's try it.

First we need access to the core library.

Click on scratch, and have a look at the message below "Requires". It tells you to paste a big ugly string into Requires if you want to use the core library. That string is this:

So do that. It'll look like this:

Now, while you're selected on scratch, choose add declaration from the Tree menu, then click on the newdecl declaration and rename it to MyTrickyDecl. Then add MyHelloWorld and map_core to the Requires section of MyTrickyDecl.

Put the transform we used earlier for seeing the library ( "^*" ) into the Transform. You should now have this:

and open Result. You should see the following:

You can see two declarations in the library; MyHelloWorld and map_core.

Now let's use them.

First in the source, let's have a list of messages:

Next, we use the following transform:

It's ok to feel a bit lost at this point! I'll talk it through, but do have a look at the learn menu, you can read about how sUTL works. 

The transform uses map_core to iterate over the a list, and transform each item in it. The list attribute determines what the list will be, in this case the entire source, ie: the list containing our three messages. So far so good.

The attribute t provides a sub-transform to apply to each item in the list. It uses the "!!" style of evaluation, which lets you provide a replacement scope (using the s attribute) to another transform (using the !! attribute). We've selected MyHelloWorld from the library using the path "^*.MyHelloWorld". So t evaluates MyHelloWorld using the current item in the list ("^@.item") as the scope (which is what MyHelloWorld expects). 

Having a look at the result, this is what we get:

If you got this far, that's pretty amazing. Thanks for persevering, and I hope you're starting to see what a useful tool sUTL Studio is for working with sUTL!