usage.md

Usage

Create a context

A {py:obj}starlark_go.Starlark object is needed to provide a context (mainly, a set of global variables) for executing Starlark code. Creating an empty one is simple:

from starlark_go import Starlark

s = Starlark()

The globals keyword argument to the A {py:obj}starlark_go.Starlark constructor can be used to pass a dictionary containing some initial global variables:

from starlark_go import Starlark

s = Starlark(globals={"a": 1, "b": 3})

Evaluating code

{py:meth}starlark_go.Starlark.eval can be used to evaluate a Starlark expression:

from starlark_go import Starlark

s = Starlark()

s.eval("2 + 2") # 4

Starlark syntax is more-or-less identical to Python. Expressions can reference variables, just like you might in Python:

from starlark_go import Starlark

s = Starlark(globals={"a": 1, "b": 3})

s.eval("a + b") # 4

Defining variables and functions

{py:meth}starlark_go.Starlark.eval is only for evaluating expressions; if you want to define things in Starlark, you'll need to use {py:meth}starlark_go.Starlark.exec.

from starlark_go import Starlark

s = Starlark()

s.exec("a = 1")
s.exec("b = 3")
s.eval("a + b") # 4

There is no distinction between variables set by globals versus variables set by exec; it is simply another way to set a variable.

{py:meth}starlark_go.Starlark.exec can also be used to define functions in Starlark. Remember, Starlark's syntax is more-or-less identical to Python:

from starlark_go import Starlark

s = Starlark()

s.exec("""
def add_one(x):
  return x + 1
""")

s.eval("add_one(3)") # 4

Defining variables from Python

{py:meth}starlark_go.Starlark.set can be used to define one or more Starlark global variables:

from starlark_go import Starlark

s = Starlark()

s.set(a=1, b=3)

s.eval("a + b") # 4

There is no distinction between variables set by set versus other variables; it is simply another way to set a variable.

Retrieving variables

{py:meth}starlark_go.Starlark.get can be used to retrieve a Starlark global variable:

from starlark_go import Starlark

s = Starlark(globals={"b": 3, "c": True})

s.exec("a = 1")
s.set(d=[1, 2, 3])

s.get("a") # 1
s.get("b") # 3
s.get("c") # True
s.get("d") # [1, 2, 3]

A default value can be provided to {py:meth}starlark_go.Starlark.get; if one is not provided and the variable you are attempting to retrieve does not exist, a KeyError will be raised:

from starlark_go import Starlark

s = Starlark()

s.get("e") # !!! raises KeyError !!!
s.get("e", 72) # 72

Removing variables

{py:meth}starlark_go.Starlark.pop functions identically to {py:meth}starlark_go.Starlark.get, except that it removes the variable before returning its value:

from starlark_go import Starlark

s = Starlark(globals={"a": 1, "b": 2})

s.eval("a + b") # 4
s.pop("a") # 1
s.eval("a + b") # !!! raises ResolveError !!!

Overriding the print() function

By default, Starlark's print() function is routed to Python's built-in {py:func}python:print, but you can provide a different function to override it.

This can be done when you create the context:

import logging

from starlark_go import Starlark

s = Starlark(print=logging.warning)

...or after it is created:

import logging

from starlark_go import Starlark

s = Starlark()
s.print = logging.warning

...or for individual calls to {py:meth}starlark_go.Starlark.eval and {py:meth}starlark_go.Starlark.exec:

import logging

from starlark_go import Starlark

s = Starlark()
s.exec('print("hello!")', print=logging.warning)