golars scripting language (.glr)

.glr files are a tiny, line-oriented language for pipeline-style DataFrame work. Designed to feel like "your REPL session in a file", nothing more. Every REPL command you know is also a script statement.

# trades-daily.glr
load data/trades.csv          as trades
load data/symbols.csv         as symbols

use trades
filter volume > 100
groupby symbol amount:sum:total
join symbols on symbol
sort total desc
limit 10
show

Run it:

golars run trades-daily.glr       # one-shot

From inside the REPL:

golars » .source trades-daily.glr

Grammar

program      = { statement NL } ;
statement    = empty
             | comment
             | command ;
comment      = "#" { any-char-until-NL } ;
command      = [ "." ] identifier { arg } ;
arg          = identifier | number | string | operator | list | "as" | "on" ;
list         = "[" [ arg { "," arg } ] "]" ;
string       = '"' { any-char } '"' ;
identifier   = ( letter | "_" ) { letter | digit | "_" | "." | "-" | "/" | ":" } ;
number       = [ "-" ] digit { digit } [ "." digit { digit } ] ;
operator     = "==" | "!=" | "<=" | ">=" | "<" | ">" | "and" | "or" ;

That is the statement level. filter, with, select and groupby hand the rest of the line to the expression language.

Statements are line-terminated. A trailing \ (after any trailing whitespace) continues onto the next physical line, useful for long filter predicates:

filter salary > 100000 \
  and dept == "eng" \
  and tenure_years >= 2

The leading . on every command is optional: load foo.csv and .load foo.csv do the same thing. A # inside a "..." string is treated as a literal - only unquoted # starts a comment.

If you mis-spell a command golars tries to be helpful:

$ golars run typo.glr
typo.glr:3: unknown command "filtet" (did you mean "filter"?)

Statement reference

Commands are grouped the way .help prints them. The canonical list, with signatures and hover text, lives in script/spec.go; the REPL, the LSP, the Jupyter kernel and the editor grammars all read from it. Aliases are listed next to the command they stand for.

Three kinds of statement behave differently:

• Pipeline statements add a lazy step to the focused frame. Nothing runs until something collects (show, head, save, ...).
• Reshape statements have no lazy form. They collect the focus, transform it, and make the result the new focus.
• Inspect and aggregate statements print something and leave the focus unchanged.

io

Without as NAME a scan replaces the focus and the file is opened when the pipeline is collected. With as NAME the scan is collected and staged, like load PATH as NAME.

frames

pipeline (lazy)

reshape (replaces the focus)

inspect

aggregate

plan

session

Expression language

with, filter, select and the name=expr form of groupby share one expression language. It reaches the golars expression API directly: every method on expr.Expr and on its namespaces is callable by its snake_case name, so new library functions show up in glr without parser changes.

Grammar

expr     := orExpr
orExpr   := andExpr ("or" andExpr)*
andExpr  := notExpr ("and" notExpr)*
notExpr  := "not" notExpr | cmpExpr
cmpExpr  := addExpr ( cmpOp addExpr | "is_null" | "is_not_null"
                    | strOp addExpr | ["not"] "in" list )?
cmpOp    := "==" | "!=" | "<" | "<=" | ">" | ">="
strOp    := "contains" | "starts_with" | "ends_with" | "like" | "not_like"
addExpr  := mulExpr (("+" | "-") mulExpr)*
mulExpr  := unary (("*" | "/" | "//" | "%") unary)*
unary    := "-" unary | power
power    := postfix ("**" unary)?
postfix  := primary ("." [ns "."] ident [args])*
primary  := literal | list | "(" expr ")" | when
          | ns "." ident args | ident args | ident
when     := "when" orExpr "then" orExpr ("when" orExpr "then" orExpr)*
            ("otherwise" orExpr)?
args     := "(" [arg ("," arg)*] ")"
arg      := ident "=" expr | expr
list     := "[" [expr ("," expr)*] "]"
ns       := "str" | "dt" | "list" | "arr" | "struct" | "name" | "bin" | "cat"

