Forge logoforge/v0.4

// docs

Learn ForgeScript.

A short, hands-on tour. Copy each snippet into the playground or run it locally with forgescript run file.fs.

// 01

Hello, ForgeScript

ForgeScript is a tiny language for data work. Programs read top to bottom — each step takes a table and returns a new one.

# this is a comment
load "iris" as df
df |> head(3)

Three things to notice: # starts a comment, load … as binds a dataset to a name, and |> pipes a value into the next call.

// 02

Load data

load reads a built-in dataset, a CSV file, or a URL. The result is a dataframe.

load "iris"  as df          # built-in
load "sales" as s           # built-in
load "data/orders.csv" as o # local file (CLI only)

In the browser playground, only the built-in datasets are available. The CLI can read any local CSV.

// 03

The pipe operator

|> takes the value on its left and passes it as the first argument to the call on its right. It reads naturally, top to bottom.

# without the pipe
head(sort(filter(df, species == "setosa"), :sepal_length), 5)

# with the pipe — same thing, easier to read
df
  |> filter(species == "setosa")
  |> sort(:sepal_length)
  |> head(5)

// 04

Filter & select

filter keeps rows that match a condition. select keeps only the columns you name (with the :name syntax).

load "iris" as df

df
  |> filter(species == "virginica" and petal_length > 5)
  |> select(:species, :petal_length, :petal_width)
  |> head(10)

Use and, or, not for boolean logic. Strings use double quotes.

// 05

Group & aggregate

group_by splits the table by a key. agg collapses each group into one row using aggregator functions like sum, mean, count, min, max.

load "sales" as s

s
  |> group_by(:region)
  |> agg(
       revenue = sum(:revenue),
       deals   = sum(:deals),
       avg     = mean(:revenue)
     )

// 06

Sort & peek

sort orders the table by a column. Pass desc = true for descending. head returns the first N rows.

load "sales" as s

s
  |> sort(:revenue, desc = true)
  |> head(5)

// 07

Train a model

ForgeScript treats models like any other value: train, evaluate, save.

load "iris" as df

let m = df
  |> drop_na()
  |> train(model = "random_forest", target = :species, trees = 200)

m |> save("models/iris.fm")

The model trainer is part of the CLI. The browser playground focuses on dataframe pipelines.

// 08

What's next

You know enough to be useful. From here: