github.com/k14s/starlark-go@v0.0.0-20200720175618-3a5c849cc368/README.md (about) 1 2 <!-- This file is the project homepage for go.starlark.net --> 3 4 # Starlark in Go 5 6 This is the home of the _Starlark in Go_ project. 7 Starlark in Go is an interpreter for Starlark, implemented in Go. 8 Starlark was formerly known as Skylark. 9 The new import path for Go packages is `"github.com/k14s/starlark-go/starlark"`. 10 11 Starlark is a dialect of Python intended for use as a configuration language. 12 Like Python, it is an untyped dynamic language with high-level data 13 types, first-class functions with lexical scope, and garbage collection. 14 Unlike CPython, independent Starlark threads execute in parallel, so 15 Starlark workloads scale well on parallel machines. 16 Starlark is a small and simple language with a familiar and highly 17 readable syntax. You can use it as an expressive notation for 18 structured data, defining functions to eliminate repetition, or you 19 can use it to add scripting capabilities to an existing application. 20 21 A Starlark interpreter is typically embedded within a larger 22 application, and the application may define additional domain-specific 23 functions and data types beyond those provided by the core language. 24 For example, Starlark was originally developed for the 25 [Bazel build tool](https://bazel.build). 26 Bazel uses Starlark as the notation both for its BUILD files (like 27 Makefiles, these declare the executables, libraries, and tests in a 28 directory) and for [its macro 29 language](https://docs.bazel.build/versions/master/skylark/language.html), 30 through which Bazel is extended with custom logic to support new 31 languages and compilers. 32 33 34 ## Documentation 35 36 * Language definition: [doc/spec.md](doc/spec.md) 37 38 * About the Go implementation: [doc/impl.md](doc/impl.md) 39 40 * API documentation: [godoc.org/go.starlark.net/starlark](https://godoc.org/go.starlark.net/starlark) 41 42 * Mailing list: [starlark-go](https://groups.google.com/forum/#!forum/starlark-go) 43 44 * Issue tracker: [https://github.com/google/starlark-go/issues](https://github.com/google/starlark-go/issues) 45 46 * Travis CI: [![Travis CI](https://travis-ci.org/google/starlark-go.svg) https://travis-ci.org/google/starlark-go](https://travis-ci.org/google/starlark-go) 47 48 ### Getting started 49 50 Build the code: 51 52 ```shell 53 # check out the code and dependencies, 54 # and install interpreter in $GOPATH/bin 55 $ go get -u go.starlark.net/cmd/starlark 56 ``` 57 58 Run the interpreter: 59 60 ``` 61 $ cat coins.star 62 coins = { 63 'dime': 10, 64 'nickel': 5, 65 'penny': 1, 66 'quarter': 25, 67 } 68 print('By name:\t' + ', '.join(sorted(coins.keys()))) 69 print('By value:\t' + ', '.join(sorted(coins.keys(), key=coins.get))) 70 71 $ starlark coins.star 72 By name: dime, nickel, penny, quarter 73 By value: penny, nickel, dime, quarter 74 ``` 75 76 Interact with the read-eval-print loop (REPL): 77 78 ``` 79 $ starlark 80 >>> def fibonacci(n): 81 ... res = list(range(n)) 82 ... for i in res[2:]: 83 ... res[i] = res[i-2] + res[i-1] 84 ... return res 85 ... 86 >>> fibonacci(10) 87 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 88 >>> 89 ``` 90 91 When you have finished, type `Ctrl-D` to close the REPL's input stream. 92 93 Embed the interpreter in your Go program: 94 95 ``` 96 import "github.com/k14s/starlark-go/starlark" 97 98 // Execute Starlark program in a file. 99 thread := &starlark.Thread{Name: "my thread"} 100 globals, err := starlark.ExecFile(thread, "fibonacci.star", nil, nil) 101 if err != nil { ... } 102 103 // Retrieve a module global. 104 fibonacci := globals["fibonacci"] 105 106 // Call Starlark function from Go. 107 v, err := starlark.Call(thread, fibonacci, starlark.Tuple{starlark.MakeInt(10)}, nil) 108 if err != nil { ... } 109 fmt.Printf("fibonacci(10) = %v\n", v) // fibonacci(10) = [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 110 ``` 111 112 See [starlark/example_test.go](starlark/example_test.go) for more examples. 113 114 ### Contributing 115 116 We welcome submissions but please let us know what you're working on 117 if you want to change or add to the Starlark repository. 118 119 Before undertaking to write something new for the Starlark project, 120 please file an issue or claim an existing issue. 121 All significant changes to the language or to the interpreter's Go 122 API must be discussed before they can be accepted. 123 This gives all participants a chance to validate the design and to 124 avoid duplication of effort. 125 126 Despite some differences, the Go implementation of Starlark strives to 127 match the behavior of [the Java implementation](https://github.com/bazelbuild/bazel) 128 used by Bazel and maintained by the Bazel team. 129 For that reason, proposals to change the language itself should 130 generally be directed to [the Starlark site]( 131 https://github.com/bazelbuild/starlark/), not to the maintainers of this 132 project. 133 Only once there is consensus that a language change is desirable may 134 its Go implementation proceed. 135 136 We use GitHub pull requests for contributions. 137 138 Please complete Google's contributor license agreement (CLA) before 139 sending your first change to the project. If you are the copyright 140 holder, you will need to agree to the 141 [individual contributor license agreement](https://cla.developers.google.com/about/google-individual), 142 which can be completed online. 143 If your organization is the copyright holder, the organization will 144 need to agree to the [corporate contributor license agreement](https://cla.developers.google.com/about/google-corporate). 145 If the copyright holder for your contribution has already completed 146 the agreement in connection with another Google open source project, 147 it does not need to be completed again. 148 149 ### Stability 150 151 We reserve the right to make breaking language and API changes at this 152 stage in the project, although we will endeavor to keep them to a minimum. 153 Once the Bazel team has finalized the version 1 language specification, 154 we will be more rigorous with interface stability. 155 156 ### Credits 157 158 Starlark was designed and implemented in Java by 159 Ulf Adams, 160 Lukács Berki, 161 Jon Brandvein, 162 John Field, 163 Laurent Le Brun, 164 Dmitry Lomov, 165 Damien Martin-Guillerez, 166 Vladimir Moskva, and 167 Florian Weikert, 168 standing on the shoulders of the Python community. 169 The Go implementation was written by Alan Donovan and Jay Conrod; 170 its scanner was derived from one written by Russ Cox. 171 172 ### Legal 173 174 Starlark in Go is Copyright (c) 2018 The Bazel Authors. 175 All rights reserved. 176 177 It is provided under a 3-clause BSD license: 178 [LICENSE](https://github.com/google/starlark-go/blob/master/LICENSE). 179 180 Starlark in Go is not an official Google product.