This specification is intended for developers wanting to build software that uses Traindown.
If you are a consumer looking for information on how to use Traindown to record your training, please refer to the Guide.
The specification presented below aims to provide a complete definition of the Traindown Language such that you may go out into the world and develop software that can help other folks record and make sense of their personal training history.
The language used in this specification is informal but comprehensive. Should you spot any errors or have any questions, please don't hesitate to email me at tyler at greaterscott.com or if you are on GitHub feel free to open an issue.
Also, don't forget to check out the Source page and the repos linked there for official prebuilt libraries that make using Traindown in your project as easy as adding another dependency.
Without further ado, here is Traindown.
Traindown has a relatively small set of reserved keywords and identifiers.
There is intention behind this. The point is to require as little cognitive overhead of the writer (not user!) as possible. You have to figure that alot of Traindown is typed while out of breath and covered in chalk or whatever else.
| Token | Name | Rules |
|---|---|---|
| EOF | End of file | System defined |
| LT | Line Terminator | ";" | Unicode line break codepoints |
| ANY | Non Line Terminating Unicode | !LT |
| NUM | Number Values | 0123456789. |
| DT | Date / Time | "@" ANY* LT |
| MK | Meta Key | "#" ANY* ":" |
| MV | Meta Value | MK ANY* LT |
| NOTE | Note | "*" ANY* LT |
| MN | Movement Name | ANY* : |
| SSMN | Superset Movement Name | "+" ANY* : |
| FAILS | Failures | NUM* ("f" | "F") |
| REPS | Reps | NUM* ("r" | "R") |
| SETS | Sets | NUM* ("s" | "S") |
| LOAD | Load | NUM* | ("b" | "B")("w" | "W") ["+" NUM*]? |
Traindown does not have composition of tokens into compound types or values. The table above represnts everything you will need to tokenize in order to parse a Traindown document
There are four scopes to a Traindown document ordered here by broadest to narrowest:
Document
From the beginning of the file to the EOF token.
Session
From a DT token until EOF or another DT token
Movement
From an MN/SSMN token until EOF or another MN/SSMN token
Performance
(LOAD | FAILS | SETS | REPS) tokens until a previously encountered token type repeats or EOF.
Currently this scope is not used in the parsing of Traindown.
Should your software make use of the document scope, please be sure to provide the people using your software of this. Also be aware that if you make use of the scope while it is currently undefined, you may have incompatibility with a future version of Traindown.
That said, if you are using it, please reach out an let me know so that we can work to bring it into the spec.
A session is to be considered as a single training event.
Every session must have at least a date on which it occurred.
You should provide error messaging to remind the writer that they should include a date (and/or time) in their Traindown document.
A single Traindown document may contain more than one session. This is up to the person writing the document, not you.
Should your software not honor this, please be sure to message this to the people using your software. Ideally this is to be done prior to an error message and you should offer to auto format into one session per document as this is simple to do.
In addition to the required date (and/or time), a session may contain metadata key/value pairs, notes, and movements. All three of those should be considered optional. A session without movements may not seem like a use case, but it is.
A movement is to be considered as a single exercise or event in a training session. An example of this would be something like "squats".
A movement may contain metadata key/value pairs, notes, and performances.
Like with sessions and movements, it may not make sense to have a movement without performances, but it is a supported use case so let's honor it.
You should record the sequence of the movements provided by the writer. This is important for them to make sense of the story of the session.
A performance is the expression of a movement.
Each performance must have a load.
A person writing Traindown may optionally provide sets, reps, and failures. In absence of explicit detail, you should assume a single set, a single rep, and no failures.
A performance may contain metadata key/value pairs and notes.
You should record the sequence of the performances provided by the writer. This is important for them to make sense of the story of the movement.
A heartfelt thanks to all the folks that have helped Traindown become what it is today. Whether you may realize it or not, you have postitively impacted this project.
A special thanks to
Kick ass!