|
6 | 6 | [](https://codeclimate.com/github/1set/starlet/maintainability) |
7 | 7 | [](https://goreportcard.com/report/github.com/1set/starlet) |
8 | 8 |
|
9 | | -Enhancing your Starlark scripting experience with powerful extensions and enriched wrappers. Start your Starlark journey with Starlet, where simplicity meets functionality. |
| 9 | +> Enhancing your Starlark scripting experience with powerful extensions and enriched wrappers. Start your Starlark journey with Starlet, where simplicity meets functionality. |
10 | 10 |
|
11 | | -> :warning: **Under Active Development**: Please note that this library is currently under active development. As a result, the API may undergo significant changes in the future. Use at your own risk, or consider waiting until a more stable release before using it in production. |
| 11 | +*Starlet* is yet another Go wrapper for the official [*Starlark in Go*](https://github.com/google/starlark-go) project, designed to enhance the Starlark scripting experience with powerful extensions and enriched wrappers, and provide a more user-friendly and powerful interface for embedding Starlark scripting in your Go applications. |
12 | 12 |
|
13 | | -Explore the capabilities of the Starlet command-line tool efficiently by installing it using the command below: |
| 13 | +Inspired by the [*Starlight*](https://github.com/starlight-go/starlight) and [*Starlib*](https://github.com/qri-io/starlib) projects, *Starlet* focuses on three main objectives: providing an easier-to-use **Go wrapper** for Starlark, offering flexible **data conversion** between Go and Starlark, and supplying a set of **useful libraries** for Starlark. |
| 14 | + |
| 15 | +## Key Features |
| 16 | + |
| 17 | +*Starlet* provides the following key features: |
| 18 | + |
| 19 | +### Flexible Machine Abstraction |
| 20 | + |
| 21 | +*Starlet* introduces a streamlined interface for executing Starlark scripts, encapsulating the complexities of setting up and running the scripts: The [`Machine`](https://pkg.go.dev/github.com/1set/starlet#Machine) type serves as a comprehensive wrapper for Starlark runtime environments, offering an intuitive API for executing Starlark scripts, managing global variables, loading modules, controlling the script execution flow., and handling script outputs. |
| 22 | + |
| 23 | +### Enhanced Data Conversion |
| 24 | + |
| 25 | +*Starlet* offers the [`dataconv`](https://pkg.go.dev/github.com/1set/starlet/dataconv) package that simplifies the data exchange between Go and Starlark types. Unlike *Starlight*, which wraps Go values in Starlark-friendly structures, it focuses on transforming Go values into their Starlark equivalents and vice versa. This allows for a more seamless integration of Go's rich data types into Starlark scripts. |
| 26 | + |
| 27 | +### Extended Libraries & Functionalities |
| 28 | + |
| 29 | +*Starlet* includes a set of custom modules and libraries that extend the functionality of the Starlark language. These modules cover a wide range of use cases, such as file manipulation, HTTP client, JSON/CSV handling, and more, making Starlark scripts even more powerful and versatile. |
| 30 | + |
| 31 | +## Libraries |
| 32 | + |
| 33 | +*Starlet* comes with a set of libraries to extend the standard Starlark library. Here's a brief overview: |
| 34 | + |
| 35 | +| Package | Go Doc | Description | |
| 36 | +|:----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------| |
| 37 | +| [`atom`](/lib/atom) | [](https://pkg.go.dev/github.com/1set/starlet/lib/atom) | Atomic operations for integers, floats, and strings | |
| 38 | +| [`base64`](/lib/base64) | [](https://pkg.go.dev/github.com/1set/starlet/lib/base64) | Base64 encoding & decoding functions | |
| 39 | +| [`csv`](/lib/csv) | [](https://pkg.go.dev/github.com/1set/starlet/lib/csv) | Parses and writes comma-separated values (csv) contents | |
| 40 | +| [`file`](/lib/file) | [](https://pkg.go.dev/github.com/1set/starlet/lib/file) | Functions to interact with the file system | |
| 41 | +| [`goidiomatic`](/lib/goidiomatic) | [](https://pkg.go.dev/github.com/1set/starlet/lib/goidiomatic) | Go idiomatic functions and values for Starlark | |
| 42 | +| [`hashlib`](/lib/hashlib) | [](https://pkg.go.dev/github.com/1set/starlet/lib/hashlib) | Hash primitives for Starlark | |
| 43 | +| [`http`](/lib/http) | [](https://pkg.go.dev/github.com/1set/starlet/lib/http) | HTTP client and server handler implementation for Starlark | |
| 44 | +| [`json`](/lib/json) | [](https://pkg.go.dev/github.com/1set/starlet/lib/json) | Utilities for converting Starlark values to/from JSON strings | |
| 45 | +| [`log`](/lib/log) | [](https://pkg.go.dev/github.com/1set/starlet/lib/log) | Functionality for logging messages at various severity levels | |
| 46 | +| [`path`](/lib/path) | [](https://pkg.go.dev/github.com/1set/starlet/lib/path) | Functions to manipulate directories and file paths | |
| 47 | +| [`random`](/lib/random) | [](https://pkg.go.dev/github.com/1set/starlet/lib/random) | Functions to generate random values for various distributions | |
| 48 | +| [`re`](/lib/re) | [](https://pkg.go.dev/github.com/1set/starlet/lib/re) | Regular expression functions for Starlark | |
| 49 | +| [`runtime`](/lib/runtime) | [](https://pkg.go.dev/github.com/1set/starlet/lib/runtime) | Provides Go and app runtime information | |
| 50 | +| [`string`](/lib/string) | [](https://pkg.go.dev/github.com/1set/starlet/lib/string) | Constants and functions to manipulate strings | |
| 51 | + |
| 52 | +For extensive documentation on each library, please refer to the respective README files in the [`lib`](/lib) directory. Additionally, *Starlet* includes an array of official modules. You can explore all provided modules by using [`GetAllBuiltinModuleNames()`](https://pkg.go.dev/github.com/1set/starlet#GetAllBuiltinModuleNames) method. |
| 53 | + |
| 54 | +## Installation |
| 55 | + |
| 56 | +To install *Starlet*, use the following Go command under your project directory: |
| 57 | + |
| 58 | +```bash |
| 59 | +go get github.com/1set/starlet |
| 60 | +``` |
| 61 | + |
| 62 | +To explore the capabilities of the Starlet CLI tool, use the command below to install: |
14 | 63 |
|
15 | 64 | ```bash |
16 | | -go install -v github.com/1set/starlet/cmd/starlet@latest |
| 65 | +go install github.com/1set/starlet/cmd/starlet@latest |
17 | 66 | ``` |
18 | 67 |
|
| 68 | +## Usage |
| 69 | + |
| 70 | +You can use *Starlet* to enhance your Starlark scripting experience. Here's a quick example: |
| 71 | + |
| 72 | +```go |
| 73 | +import "github.com/1set/starlet" |
| 74 | + |
| 75 | +// Define your machine with global variables and modules |
| 76 | +globals := starlet.StringAnyMap{ |
| 77 | + "greet": func(name string) string { |
| 78 | + return fmt.Sprintf("Hello, %s!", name) |
| 79 | + }, |
| 80 | +} |
| 81 | +mac := starlet.NewWithNames(globals, []string{"random"}, nil) |
| 82 | + |
| 83 | +// Run a Starlark script in the machine |
| 84 | +script := ` |
| 85 | +target = random.choice(["World", "Starlark", "Starlet"]) |
| 86 | +text = greet(target) |
| 87 | +print("Starlark:", text) |
| 88 | +` |
| 89 | +res, err := mac.RunScript([]byte(script), nil) |
| 90 | + |
| 91 | +// Check for errors and results |
| 92 | +if err != nil { |
| 93 | + fmt.Println("Error executing script:", err) |
| 94 | + return |
| 95 | +} |
| 96 | +fmt.Println("Go:", res["text"].(string)) |
| 97 | +fmt.Println("Modules:", starlet.GetAllBuiltinModuleNames()) |
| 98 | +``` |
| 99 | + |
| 100 | +This may output: |
| 101 | + |
| 102 | +``` |
| 103 | +Starlark: Hello, Starlet! |
| 104 | +Go: Hello, Starlet! |
| 105 | +Modules: [atom base64 csv file go_idiomatic hashlib http json log math path random re runtime string struct time] |
| 106 | +``` |
| 107 | + |
| 108 | +## Contributing |
| 109 | + |
| 110 | +Contributions to *Starlet* are all welcomed. If you encounter any issues or have suggestions for improvements, please feel free to open an issue or submit a pull request. Before undertaking any significant changes, please let us know by filing an issue or claiming an existing one to ensure there is no duplication of effort. |
| 111 | + |
| 112 | +## License |
| 113 | + |
| 114 | +*Starlet* is licensed under the [MIT License](LICENSE). |
| 115 | + |
| 116 | +## Credits |
| 117 | + |
| 118 | +*Starlet* is inspired by two projects: |
| 119 | + |
| 120 | +1. [Starlight](https://github.com/starlight-go/starlight): A Go wrapper and data conversion tool between Go and Starlark. |
| 121 | +2. [Starlib](https://github.com/qri-io/starlib): A collection of third-party libraries for Starlark. |
| 122 | + |
| 123 | +We appreciate the work done by the creators and contributors of these projects. Their efforts have paved the way for the development of *Starlet*. Special thanks to the authors and contributors of these projects! 🎉 |
0 commit comments