1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<!-- This file is the project homepage at github.com/google/starlark -->
# Starlark in Go
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 and is currently in transition
to the new name. We will use this as an opportunity to make some
breaking API changes. The import path for the Go packages will
eventually be `go.starlark.net/starlark`, but it does not work yet.
Please continue to import the old Skylark names for now.*
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/starlark/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/github.com/google/starlark](https://godoc.org/github.com/google/starlark)
* Mailing list: [starlark-go](https://groups.google.com/forum/#!forum/starlark-go)
* Issue tracker: [https://github.com/google/starlark/issues](https://github.com/google/starlark/issues)
* Travis CI:  [https://travis-ci.org/google/starlark](https://travis-ci.org/google/starlark)
### Getting started
Build the code:
```shell
$ go get github.com/google/starlark/...
$ go build github.com/google/starlark/cmd/starlark
```
Run the interpreter:
```
$ 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):
```
$ ./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.
### 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 used by Bazel.
For that reason, proposals to change the language itself should
generally be directed to the Bazel team, 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.
Now that the project's long-term name ("Starlark") has been decided,
we plan to copy this repository to github.com/google/starlark and
change the canonical import path for all packages to starlark.net/starlark.
The current github.com/google/starlark repository will be frozen.
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) 2017 The Bazel Authors.
All rights reserved.
It is provided under a 3-clause BSD license:
[LICENSE](https://github.com/google/starlark/blob/master/LICENSE).
The name "Starlark" is a code name of the Bazel project.
The Bazel team plans to rename the language to "Starlark" to reflect its
applicability to projects unrelated to Bazel.
Starlark in Go is not an official Google product.
|
