shithub: spread

ref: 1260c5c1735d5cf5a60890df7471bcd808b6231d
dir: /README.md/

Spreadsheet Editor

This program builds around hoc(1).


# Spreadsheet files

They are divided into two blocks, separated by a line containing three `%`:

1. hoc script. Loaded verbatim to hoc. Use this to add functionality.
2. cells and cell contents.

A sample file could look like this:

	func t(a) {
		print a
	}
	%%%
	A1=3
	A2;hello
	A3=5
	A4=A1()+A3()

The general syntax of cells should be quite obvious, but it's worth noting
that cells divided by an `=` sign will end up being calculation functions,
while cells divided by a `;` sign are string literals. Only calculation
functions (cells with `=`) will end up being hoc functions.

A newer version supports cell alignment by prepending the following chars
to the lines:

- `<`: left align (default if empty)
- `>`: right align
- `|`: center align
- `.`: dot align (not implemented yet)

These chars also work for entry lines.

# Usage

	spread [-di] [file]

- `file` will be loaded as a spreadsheet
- `-d` enables extra debug output
- `-i` opens spread in CLI mode (see below)

# Modes

## GUI mode

### Mouse control

- RMB click on a cell to edit it
- Math cells that refer to other empty math cells generate those
  cells automatically, with a default value of `0`. This will
  overwrite existing text cells!

### Keyboard control

- Use the arrow keys (←↑↓→) to scroll
- Use `q` or `DEL` to quit
- Every other key input [A-Za-z0-9] opens the command line

### Command line

- `w [file]` - save to file (without file: save to original file)
- `s addr` - open the edit dialog for cell addr (addr be like: B5)
- `gg` - go to A1
- `g addr` - go to addr. This scrolls so that addr is in the top left corner
- `m` - toggle math mode. Math mode displays non-math cells in a greyed out state

### Edit dialog

This is a simple text entry box for the specified cell.

- To enter a function, start the line with an `=` sign.
- To enter a string/text, don't start the line with an `=` sign.

Simple as that.

## CLI mode

For now, this opens a direct channel to hoc. All commands entered will
be forwarded to the hoc process unchanged.

Example session for previous example program:

	A4()
	→ 8
	A1()
	→ 3
	A1()*A3()
	→ 15
	A1()+2*A3()
	→ 13

# Macros

## Range support

Spread supports some level of ranges. The syntax looks like this:

	'[' CELL() op CELL() ']'
	op := any operation character that's supported by hoc (+-*/)
	CELL := any cell address (e. g. B12)

Spaces within this expression are not supported!

For example:

	A1() + [B1()+B3()] + 5

will be converted to (note that the range is enclosed in `()`):

	A1() + (B1()+B2()+B3()) + 5

This also allows more complex expressions like:

	A1() + [B1()*C10()] + [D1()+D10()]

Note that this expression contains multiple ranges, one range
exceeding a single column.

Note that his can also lead to extremely heavy performance impact
if you choose to do exponentiation with many cells.

# Open questions

## Bugs

Sure, there are many. Known issues are:

- Cyclic dependencies are not allowed, I added come rudimentary check
  that could leak some memory.