NAME

sheett - a terminal spreadsheet

SYNOPSIS

sheett [-s KEY=VAL] [...] input.sheett

DESCRIPTION

Sheett is a tool to output "pages" of text to a terminal, replacing visual areas (cells) with the results of calculations.

The file format is a utf-8 encoded LF-separated file containing any number of CELL DECLARATIONS followed by a line starting with "@@@", followed by a name ending with "@@@", and followed by a PAGE.

Blank lines are ignored.

For example, here's a file which shows the area and circumference of a circle, given a specific radius:

radius: 25
area: () => (Math.PI * radius ** 2).toFixed(2)
circumference: () => {
  const circ = 2 * Math.PI * radius;
  return circ.toFixed(2);
}

@@@ main @@@
Given a circle with radius <<radius>>:
- The area is <<area>> units squared
- The circumference is <<circumference>> units

CELL DECLARATIONS

A cell declaration is a valid JavaScript identifier followed by a colon : and any number of whitespace characters, followed by the cell's value.

The cell's value may have a number of prefixes, which give the cell special meaning:

• () => it is a calculation that is parsed as a JavaScript arrow function.
• (future) @, it evaluates to the value provided as a required CLI -s parameter
• <, it evaluates to the contents of the file at the following path.
• (future) ! it evaluates to the standard output of executing the following shell script.
• Valid JSON is loaded and parsed as JSON (i.e. double-quoted string literals, arrays, objects, boolean values, null, and numbers)

PAGE

A page is just a bunch of static text which gets output to the terminal as-is with "cells" that are replaced with their contents.

A "cell" is any portion of a line separated by two character delimiters -- the outer delimiter is the width indicator, and the inner deliminator is the height indicator

• [[ and ]] make a fixed-width, fixed-height cell
• (future) <[ and ]> make a dynamic-width, fixed-height cell
• (future) [< and >] make a fixed-width, dynamic-height cell (how does dynamic-height work?)
• (future) << and >> make a dynamic-width, dynamic-height cell

Between each delimiter is the declaration name that is bound to the cell itself.

If multiple lines have cells of the exact same width and declaration name, it is used as the height of fixed-height cell or the minimum height of dynamic-height cells.