Bare identifiers are columns; col("my col") reaches names with spaces or odd characters. Keywords (and, or, not, in, when, ...) are case-insensitive.

Operators

Calls

Every function has two equivalent spellings: a method on the value, or a call whose first argument is the value.

with r1 = x.round(2)             # same as round(x, 2)
with y1 = ts.dt.year()           # same as dt.year(ts)
with n1 = str.len_chars(name)    # same as name.str.len_chars()

• Namespaces: str, dt, list, arr, struct, name, bin, cat, matching Expr.Str(), Expr.Dt(), and so on. A column whose name is also a namespace (such as name) still works as a column: name.str.upper() is the column name.
• Lists are written [a, b]: cut(x, [0, 10]), x in ["a", "b"], replace(x, [1, 2], [10, 20]).
• Keyword arguments set options, as in polars: cut(x, [0, 10], labels=["lo", "mid", "hi"], left_closed=true), replace_strict(x, [1, 2], ["a", "b"], default="other"), str.to_date(s, "%d/%m/%Y", strict=false), rolling_mean_by(x, ts, "7d", min_periods=1), concat_str(a, b, separator="-").
• Defaults follow polars where they exist: shift(x) shifts by 1, round(x) rounds to 0 places, rank(x) is average, date_range(a, b) steps one day.
• Parentheses are optional for calls without arguments: price.sum.
• sum("x") (a quoted name) aggregates the column x, for compatibility with older scripts.

Common functions

Functions that take a Go callback (map_batches, map_elements, fold) are not reachable from glr; use Go for those.

Examples

with signed_up = str.to_date(signup, "%d/%m/%Y")
with tenure_d  = dt.total_days(dt.date(ts) - signed_up)
with slot      = dt.strftime(dt.truncate(ts, "30m"), "%H:%M")
with ntags     = list.len(str.split(tags, ";"))
with size      = cut(amount, [20, 100], labels=["small", "medium", "large"])
with bucket    = amount // 50 * 50
with parity    = when amount % 2 == 0 then "even" otherwise "odd"
with trend     = amount.rolling_mean(7, 1)
with score     = coalesce(primary, backup).str.trim()

Predicates

filter takes any boolean expression. The classic clause forms read naturally, and binds tighter than or, and parentheses group:

filter age >= 21 and salary > 50000
filter symbol == "AAPL"
filter is_active and created_at > 1704067200000000
filter note is_null
filter name like "a%" or name contains "z"
filter dept in ["eng", "ops"] and not (age < 21)
filter dt.year(ts) == 2024 and str.len_chars(name) > 3

A bare boolean column is a predicate on its own: filter is_active. String values are double- or single-quoted.

Multi-source workflows

Scripts regularly need N frames. The as NAME / use NAME / .frames trio is the whole story: there's no hidden namespace:

# Stage every input up front. None of these promote themselves to
# focus, so we can read them in any order.
load data/trades.csv    as trades
load data/symbols.csv   as symbols
load data/users.csv     as users

# Work on one, stash it, work on the next.
use trades
filter volume > 100
groupby user_id amount:sum:total_bought
stash trade_totals

# `use` is non-consuming: trade_totals stays staged, and so does the
# original trades frame: we could `use trades` again to branch off a
# different filter.
use users
filter region == "US"
join trade_totals on user_id
join symbols on symbol
sort total_bought desc
show

stash is the "save into a variable" move: it materializes whatever lazy pipeline is on the focus and parks a copy under NAME so later use NAME gives you that snapshot. The focus itself keeps going from the snapshot, so the idiomatic branching pattern is:

load data/trades.csv
filter volume > 100
stash base

filter side == "buy"
stash buys

use base
filter side == "sell"
stash sells

use buys
join sells on symbol

When .join sees a name that exists in the frame registry, it consumes that frame (keeping it in the registry for reuse) instead of treating the argument as a path. Paths win only when no frame matches.

