v0.8.8

This release merely fixes some problems with the Bazel build files in the previous release. As such, there is no need for a corresponding Python release.

v0.8.7

Firstly, Jsonnet users should be aware of a tiny non-backwards-compatible change: It is no longer possible to put spaces or comments between the characters of each of the following operators :: +: ::: and +::: . The fact this was ever possible was an accident of implementation. In fact, we expect no-one was actually writing code like { x: /*foo */: 3 }.

With that out of the way, let's talk about the many new features this release:

The major announcement is the Jsonnet reformatter, which is in many ways like the Go reformatter, including the way it is invoked:

jsonnet fmt foo.jsonnet

(See --help for more details.)

This tool will clean up whitespace, re-indent, and use syntax sugars where possible. It can control the way strings are quoted and the comment style. However it will not (yet) break or join lines. It is quite extensible so please submit issues for more things you think it should fix. An obvious candidate is alphabetic re-ordering of imports!

One thing for which it's very useful is the process of bootstrapping unformatted JSON code into beautiful Jsonnet. To do this, use a standard JSON reformatter like json_pp to line-break the JSON how you want. Then run jsonnet fmt on it to strip the quotes from field names where possible and put commas on the end of lines. That takes care of the most boring aspects of refactoring JSON into Jsonnet!

Another new feature is to add Python style array slicing. This is the ability to do

local arr = ['it', 'was', 'the', 'best', 'of', 'times'];
assert arr[2:4] == ['the', 'best'];
assert arr[1::2] == ['was', 'best', 'times'];
true

This is designed to be compatible with Python, except the ability to use negative numbers to refer to elements relative to the far end of the array. The rationale: We'd rather have an explicit error to catch broken index arithmetic, and you can always use std.length() when you (rarely) need to refer to the last element of an array.

Did you notice the last example used ' for string literals instead of the " as prescribed by JSON? This new kind of string literal is useful in cases when you want to embed " in your string without escaping. It also has a bit less visual clutter.

Another innovation is --yaml-stream, which was implemented primarily for easy output into kubectl (from the Kubernetes project). The idea is that the Jsonnet script manifests into a JSON array, and this is rendered as a "YAML stream". For more context see yaml.org.

$ jsonnet --yaml-stream -e '[{ animal: "dog", sound: "woof" }, { animal: "cat", sound: "meow" }]'
---
{
   "animal": "dog",
   "sound": "woof"
}  
---
{
   "animal": "cat",
   "sound": "meow"
}  
...

The final new feature: We now have JSON merge patch support (RFC7396) in the standard library.

v0.8.6

Aside from minor improvements and bug fixes, this release has one change to the language that is not compatible with previous versions.

Some users pointed out that import "foo" + bar had surprising behavior, because it looks like it will compute the name of the import, but in actual fact it is parsed as (import "foo") + bar, which converts the imported Jsonnet file to a string, then appends bar to it. In order to avoid that confusion, we've make the parentheses mandatory in those cases.

The vast majority of imports, which are unambiguous, are not affected. For example:

local foo = import "foo";

This release also fixes the compilation of Jsonnet during pip install.

v0.8.5

Yet another release needed to fix the Python build.
This release also includes the restrictions on super that should have been in v0.8.1 but the change got lost in the gh-pages branch.

v0.8.4

Fix the Python release (again).

v0.8.3

The last release was broken on Python so this fixes that. It also fixes a bug with decoding high unicode codepoints.

v0.8.2

This release:

• Adds unicode support (finally fixing #1)
• Extends the array and object comprehension syntax to arbtirary if / for specifiers
• Fixes a garbage collection bug when using assertions
• Adds std.count() std.startsWith() and std.endsWith()
• Re-organizes the source tree.

v0.8.1

Jsonnet v0.8.1 release notes

There are 2 major things in this release:

Asserts

The biggest change in this release is the addition of the assert construct. This is backwards-compatible except if you were using 'assert' as an identifier, in which case you'll have to rename it (or use quotes "assert": in the case of a field name).

Assert expressions

assert e1 : e2; e3

Is simply desugared to

if e1 then e3 else error e2

And the : e2 is optional like in Python and Java (except Python uses a comma instead of a colon).

Object assertions (invariants)

It is also possible to put asserts into objects:

local Base = {
    assert self.x <= self.y : "%d greater than %d" % [self.x, self.y],
    x: 1,
    y: 2,
};

These are preserved over inheritance and follow the usual late binding semantics.

Base { x: 3 }  // Raises an error.
Base { x: 3, y: 4 }  // Ok.

This can be useful for enumerations:

local Base = {
    assert std.setMember(self.animal, self.availableAnimals)
           : "%s is not a valid animal" % self.animal,
    animal: error "You must select an animal",
    availableAnimals: ["CAT", "DOG"],
};
Base { animal: "FISH" }  // Raises an error.
Base { animal: "FISH", availableAnimals+: ["FISH"] }  // Ok.

If you want to constrain the base object so the animals cannot be extended, you can do:

local Base = {
    local available_animals = ["CAT", "DOG"],
    assert std.setMember(self.animal, available_animals)
           : "%s is not a valid animal" % self.animal,
    animal: error "You must select an animal",
};

Preventing override of fields

Finally, using this mechanism you can lock down a template so that users can only override the "inputs", not the "outputs". For example imagine building bash scripts as part of a workflow framework:

local Template = {
    user:: error "Must set user",
    command:: error "Must set command",
    outputFile:: "out.log",

    local template = self,
    local output = {
        bash: "sudo %(user)s \"%(command)s\" > %(outputFile)s" % template,
    },
    bash: output.bash,
    assert self == output : "You may not override this template's output."
};
// User code:
Template {user: "myname", command: "ls", bash+:"; echo hi"}

This would produce an error because the assertion prevents the user from adding stuff onto the end of the bash command.

Removal of super as a construct in its own right

Early in development we decided to avoid restrictions in the language to see where this would lead us. Two such cases led to implementation complexity and we were tempted to remove them, but we were not sure if they would be useful. One case was mixins, which turned out to be enormously useful in many cases. The other case was the ability to do super by itself, not just in the context of super.f or super[e]. The semantics of this were tricky to define in the case of extending super, or extending super with itself (although we did so, and the rules are on the website)! It also makes the interpreter and object model harder to implement. To the best of our knowledge, there is not one single person using super in this fashion, so we have now restricted it to just super.f and super[e] as done in other languages.

v0.8.0

This release has a few more examples.

The main new feature is the ability to specify multiline strings more easily, i.e. instead of the ugly

{
    foo: "#!/bin/bash
echo \"Hello world!\"",
}

or the bureaucratic

{
    foo: std.lines([
        "#!/bin/bash"
        "echo \"Hello world!\"",
    ])
}

you can now do the following, which is similar to the YAML "block style" construct.

{
    foo: |||
        #!/bin/bash
        echo "Hello world!"
    |||,
}

The indentation is stripped.

Note that this is just a string literal, so it can be combined with % to do string templating:

{
    foo: |||
        #!/bin/bash
        echo "Hello %(greetable_entity)s!"
    ||| % {
        greetable_entity: "world"
    },
}

v0.7.9

This release has the following changes since v0.7.6 (intermediate versions exist on PyPy but not Github):

• Add std.setMember
• Various bug fixes related to transitive imports not being correctly resolved
• Addition of import_callback to Python bindings