Smos

A comprehensive self-management system

Pieces of a Smos File

A Smos file is a YAML document, for example:

- entry:
    header: Use Smos
    timestamps:
      DEADLINE: 2018-10-30
      SCHEDULED: 2018-10-20
    state-history:
    - state: STARTED
      time: 2020-05-04 17:40:04.522146420000
    tags:
    - online
  forest:
  - header: Don't mess it up
    state-history:
    - state: DONE
      time: 2020-05-04 17:40:18.177282440000
    - state: NEXT
      time: 2020-05-04 17:40:17.225761141000
  - header: Be smart about it
    state-history:
    - state: TODO
      time: 2020-05-04 17:40:25.881089668000
    tags:
    - work

It consists of a forest of entries.

Forests of trees

A forest is a list of trees. It is parsed as a yaml list:

- <tree>

A tree is parsed as an entry with a subforest:

entry: <entry>
forest: <forest>

If a tree has no subforest, then it can be represented as just an entry:

<entry>

Entry

An entry consists of

  • A header
  • Contents (optionally)
  • Timestamps (optionally)
  • Properties (optionally)
  • Its state and state history (optionally)
  • Tags (optionally)
  • A clock logbook (optionally)

Example

contents: https://github.com/NorfairKing/smos/issues/53
logbook:
- start: 2020-05-09 01:31:40.000000000000
- start: 2020-05-09 00:08:20.000000000000
  end: 2020-05-09 00:09:10.000000000000
header: Fix issue 25
timestamps:
  SCHEDULED: 2020-05-09
state-history:
- state: NEXT
  time: 2020-05-09 01:31:40.000000000000
- state: TODO
  time: 2020-05-09 00:00:50.000000000000
tags:
- code
- online
properties:
  project: smos

Yaml Schema

An entry can either be only a header, in which case it can be represented as a string:

<header>

Or it can have more fields, in which case it is an object:

header: <header>
contents: <contents>
logbook: <logbook>
timestamps: <timestamps>
state-history: <state-history>
tags: <tags>
properties: <properties>

Header

A Smos entry's header consists of a single line of text.

Headers contain a title-like piece of information about an entry.

Yaml Schema

<string>

Example

'Go to the gym: HITT class'

Contents

A Smos entry's contents consist of an arbitrary piece of text.

Contents contain details about an entry.

Yaml Schema

<string>

Timestamps

A Smos entry's timestamps are a map of timestamp names to timestamps. Timestamps contain time-based information about an entry.

Timestamp names are arbitrary pieces of text without whitespace.

Standard timestamps are, for example:

  • BEGIN
  • END
  • SCHEDULED
  • DEADLINE

A timestamp has two possible granularities:

  • The day level
  • The moment level

Example

SCHEDULED: 2020-05-09

Yaml Schema

<key>: [ # %F
    <string>
  , # %F %T%Q
    <string>
  ]

Properties

A Smos entry's properties are a map of property names to property values. Properties contain named pieces of information about an entry. Property names are arbitrary pieces of text without whitespace. Property values are arbitrary pieces of text without newlines.

Properties can be used to filter entries by.

Standard properties are, for example:

  • timewindow
  • brainpower
  • client

Example

project: smos

Yaml Schema

<key>: <string>

State and state history

A Smos entry can have a state. States contain information about the state of an entry. States are arbitrary pieces of text without whitespace.

The state history must appear in reverse chronological order.

Standard states are, for example:

  • WAITING
  • TODO
  • STARTED
  • READY
  • NEXT
  • FAILED
  • DONE
  • CANCELLED

A Smos entry also remembers its entire state history.

Example

- state: NEXT
  time: 2020-05-09 01:31:40.000000000000
- state: TODO
  time: 2020-05-09 00:00:50.000000000000

Yaml Schema

- # In reverse chronological order
  # StateHistoryEntry
  [ state: # required
      # The new state
      # or <null>
      <string>
  , new-state: # required
      # legacy key
      # or <null>
      <string>
  ]
  [ time: # required
      [ # %F %H:%M:%S.%q
        <string>
      , # Whatever the 'time' library wants to parse. (fallback)
        <any>
      ]
  , timestamp: # required
      [ # %F %H:%M:%S.%q
        <string>
      , # Whatever the 'time' library wants to parse. (fallback)
        <any>
      ]
  ]

Tags

A Smos entry can have tags. Tags contain label-like information about an entry. Tags are arbitrary pieces of text without whitespace.

Properties can be used to filter entries by.

Standard tags are, for example:

  • code
  • external
  • home
  • online
  • offline
  • power
  • toast

Example

- code
- online

Yaml Schema

- <string>

Logbook

Each entry can contain information about when a clock was started on it. Clocks can either be closed (have a begin and end time) or open (only a begin time).

Logbooks are used to generate timetables.

Example

- start: 2020-05-09 01:31:40.000000000000
- start: 2020-05-09 00:08:20.000000000000
  end: 2020-05-09 00:09:10.000000000000

Yaml Schema

There is no yaml schema available for logbooks because they are parsed monadically.