Elements

Any text will parse as a valid sowhat record. The elements listed below add meaning and values to the record:

  • Pins: Pins provide an additional sequence to sort Records
  • Dates: The date the record pertains to (see below for more information about why this is not implied via file create time or some other meta-data source)
  • Folders: Describes where to file the record
  • Tasks: Indicates whether the record is something todo or something done
  • URLs: See the urlPattern for the exact Regex
  • Tags: Standard tagging organizational structure
  • Events: Just like a tag, but utilizes the date element to indicate that something happened at that time. In addition to marking a moment in time, events can include a continuation notation indicating the event spans a time range ending when a record dated in the future includes an event close token
  • Beans: Beans are meant to be counted, and so they must be, or they are not much use. They are like tags combined with a number used to increase or decrease the value of a symbol.
  • Formulas: Lisp-style equations that are able to reference the value of Beans and other Formulas
  • Words: words wonderful words, whatever words you like.

The following is an overview of all elements that can be included in a note.

<Pin>? <Date>? <Folder>? <Todo|Done>? < Word | URL | Tag | Event | Bean | Formula | Whitespace >*

Replace the <Element> with the element specifications below. ? after an element indicates the element is optional. * after an element indicates 0 or more of the preceding element(s).

The placement of Pins, Dates, Folders and Tasks is fixed. These four elements must conform to the following order:

<Pin>? <Date>:? <Folder>:? <Task>:?

Pins, Dates, Folders and Tasks are all optional.

Element Label

Folders, Tags, Events and Beans all include a Label portion, it matches quoted text or non-whitespace text.

Pins

An optional flag to add to the very beginning of a record, *1. The purpose of a Pin is to give the system a means to sort records with a sequence value other than Date.

The syntax of a Pin is an asterisk followed by 0-3 integers, giving 1000 possible pin positions. Must be pecified as the first element in a record.

*
*0
*999
*420

Dates

An optional date of the record can be specified as the first element. It must conform to the following format YYYY-MM-DD HH:MM:SS

Folders

A record can include one folder. It must follow the date element or be the first element of a record. Folders must be a / followed by the element label pattern

Folders may contain any number of nested folder segments.

If a folder is not specified it is assumed to be the top level folder.

Tasks

Task keywords, todo and done occur at the beginning of a record or follow a folder or date. The two elements are two aspects of the same concept -- they are meant to indicate whether the record is something to do or something that has been done!

The keywords can be capital or lowercase or a mix, it does not matter: todo, DONE, ToDo, dONe are all OK.

URLs

URLs identified in the record are parsed into a list for further processing. They can be included anywhere in the record except within another element.

The URL regex can be found here

Tags

A # character followed by the label pattern.

Events

Events indicate that something happened at a certain time. The time associated with an event is the date specified along with the record.

The name of the event must match the element label pattern of the element referenced above.

Point-in-time Events

Syntactically the same as a tag, but instead of a "#" they begin with a "!"

Beans

Beans are used to increase or decrease a value associated with a symbol (the label pattern of the Bean).

The syntax is:

<+|-><Label><:<Number>>?

The number portion is optional, and if ommitted will result in an increase or decrease of 1.

To increase a Bean value use a + sign

+cash:42

To decrease a Bean value use a - sign

-cash:42

The value is any number that matches the following regex (NOTE: it must be a positive number):

/([0-9]*\\.?[0-9]+|[0-9]+\\.?[0-9]*)([eE][+-]?[0-9]+)?/

Formulas

Formulas are used to calculate number values.

They use the following syntax

$$(<Label>)<S-Expression Formula Body>

Matching a formula is a collection of different patterns.

The formula name or <Label> must conform to the Element Label Pattern above

The Formula body uses a lisp style s-expression syntax. Any non-space sequence of characters up to 42 in total length registers as an operator.

Formulas are intended to use alongside Beans. Beans values could be referenced as arguments to other math functions or invoked as part of a custom function that looks up their value.

For more details see the /tap documentation on Formulas

Errors

Even though all text will parse as a valid record, an individual element may contain errors. Tap will highlight text it interprets as an error.