You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
182 lines
6.2 KiB
182 lines
6.2 KiB
|
|
<!-- This file is the project homepage for go.starlark.net -->
|
|
|
|
# Starlark in Go
|
|
|
|
[](https://travis-ci.org/google/starlark-go)
|
|
[](https://godoc.org/go.starlark.net/starlark)
|
|
|
|
This is the home of the _Starlark in Go_ project.
|
|
Starlark in Go is an interpreter for Starlark, implemented in Go.
|
|
Starlark was formerly known as Skylark.
|
|
The new import path for Go packages is `"go.starlark.net/starlark"`.
|
|
|
|
Starlark is a dialect of Python intended for use as a configuration language.
|
|
Like Python, it is an untyped dynamic language with high-level data
|
|
types, first-class functions with lexical scope, and garbage collection.
|
|
Unlike CPython, independent Starlark threads execute in parallel, so
|
|
Starlark workloads scale well on parallel machines.
|
|
Starlark is a small and simple language with a familiar and highly
|
|
readable syntax. You can use it as an expressive notation for
|
|
structured data, defining functions to eliminate repetition, or you
|
|
can use it to add scripting capabilities to an existing application.
|
|
|
|
A Starlark interpreter is typically embedded within a larger
|
|
application, and the application may define additional domain-specific
|
|
functions and data types beyond those provided by the core language.
|
|
For example, Starlark was originally developed for the
|
|
[Bazel build tool](https://bazel.build).
|
|
Bazel uses Starlark as the notation both for its BUILD files (like
|
|
Makefiles, these declare the executables, libraries, and tests in a
|
|
directory) and for [its macro
|
|
language](https://docs.bazel.build/versions/master/skylark/language.html),
|
|
through which Bazel is extended with custom logic to support new
|
|
languages and compilers.
|
|
|
|
|
|
## Documentation
|
|
|
|
* Language definition: [doc/spec.md](doc/spec.md)
|
|
|
|
* About the Go implementation: [doc/impl.md](doc/impl.md)
|
|
|
|
* API documentation: [godoc.org/go.starlark.net/starlark](https://godoc.org/go.starlark.net/starlark)
|
|
|
|
* Mailing list: [starlark-go](https://groups.google.com/forum/#!forum/starlark-go)
|
|
|
|
* Issue tracker: [https://github.com/google/starlark-go/issues](https://github.com/google/starlark-go/issues)
|
|
|
|
### Getting started
|
|
|
|
Build the code:
|
|
|
|
```shell
|
|
# check out the code and dependencies,
|
|
# and install interpreter in $GOPATH/bin
|
|
$ go get -u go.starlark.net/cmd/starlark
|
|
```
|
|
|
|
Run the interpreter:
|
|
|
|
```console
|
|
$ cat coins.star
|
|
coins = {
|
|
'dime': 10,
|
|
'nickel': 5,
|
|
'penny': 1,
|
|
'quarter': 25,
|
|
}
|
|
print('By name:\t' + ', '.join(sorted(coins.keys())))
|
|
print('By value:\t' + ', '.join(sorted(coins.keys(), key=coins.get)))
|
|
|
|
$ starlark coins.star
|
|
By name: dime, nickel, penny, quarter
|
|
By value: penny, nickel, dime, quarter
|
|
```
|
|
|
|
Interact with the read-eval-print loop (REPL):
|
|
|
|
```pycon
|
|
$ starlark
|
|
>>> def fibonacci(n):
|
|
... res = list(range(n))
|
|
... for i in res[2:]:
|
|
... res[i] = res[i-2] + res[i-1]
|
|
... return res
|
|
...
|
|
>>> fibonacci(10)
|
|
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
|
|
>>>
|
|
```
|
|
|
|
When you have finished, type `Ctrl-D` to close the REPL's input stream.
|
|
|
|
Embed the interpreter in your Go program:
|
|
|
|
```go
|
|
import "go.starlark.net/starlark"
|
|
|
|
// Execute Starlark program in a file.
|
|
thread := &starlark.Thread{Name: "my thread"}
|
|
globals, err := starlark.ExecFile(thread, "fibonacci.star", nil, nil)
|
|
if err != nil { ... }
|
|
|
|
// Retrieve a module global.
|
|
fibonacci := globals["fibonacci"]
|
|
|
|
// Call Starlark function from Go.
|
|
v, err := starlark.Call(thread, fibonacci, starlark.Tuple{starlark.MakeInt(10)}, nil)
|
|
if err != nil { ... }
|
|
fmt.Printf("fibonacci(10) = %v\n", v) // fibonacci(10) = [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
|
|
```
|
|
|
|
See [starlark/example_test.go](starlark/example_test.go) for more examples.
|
|
|
|
### Contributing
|
|
|
|
We welcome submissions but please let us know what you're working on
|
|
if you want to change or add to the Starlark repository.
|
|
|
|
Before undertaking to write something new for the Starlark project,
|
|
please file an issue or claim an existing issue.
|
|
All significant changes to the language or to the interpreter's Go
|
|
API must be discussed before they can be accepted.
|
|
This gives all participants a chance to validate the design and to
|
|
avoid duplication of effort.
|
|
|
|
Despite some differences, the Go implementation of Starlark strives to
|
|
match the behavior of [the Java implementation](https://github.com/bazelbuild/bazel)
|
|
used by Bazel and maintained by the Bazel team.
|
|
For that reason, proposals to change the language itself should
|
|
generally be directed to [the Starlark site](
|
|
https://github.com/bazelbuild/starlark/), not to the maintainers of this
|
|
project.
|
|
Only once there is consensus that a language change is desirable may
|
|
its Go implementation proceed.
|
|
|
|
We use GitHub pull requests for contributions.
|
|
|
|
Please complete Google's contributor license agreement (CLA) before
|
|
sending your first change to the project. If you are the copyright
|
|
holder, you will need to agree to the
|
|
[individual contributor license agreement](https://cla.developers.google.com/about/google-individual),
|
|
which can be completed online.
|
|
If your organization is the copyright holder, the organization will
|
|
need to agree to the [corporate contributor license agreement](https://cla.developers.google.com/about/google-corporate).
|
|
If the copyright holder for your contribution has already completed
|
|
the agreement in connection with another Google open source project,
|
|
it does not need to be completed again.
|
|
|
|
### Stability
|
|
|
|
We reserve the right to make breaking language and API changes at this
|
|
stage in the project, although we will endeavor to keep them to a minimum.
|
|
Once the Bazel team has finalized the version 1 language specification,
|
|
we will be more rigorous with interface stability.
|
|
|
|
### Credits
|
|
|
|
Starlark was designed and implemented in Java by
|
|
Ulf Adams,
|
|
Lukács Berki,
|
|
Jon Brandvein,
|
|
John Field,
|
|
Laurent Le Brun,
|
|
Dmitry Lomov,
|
|
Damien Martin-Guillerez,
|
|
Vladimir Moskva, and
|
|
Florian Weikert,
|
|
standing on the shoulders of the Python community.
|
|
The Go implementation was written by Alan Donovan and Jay Conrod;
|
|
its scanner was derived from one written by Russ Cox.
|
|
|
|
### Legal
|
|
|
|
Starlark in Go is Copyright (c) 2018 The Bazel Authors.
|
|
All rights reserved.
|
|
|
|
It is provided under a 3-clause BSD license:
|
|
[LICENSE](https://github.com/google/starlark-go/blob/master/LICENSE).
|
|
|
|
Starlark in Go is not an official Google product.
|