Добавляем Starlark в приложение на Go

Что за птица?

Starlark (ранее известный как Skylark) — питоноподобный язык, изначально разработанный для системы сборки Bazel, со временем выбравшийся за её пределы через интерпретаторы для Go и Rust.

Язык располагает к использованию в роли инструмента конфигурации, однако, благодаря хорошо написанному интерпретатору на Go и детальному описанию спецификации, его можно использовать в виде встроенного в приложение языка программирования — например, когда вы хотите дать пользователю повзаимодействовать с объектом логики приложения, но не хотите постоянно плодить сущности под почти одинаковые кейсы через сотню настроечных параметров (мой случай).

Достаточно полных туториалов в процессе работы у меня найти не удалось, поэтому появилась идея написать небольшой материал по этой теме. В статье пройдемся по работе с Starlark в Go, от простейшего запуска скрипта до добавления нового встроенного типа.

Начиная с малого

Для начала работы достаточно сделать две вещи — написать исходник скрипта и выполнить его:

# hello.star print("Hello from Starlark script")

// main.go package main  import "go.starlark.net/starlark"  func main() { _, err := starlark.ExecFile(&starlark.Thread{}, "hello.star", nil, nil) if err != nil { panic(err) } }

ExecFile загружает исходный файл (или исходный код, если третий аргумент функции не nil), парсит и выполняет код в указанном треде, после чего возвращает словарь с объектами глобальной области видимости скрипта — переменными, функциями. Глобальная область видимости замораживается, что означает, что любые попытки изменения глобальных определений будут вызывать ошибку выполнения.

Запускаем, получаем:

$ go run main.go Hello from Starlark script

Хорошее начало, однако, пользы от этого мало — всё дело в том, что скрипт стоит рассматривать не как отдельную программу, а как встраиваемый модуль, функции которого мы собираемся вызывать по необходимости.

Попробуем иначе:

# hello.star def hello():     print("Hello from Starlark script")

Повторно запускаем код на Go и… ничего не происходит (ожидаемо), поскольку мы лишь объявили функцию, но не обратились к ней. А значит, нужно вызвать её из основной программы:

// main.go package main  import "go.starlark.net/starlark"  func main() {     // выделим поток, в котором будем загружать и выполнять скрипт     thread := &starlark.Thread{} globals, err := starlark.ExecFile(thread, "hello.star", nil, nil) if err != nil { panic(err) }  _, err = starlark.Call(thread, globals["hello"], nil, nil) if err != nil { panic(err) } }

Результат:

$ go run main.go Hello from Starlark script

globals это тот самый упомянутый ранее словарь с глобальными переменными и функциями. Через Call мы вызываем нашу функцию hello() по имени, получая её из словаря. Третьим и четвертым аргументом в функцию можно передать позиционные и именованные аргументы.

Передаем и получаем значения

«Из коробки» Starlark имеет одиннадцать встроенных типов (и ещё несколько из доступных модулей, но сейчас не о них):

• None, аналог nil, используемый тогда, когда нужно выразить отсутствие значения

• Boolean, логическое True или False

• Integer, целое число, тип объединяет знаковые и беззнаковые целые числа

• Float, число с плавающей точкой

• String, строка в UTF-8

• List, лист, изменяемая последовательность значений

• Tuple, кортеж, как лист, только неизменяемый (но содержащиеся в кортеже значения можно изменять)

• Dictionary, словарь «ключ-значение», в качестве ключей поддерживаются только хэшируемые типы

• Set, множество, под капотом использует хэш-таблицу, поэтому требование к значениям то же, что к ключам в словаре; Go-специфичный тип, использование которого требует установки специального флага

• Function, функции, определенные в коде Starlark

• Built-in function, отдельный тип для функций (или методов, о чём позже) реализованных в Go

Со стороны Go все типы обязаны реализовывать интерфейс Value, не считая специфичных для типов интерфейсов, таких как Callable для функций — эта информация пригодится при написании собственных типов.

Итак, попробуем передать что-нибудь в нашу функцию:

# hello.star def hello(message):     print(message)