Anonymous load PATH

The short form load PATH (no as) is equivalent to use NAME where NAME is empty. It's the "single-frame script" ergonomic:

load data/trades.csv
filter volume > 100
show

No registry, no juggling: just pipe.

Transpile to Go

golars transpile SCRIPT.glr [-o OUT.go] [--package NAME] emits a standalone Go program that reproduces the pipeline through the lazy API. The generated source is piped through go/format and has its imports pruned by go/ast, so the output is always gofmt'd and free of unused imports.

golars transpile examples/script/pipeline.glr -o main.go --package main
go run main.go

Mapping:

Expressions are lowered to the same expr calls a hand-written program would use (dt.year(ts) becomes expr.Col("ts").Dt().Year()). REPL-only commands (.tree, .graph, .mermaid, .frames, ...) are skipped and listed in a header comment; other commands without a lowering emit a TODO(glr): comment so the file still compiles. If no show / head / collect / save appears in the script, transpile adds an implicit final Collect + fmt.Println so the generated binary prints something instead of exiting silently.

See examples/script/transpiled/ for a transpiled copy of every bundled .glr example.

Interop with code

Anything that implements script.Executor can host the language. cmd/golars is the reference, but the package ships a generic runner:

import "github.com/Gaurav-Gosain/golars/script"

r := script.Runner{
    Exec:  script.ExecutorFunc(func(line string) error { /* … */ return nil }),
    Trace: func(line string) { fmt.Println(">", line) },
    ContinueOnErr: true,
    ErrOut: os.Stderr,
}
if err := r.RunFile("pipeline.glr"); err != nil {
    log.Fatal(err)
}

• Trace receives every normalised statement just before execution.
• ContinueOnErr + ErrOut emits errors inline and keeps running.
• script.Normalize(raw) is exported so third parties can apply the same parsing rules (comment stripping, leading . insertion).

Editor support

Tree-sitter grammar + highlight queries live at editors/tree-sitter-golars/. Install notes for Neovim (nvim-treesitter) and VS Code in that directory's README.

LSP

cmd/golars-lsp is a minimal Language Server that ships:

• Inline completions for commands, staged-frame names, file paths, and column names read from loaded CSV files.
• Inlay hints showing each pipeline step's output shape - → 5 rows × 3 cols appears at the end of every shape-changing statement. Row counts propagate as upper bounds: limit N clamps to N, left joins preserve the left side's count, filters and inner joins mark rows ?.
• Hover docs with signature + long description on any command token.
• Diagnostics for unknown commands and files that don't resolve.

# ^? probe: live table previews

Drop # ^? on its own line anywhere in a script and the Neovim plugin renders the focused frame's current table as virtual text below the comment (via a golars --preview subprocess). This is the scripting equivalent of Twoslash/Quokka probes: a live peek at the data at that pipeline position:

load data/trades.csv
filter volume > 100
sort amount desc
limit 5
# ^?

The preview updates on save + debounced text changes; configure via require("golars").setup({ preview_cmd = { "/path/to/golars" }, preview_rows = 20, preview_timeout_ms = 3000 }). Set preview = false to disable.

golars --preview <path>

Invoke the preview pipeline from any editor, or manually via:

golars --preview path/to/script.glr
golars --preview path/to/script.glr --preview-rows 25

Runs the script silently (no banner, no trace, no success chrome) and prints exactly one rendered table: the focused pipeline's head. Exit code 0 on success, non-zero on script error (message on stderr).

What this language is NOT

• No variables beyond the named-frame registry. If you need branching or reusable expressions, write a Go program that drives script.Runner with your own logic.
• No control flow (no if, no loops). The idiom for conditional runs is shell scripting around golars run, or a Go host with an Executor that dispatches.
• No user-defined functions. with NAME = EXPR covers derived columns; anything beyond that belongs in Go, where the full expression API is available.

The design target is "drop a day of REPL work into a file and have it run again tomorrow." Everything else is out of scope.