API

Slicing

The Novem slicing instruction is modelled on the python array slicing notation, but expanded with a few quality of life enhancements. The goal of slicing is to provide an easy way to subdivide a table for applying styles and formatting.

In addition for the primary slicing function, we also allow the user to supply a comma separated list of indices starting at zero (negative indices are also supported).

The novem slicing syntax is created to operate on sub-sections of tables. To achieve this we need two slices, one for rows and one for columns. These two slicers together is called a selector.

Any styles using selectors will only be applied on the union of the slices.

N.B. Please be aware that slicing instructions cannot contain any spaces.
The slicing operation consists of one or more integers separated by a colon :. The first number denotes the starting position (counting from zero), the second the ending position and the third the step (how many items to skip). The integer values can be skipped to indicate start or end of a range.

0
Start index

Zero based index on where to start, if left empty the slice will start at index 0 (start of row/column).

A comma separated list of indices can be supplied instead, but then the remainder of the instruction must be removed.

:
Position separator
Splits up the start and end sections.
-1
End index

Which index to stop at. This can be an explicit value (5) or relative value from the end of the range (-5). If this element is not specified, the slice defaults to the last element of the range.

N.B. The last element of a range is -1.

:
Step separator
Splits of the end and step sections.
2
Step value

This value indicates how many steps to take between each value, by default a step of 1 is assumed, selecting every element.

A step of 2 would thus select every other element, and so on.

For a complete selector, a slice is specified twice, once for rows and once for columns. The instructions are separated with a space.

Below are a few examples of selectors along with some explanations.

-- select all rows and all columns
  :     :

-- select first row and all columns
 0      :

-- select last row and all columns
-1      :

-- select first three rows
 0:2    :   -- we use 2 ans that's the third element in a zero index

-- select last three rows
-1:-4   :

-- select a 3x3 matrix in the top left corner of the table
 0:2   0:2
  :2    :2  -- the zero is implied if omitted

-- select every other row in the table
  ::2   :

-- select the first and last row
0,-1    :

-- select row 4,5,6
3,4,5   :   -- remember zero index

Play around with a live demo of the slicer syntax:

Below are a couple of examples showing how the slicer selection can be used to apply different styles to a novem table.

This example shows a static color pattern reminiscent of a picnic blanket using three shades of blue and setting the background color.

We use four selectors and leverage the step instruction. First color alternating rows starting at different offsets, then add alternating columns. The selectors are applied in order, so later entries take precedence.

text/config/colors/colors
-- Create a "picnic blanket" using 4 shades of blue
::2  :  bg sta blue-100   -- color every other row starting at 0
1::2 :  bg sta blue-200   -- color every other row starting at 1
1::2 1::2 bg sta blue-300 -- color every other col starting at row 1 col 1
::2  1::2 bg sta blue-200 -- color every other row starting at row 0 col 1

Here we highlight a hierarchical structure in our table by coloring rows in descending shades of gray. This is a common strategy when wanting to preserve space.

Unlike in the picnic example above, here we explicitly choose which entries to highlight with a comma-separated list of rows.

text/config/colors/colors
-- Color rows by "hierarchy"
1 : bg sta gray-500           -- world
2,5,8 : bg sta gray-400       -- region 1
3,6,9,12,19 : bg sta gray-300 -- region 2
Next
Terminology