csvpp 0.5.0

Compile csvpp source code to a target spreadsheet format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

[![crates.io](https://img.shields.io/crates/v/csvpp.svg)](https://crates.io/crates/csvpp)
[![github workflow](https://github.com/patrickomatic/csv-plus-plus/actions/workflows/rust.yml/badge.svg)](https://github.com/patrickomatic/csv-plus-plus/actions)
[![dependency status](https://deps.rs/repo/github/patrickomatic/csv-plus-plus/status.svg)](https://deps.rs/repo/github/patrickomatic/csv-plus-plus)
[![codecov](https://codecov.io/github/patrickomatic/csv-plus-plus/graph/badge.svg?token=RWNEXNQT91)](https://codecov.io/github/patrickomatic/csv-plus-plus)

# csv++

csv++ is a superset of [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) which allows
you to author spreadsheets in a text file then compile that to your target spreadsheet (Excel, 
Google Sheets or even back to CSV).

Since csv++ is a superset of CSV any CSV document is valid:

```csvpp
Sum,Column 1,Column 2,
=5*SUM(B2,C2),,,
```

However you can extract reusable variables and functions by making a code section at the top, 
separated from the cells with a `---`.  Here's the same spreadsheet but extracted out into
variables and functions:

```csvpp
# you can define variables with `:=`
multiplier := 5

# functions look like this and have a single expression as their body
fn my_fn(a, b)
  multiplier * SUM(a, b)

---
Sum                 , Column 1, Column 2,
"=my_fn(B2, C2)"    ,         ,         ,
```

One more useful feature is the ability to bind variables to a cell.  You can use the `[[`/`]]`
syntax on the cell you want to bind it on.

```csvpp
fn my_complex_fn(a, b)
  a * a + SQRT(b)

---
Complex function      , Column 1  , Column 2 ,
"=my_complex_fn(a, b)", [[var=a]] , [[var=b]],
```


## Fills

Another useful feature is to define a range of rows which fill out (either infinitely or by a
finite amount) in the compiled spreadsheet.  To specify one you use the row-option syntax
which is similar to above, you just prefix it with `!`: `![[`/`]]`.

```csvpp
Product Name  , Quantity          , Price per Unit  , =SUM(D2:D12)
![[fill=10]]  , [[var=quantity]]  , [[var=price]]   , =quantity * price
```

This will take the second row and repeat it 10 times in the final spreadsheet.  If you wanted 
it to be repeated until the end of the spreadsheet just leave off the `=10` and specify it as 
`![[fill]]`.


## 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 above 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:

```csvpp
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:

```csv
     ,     ,     ,     ,
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`.


## Importing Code

csv++ allows you to import and re-use functions and variables with the `use` statement:

#### `my_math_constants.csvpp`
```csvpp
pi := 3.14159
e := 2.7182818284
---
```

#### `main.csvpp`
```csvpp
use my_math_constants

fn circumference_from_diameter(r)
    r * 2 * pi

fn radius_to_diameter(r)
    2 * r

fn circumference_from_radius(r)
    radius_from_diameter(radius_to_diameter(r))

---
Radius          ,Circumference                           ,
[[var=radius]]  ,"=circumference_from_radius(radius)"    ,
```

## Formatting

You can apply basic cell formatting which will either apply for the entire row or just for 
individual cells.  To apply formatting to individual cells use the `[[`/`]]` syntax:

```csvpp
[[text=bold/text=underline]]foo,[[fontsize=20]]bar,baz,
```

and here is the same thing using short-hand:

```csvpp
[[t=b/t=u]]foo,[[fs=20]]bar,baz,
```

To format the entire row you can use `![[`/`]]` at the beginning of the line

```csvpp
![[t=b/t=u]]foo,bar,baz,
```

For a full list of formatting features, take a look at the [language reference](docs/LANGUAGE_REFERENCE.md)

### Additional Reading

* [Installation](docs/INSTALL.md)
* [Language Reference](docs/LANGUAGE_REFERENCE.md)
* [Examples](https://github.com/patrickomatic/csvpp-examples)
* [Changelog](docs/CHANGELOG.md)
* [Want to Contribute?](docs/CONTRIBUTING.md)
* [csvpp on crates.io](https://crates.io/crates/csvpp)