sdg.man

.\" Man page for SDGScript. View with:  man ./sdg.man
.TH SDG 1 "2026-07-16" "SDGScript 0.1" "SDGScript Manual"
.SH NAME
sdg \- SDGScript, the sustainable programming language
.SH SYNOPSIS
.B sdg
.I run
.I file.sdg
.RB [ --report ]
.br
.B sdg
.I repl
.br
.B sdg
.I version
.SH DESCRIPTION
.B sdg
is the interpreter for SDGScript, a small language with a sustainability theme
whose keywords carry real behaviour. Programs are read,
parsed, and evaluated by a tree-walking interpreter that meters the work it
does so it can print a sustainability report.
.PP
The defining rule is that nothing should be wasted: a binding that is grown but
never consumed halts the program with a waste error. Pure functions are marked
.B renewable
and their results are recycled (memoized). Blocks may be given an op
.B budget
that fails if overspent.
.SH COMMANDS
.TP
.B run \fIfile.sdg\fR [--report]
Execute a program. With
.B --report
a sustainability summary is printed after the run, listing ops evaluated,
allocations, values reported, recycled (memoized) results, an estimated CO2e
figure, and a renewability score.
.TP
.B repl
Start an interactive session. Waste checking is relaxed so partial snippets do
not error. The sustainability report is printed on exit.
.TP
.B version
Print the version banner.
.SH LANGUAGE
.SS Bindings
.TP
.B grow \fIname\fR = \fIexpr\fR
Declare (plant) a new binding. If it is never read, the run ends with a waste
error.
.TP
.B \fIname\fR = \fIexpr\fR
Reassign an existing binding. Reassigning a binding that was never grown is an
error.
.SS Functions
.TP
.B fn(\fIparams\fR) { ... }
An ordinary function.
.TP
.B renewable fn(\fIparams\fR) { ... }
A pure function. It may not perform I/O (no
.BR report )
and may not mutate bindings from an enclosing scope. Because its output depends
only on its input, results are memoized and reused on repeated calls.
.TP
.B harvest \fIexpr\fR
Return a value from a function.
.SS Control flow
.TP
.B sustain \fIx\fR in \fIiterable\fR { ... }
Iterate over an array, binding each element to
.IR x .
.TP
.B if (\fIcond\fR) { ... } else { ... }
Conditional. May be used as an expression.
.TP
.B budget \fIN\fR ops { ... }
Run a block under a cap of
.I N
evaluation steps. Exceeding the cap raises a budget error. The word
.B ops
is optional and only there to read well.
.SS Output
.TP
.B report \fIexpr\fR
Print a value and feed the sustainability meter. Not permitted inside a
renewable function.
.SS Builtins
.TP
.B len(\fIx\fR)
Length of an array or string.
.TP
.B range(\fIn\fR)
The array [0, 1, ... n-1].
.TP
.B push(\fIarr\fR, \fIv\fR)
Return a new array with
.I v
appended. The original is not mutated.
.TP
.B str(\fIx\fR)
Convert a value to its string form.
.SH EXAMPLES
.PP
A footprint calculator whose repeated inputs are recycled:
.PP
.RS
.nf
grow footprint = renewable fn(km) {
    harvest km * 0.12
}
grow trips = [10, 20, 10, 20, 10]
grow total = 0.0
sustain t in trips {
    total = total + footprint(t)
}
report total
.fi
.RE
.PP
Run it with a report:
.PP
.RS
.nf
sdg run examples/footprint.sdg --report
.fi
.RE
.SH DIAGNOSTICS
.TP
.B waste error
A binding was grown but never consumed.
.TP
.B renewable error
A renewable function attempted I/O or mutated external state.
.TP
.B budget error
A budgeted block exceeded its allotted ops.
.SH EXIT STATUS
.B sdg
exits 0 on success and 1 on a parse error or a runtime error.
.SH SEE ALSO
The project README for the philosophy and roadmap.
.SH AUTHORS
The SDGScript project.