calculang 💬

only for calculations ⇔ numbers ⇔ workings

calculang doesn’t ‘do things’ (“side-effects”) like regular programming languages 💥

This serves to simplify, permitting the aims above for calculations, numbers, and their workings ✅️

portable 💨

calculang models compile to highly-portable Javascript modules. Besides private usecases, outputs such as numbers and visualizations can be placed directly in a blog post you read ¹, in a dashboard for your teams metrics, in your banking app, and so on.

formulas as building blocks 🧱

In calculang, formulas are the building blocks of calculations. Formulas are “pure functions” for mathematics or FP audience; for everyone else: they’re just like spreadsheet formulas.

calculang formulas are flexible ♻️: not only can they be re-used, they can be re-used with specified changes: specified at the formula-level.

calculang facilitates transparency at the same formula-level (because formulas are exported as a rule).

versus spreadsheets

In calculang, layout and presentation is separated from calculation logic: and there can be many of these.
Every formula is given a name, so that there is no need to debate v or hlookups vs. index-match 🤯
Flexible formulas and modularity allow us to give more meaningful and maintainable structure to many common patterns we create in spreadsheets.
calculang models are “code” and as such can integrate readily with state-of-the-art tools and practices around auditability, version control and testing and development.

tools 🧰

A calculang introspection API makes it convenient to build tools (even environments) that interact with calculang models and their formulas in meaningful ways.

It includes all of the information needed to transpile from calculang source into Javascript output; and more besides.

introspection output 📜

every calculang formula
- their source locations
- and their input dependencies
every calculang call within calculang code
- and their source locations
all calculang relationships (links)
information about source files, calculang scopes², and how they are related through the module graph

There is some documentation here, but you can also see introspection outputs using this experimental tool.

visualization APIs & calcudata

One calculang tool is calcuvizspec: a visualization API that uses Vega-Lite to map model features (formulas and inputs) directly to visual marks.

A presentation including some examples is here (toggle Code blocks).

This API exists due to a need model developers have: they must be able to very quickly see numbers from a model, and iterate the model and outputs quickly during the development process.

A separate API: calcuvegadata, is more efficient for development- or finalised- model outputs which respond to interactivity.

calcudata is a convenient lower-level API for querying numbers.

These APIs include a notion about a cursor: representing inputs where a single value is provided, and domains: representing inputs where a range of values are provided (and their cross-product is used).

These are opinionated APIs: none of which are prescribed. Different opinions about patterns to use models are encouraged!