go.starlark.net@v0.0.0-20231101134539-556fd59b42f6/README.md (about)

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