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.