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]] ,

csv++ User Guide