// main.go package main  import "go.starlark.net/starlark"  func main() { thread := &starlark.Thread{} globals, err := starlark.ExecFile(thread, "hello.star", nil, nil) if err != nil { panic(err) }  // здесь готовим позиционные аргументы для вызываемой функции args := starlark.Tuple{ starlark.String("Hello from Golang"), } _, err = starlark.Call(thread, globals["hello"], args, nil) if err != nil { panic(err) } }

Результат:

$ go run main.go Hello from Golang

Таким образом можно передавать любое разумное количество аргументов в вызываемую функцию. Стоит отметить, что попытка передачи большего или меньшего числа аргументов является ошибкой времени выполнения скрипта — если задали в сигнатуре три аргумента, три и передаём.

Попробуем получить что-то из нашей функции. Напишем сложение чисел в качестве простейшего примера:

# hello.star def sum(x, y):     return x + y

// main.go package main  import "go.starlark.net/starlark"  func main() { thread := &starlark.Thread{} globals, err := starlark.ExecFile(thread, "hello.star", nil, nil) if err != nil { panic(err) }      // здесь готовим позиционные аргументы для вызываемой функции args := starlark.Tuple{ starlark.MakeInt(42), starlark.MakeInt(451), } result, err := starlark.Call(thread, globals["sum"], args, nil) if err != nil { panic(err) } print(result.String()) // распечатаем результат }

Запускаем:

$ go run main.go 493

В переменной reslut хранится какой-то результат вызванной функции. Сейчас получить значение вышло переводом Value в строку, однако в реальном использовании понадобится выполнить приведение интерфейса к нужному типу. В качестве примера:

func toGoValue(starValue starlark.Value) (any, error) { switch v := starValue.(type) { case starlark.String: return string(v), nil case starlark.Bool: return bool(v), nil case starlark.Int: // int, uint both here if value, ok := v.Int64(); ok { return value, nil }  if value, ok := v.Uint64(); ok { return value, nil }  return nil, errors.New("unknown starlark Int representation") case starlark.Float: return float64(v), nil case *starlark.List: slice := []any{} iter := v.Iterate()         defer iter.Done() var starValue starlark.Value for iter.Next(&starValue) { goValue, err := toGoValue(starValue) if err != nil { return nil, err } slice = append(slice, goValue) } return slice, nil case *starlark.Dict: datamap := make(map[string]any, v.Len()) for _, starKey := range v.Keys() { goKey, ok := starKey.(starlark.String) if !ok { // datamap key must be a string return nil, fmt.Errorf("datamap key must be a string, got %v", starKey.String()) }  // since the search is based on a known key,  // it is expected that the value will always be found starValue, _, _ := v.Get(starKey) goValue, err := toGoValue(starValue) if err != nil { return nil, err }  datamap[goKey.String()] = goValue } return datamap, nil default: return nil, fmt.Errorf("%v is not representable as datamap value", starValue.Type()) } }

Небольшое замечание: в приведенном выше коде стоит обратить внимание на работу с итератором — когда он больше не нужен, требуется явно вызывать Done().

Добавляем новый тип

Интерпретатор Starlark позволяет расширять язык, добавляя новые типы — достаточно реализовать интерфейс Value.

Представим, что у нас есть тип, пусть это будет пользователь, пример синтетический:

type User struct { name string mail *mail.Address }  // конструктор пригодится позже func NewUser(name, address string) (*User, error) { mail, err := mail.ParseAddress(address) if err != nil { return nil, err }  if len(name) == 0 { return nil, errors.New("name required") }  return &User{name: name, mail: mail}, nil }  func (u *User) Rename(newName string) { u.name = newName }  func (u *User) ChangeMail(newMail string) error { mail, err := mail.ParseAddress(newMail) if err != nil { return err } u.mail = mail return nil }  func (u *User) Name() string { return u.name }  func (u *User) Mail() string { return u.mail.String() }

и мы хотим сделать его доступным в Starlark. Для этого понадобится тип-обёртка с соответствующими методами:

var _ starlark.Value = &StarlarkUser{}  type StarlarkUser struct { user *User }  func (e *StarlarkUser) String() string { return fmt.Sprintf("name: %v, mail: %v", e.user.Name(), e.user.Mail()) }  func (e *StarlarkUser) Type() string { return "user" }  // для упрощения, не будем заморачиваться с реализацией методов ниже func (e *StarlarkUser) Freeze() {}  func (e *StarlarkUser) Truth() starlark.Bool { return len(e.user.Name()) > 0 && len(e.user.Mail()) > 0 }  func (e *StarlarkUser) Hash() (uint32, error) { return 0, errors.New("not hashable") }

МетодыString() , Type() и Truth() нужны для использования типа в встроенных в язык функциях str(), type() и bool() (помимо этого, второй несёт информацию о типе), Hash() используется для хэширования значения для использования в хэш-мапе в словарях и сетах, а Freeze() нужен для замораживания объекта (как видно, гарантия неизменяемости объекта после замораживания глобальной области видимости лежит целиком на реализации типа).

Такой тип уже можно как-то использовать, попробуем:

# user.star def user_info(user):     print(type(user)) # напечатает тип     print(user)       # напечатает строковое представление объекта

args := starlark.Tuple{ &StarlarkUser{ &User{ name: "John",  mail: &mail.Address{ Name:    "John", Address: "John@gmail.com", }, }, }, } _, err = starlark.Call(thread, globals["user_info"], args, nil) if err != nil { panic(err) }

Результат:

user name: John, mail: "John" <John@gmail.com>

У нас получился полноценный тип, однако, с ним нельзя выполнять никаких операций — для их реализации нужно поддержать соответствующие интерфейсы, например, HasUnary, HasBinary и т.д., чего мы в рамках этой статьи делать конечно же не будем, а то текста и так уже много, а впереди ещё создание встроенных функций и методов.

Добавляем новую функцию

Тут как раз пригодится конструктор NewUser(). Встроенные функции реализуются через Builtin:

// тело функции func newUser(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) { var name, mail string if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 2, &name, &mail); err != nil { return starlark.None, err }  user, err := NewUser(name, mail) if err != nil { return starlark.None, err }  return &StarlarkUser{user: user}, nil }  func main() { thread := &starlark.Thread{}     // собираем наши встраиваемые функции, которые затем передаются в ExecFile() builtins := starlark.StringDict{ "newUser": starlark.NewBuiltin("newUser", newUser), }  globals, err := starlark.ExecFile(thread, "user.star", nil, builtins) if err != nil { panic(err) }  _, err = starlark.Call(thread, globals["user_info"], nil, nil) if err != nil { panic(err) } }

Появилось несколько новых вещей. Во-первых, встраиваемые функции должны соответствовать типу func(thread *starlark.Thread, fn *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error).

Во-вторых, встраиваемые функции, а точнее, все предопределенные объекты, собираются в словарь и передаются в ExecFile(), чтобы сделать их доступными для кода Starlark.

В-третьих, для распаковки аргументов можно использовать UnpackPositionalArgs — в ней будут выполнены проверки количества и типов переданных аргументов.

Пробуем вызвать:

# user.star def user_info():     user = newUser("John", "john@gmail.com")      print(type(user))     print(user) 

$ go run main.go user name: John, mail: <john@gmail.com>

Работает! Стоит отметить, что таким образом можно передавать не только функции, но и любые другие объекты, тип которых реализует Value — например, можно передать заранее собранный набор констант, которые могут пригодиться в встраиваемом коде.

Добавляем методы

Добавление «методов» к кастомным объектам реализуется схожим образом, через Buitlin, при этом, тип, имеющий методы, должен реализовывать интерфейс HasAttrs.

Но сначала подготовим наши методы:

func userName(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) { if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 0); err != nil { return starlark.None, err }      // получаем ресивер, приводим к нужному типу и работаем уже с ним name := b.Receiver().(*StarlarkUser).user.Name()  return starlark.String(name), nil }  func userRename(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) { var name string if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 1, &name); err != nil { return starlark.None, err }  b.Receiver().(*StarlarkUser).user.Rename(name)  return starlark.None, nil }

Механика работы методов отличается от функций тем, что из передаваемого Builtin извлекается ресивер, приводится к нужному типу, после чего над ним выполняются необходимые манипуляции.

Поглядывая на реализацию встроенных типов в библиотеке интерпретатора, собираем наши методы в словарь:

var userMethods = map[string]*starlark.Builtin{ "name":   starlark.NewBuiltin("name", userName), "rename": starlark.NewBuiltin("rename", userRename), }

И реализуем HasAttrs:

func (e *StarlarkUser) Attr(name string) (starlark.Value, error) { b, ok := userMethods[name] if !ok { return nil, nil // нет такого метода } return b.BindReceiver(e), nil }  func (e *StarlarkUser) AttrNames() []string { names := make([]string, 0, len(userMethods)) for name := range userMethods { names = append(names, name) } sort.Strings(names) return names }

BindReceiver() создает новый Builtin, который несет в себе переданное значение, к которому мы получаем доступ в методе.

Пробуем:

# user.star def user_info():     user = newUser("John", "john@gmail.com")      user.rename("Jim")     print(user.name())

$ go run main.go Jim

Вот таким не очень хитрым образом у нас получилось добавить методы к нашему кастомному типу.

Бонус: модули, встроенные и пользовательские

У Starlark есть несколько встроенных модулей, которые могут быть полезными, вот некоторые из них:

• math — модуль с математическими функциями и парой констант

• time — функции и типы для работы с временем

Для загрузки модулей есть специальная функция load, однако просто так её использовать не выйдет — загрузка модулей выполняется функцией Load() в потоке, и по умолчанию её нет, а значит, нужно её реализовать. Расширим наш изначальный поток:

import ( "go.starlark.net/lib/math" "go.starlark.net/lib/time" )  thread := &starlark.Thread{ Load: func(thread *starlark.Thread, module string) (starlark.StringDict, error) { switch module { case "math.star": return starlark.StringDict{ "math": math.Module, }, nil case "time.star": return starlark.StringDict{ "time": time.Module, }, nil default: return nil, fmt.Errorf("no such module: %v", module) } }, }

Функция будет вызываться на каждый load() в коде. Попробуем вывести текущее время:

# modules.star load("time.star", "time")  print(time.now()) # выведет текущее время

Второй (и последующие) аргументы load() определяют импортируемые литералы, при этом, начинающиеся с _ не импортируются. В случае реализованных на Go модулей импортируется структура, через поля которой мы и обращаемся к функциям и константам.

Можно писать модули и на Starlark, а для удобства воспользоваться расширением starlarkstruct, чтобы работа с нашим кастомным модулем не отличалась от работы с встроенными:

builtins := starlark.StringDict{     "newUser": starlark.NewBuiltin("newUser", newUser),     "struct":  starlark.NewBuiltin("struct", starlarkstruct.Make), }

Поддержим загрузку файлов в функции загрузки модулей:

thread := &starlark.Thread{ Load: func(thread *starlark.Thread, module string) (starlark.StringDict, error) { switch module { case "math.star": return starlark.StringDict{ "math": math.Module, }, nil case "time.star": return starlark.StringDict{ "time": time.Module, }, nil default: // внешний модуль, загружаем из файла script, err := os.ReadFile(module) if err != nil { return nil, err }  entries, err := starlark.ExecFile(thread, module, script, builtins) if err != nil { return nil, err }  return entries, nil } }, }

Определим модуль:

# myModule.star def hello():     print("hello from module")  # создаем структуру с экспортируемыми литералами myModule = struct(     hello = hello )

И воспользуемся им в основном коде:

load("myModule.star", "myModule")  myModule.hello() # выведет hello from module

Благодаря тому, что мы определили в модуле одноименную структуру с литералами, модуль очень просто импортируется и используется.

Заключение

В моём случае встраивание Starlark в приложение позволило дать пользователям инструмент для гибкой конфигурации и добавления кастомной логики в некоторые контролируемые этапы с работы событиями. Буду рад, если этот материал окажется полезен и вам, а Starlark, возможно, займёт достойное место в вашем коде.