Introduction

csv++ is a superset of CSV which aims to make spreadsheet authoring more akin to traditional software development with a compiler that can output to Excel, Google Sheets or CSV. That means you can edit your spreadsheet in plain text, share functions between various spreadsheets and commit your code to version control.

Installation

Just go to releases on github, download the latest release, unpack it and put it in your $PATH.

Installing From Source

To install from source check out the csv++ repository and run:

cargo install --path .

This assumes you've installed Rust

Google Sheets Setup

To publish to Google Sheets you will need to authenticate using the gcloud CLI tools. First you need to install the gcloud CLI and then run:

$ gcloud init
$ gcloud auth login --enable-gdrive-access --update-adc

Language Reference

While csv++ is a superset of CSV, it adds several features that we'll explore.

Re-usable functions and variables
A module-loading import system
The ability to specify cell-level options (text formatting, alignment, etc)
A fill feature that is akin to dragging the bottom-right of a cell in a spreadsheet.

File Structure

Each csv++ source code file contains two distinct parts: an optional code section and a CSV section.

Code Section

The code section is where variables and functions can be defined and subsequently used in the CSV section. It is terminated by the --- separator and anything following that will be treated as the CSV section.

Functions

Functions basically act as macros, where variables are interpolated but they are otherwise inserted into the spreadsheet without being evaluated. The language is a superset of the formula language used in spreadsheets - you should be able to do everything you can in a spreadsheet but also define functions and variables.

Functions are defined by:

fn <function-name> ( <arg1>, <arg2>, ... )

They can have any number of arguments and will be evaluated in the context of the cell in which they are called.

Examples

fn fees(quantity) 
  quantity * 0.10

fn profit(price, quantity) 
  (price * quantity) - fees(quantity)
---

Variables

Variables can be defined in the code section by giving a name (a combination of letters, numbers and underscores), the expression := and followed with a value:

<variable-name> := <expression>

To reference a variable you just use it by it's name - there is no special operator to dereference.

Examples

foo := 42
bar := foo * 2
---
=foo,=bar,

will evaluate to:

=42,=(42 * 2),

Cell References

You can use A1-style cell references in the code section and within function definitions. Since the syntax for variable references and for cell references are overlapping (for example ABC is both a valid cell reference and variable reference), csv++ will only interpolate the variable if it is defined. Otherwise it will be left alone and treated as a cell reference.

CSV Section

The CSV section defines the stucture of your spreadsheet and makes use of the functions and variables defined above.

Variables

An important feature of the CSV section is being able to assign variables to cells and reference them elsewhere. You do this using the [[var=<var-name>]] syntax:

profit := income - fee
---
[[var=fee]],    [[var=income]],     =profit,

which will evaluate to:

,,=(B1 - A1)

Row Variables

You can also assign a variable to reference an entire row using the row option syntax (![[/]]):

![[var=row_1]],,,

Fills

A common feature of spreadsheets is to drag the bottom right corner and that formula will be applied over a range of rows. The ![[fill=<number-of-rows>]] provides similar functionality.

![[fill=3]]foo,bar,baz,

evaluates to:

foo,bar,baz,
foo,bar,baz,
foo,bar,baz,

which is not very helpful but becomes interesting when you combine it with variables.

# fees are a fixed $2.00 per trade
fees := 2

fn profit(quantity, price_each)
  (price_each * quantity) - fees

---
![[fill=3]][[var=number_of_shares]],    [[var=price]],  "=profit(number_of_shares, price)",

becomes:

,,"=(B1 * A1) - 2",
,,"=(B2 * A2) - 2",
,,"=(B3 * A3) - 2",

A full list of cell & row options will be discussed in the Cell & Row Options section.

Comments

Any line in the CSV section will be treated as a comment and ignored if it starts with a #:

foo,bar,baz,
# this is a comment
foo1,bar1,baz1,

Multi-line Cells

When using lots of cell options the lines can get pretty long. To help with this you can split a single spreadsheet row over multiple lines using the \\ syntax like so:

---
![[halign=center \
  valign=top \
  text=bold \
  text=underline \
  ]] This,  Is, A,  Header, Row,
[[var=one]] , \
  [[var=two]] , \
  [[var=three]] , \
  [[var=four]] ,

which is equivalent to:

---
![[halign=center valign=top text=bold text=underline]] This,  Is, A,  Header, Row,
[[var=one]] , [[var=two]] , [[var=three]] , [[var=four]] ,

Modules

Modules are the basic building block of making reusable spreadsheets. Module names are derived from the name of the file - so for example if you have foo.csvpp, it's module name is foo.

Requiring Modules

If you want to re-use variables or functions from another file, you can just import that module:

`foo.csvpp`

my_constant := 42
---

`bar.csvpp`

use foo

fn my_fn(a) a * my_constant
---
[[var=a]],=my_fn(a),

Currently when importing a module, all of the variables

The Main Module

Similar to C/Java/Rust etc, csv++ requires that there is a "main" module. This is generally implicit as the file being compiled without a need to specify it. Only the spreadsheet section of the main module will be built - for any required/non-main modules the spreadsheet section will be ignored and only the code section brought into scope.

Variable Scoping

The variable scoping semantics are pretty unique because every function call is evaluated relative to the cell where it is used. As you've seen so far you can use [[var=...]] to bind a variable name to a given cell. As an example of scoping semantics we'll use this csv++ template:

foo_from_code_section := 42
---
[[var=bar_outside_fill]]    ,,,,,
![[fill=2]]bar              , \
  [[var=bar_in_fill]]       , \
  =bar_in_fill              , \
  =bar_outside_fill         , \
  =foo_from_code_section    ,

which will compile to:

     ,     ,     ,     ,
bar  ,     , =B2 , =A1 , =42
bar  ,     , =B3 , =A1 , =42

Breaking this down:

foo_from_code_section - Is always 42 no matter where it is used.
bar_in_fill - Since it is defined within an ![[fill]], it's value depends on the final row, which will be B2 or B3
bar_outside_fill - Will always be A1, pointing to the cell where it was defined. There is no relative aspect to it since it's not defined in an fill.

Cell & Row Options

Options

You can change the formatting of a cell or row, bind cells to variables, apply validation, change alignment, etc. All of the normal rules of CSV apply with the addition that each cell can have options specified in [[/]] for cells and ![[/]] for rows:

foo,[[...]]bar,baz

specifying formatting or various other options to the cell. Additionally a row can start with:

![[...]]foo,bar,baz

which will apply to all cells in the row.

All Options

border = all | top | bottom | left | right

Sets a border on the given side (or all four sides if all). Can be repeated multiple times to set multiple borders.

csv++ User Guide