Timesheet file format

The goal of this project is to define a file format that allows the user to record the time spent on tasks (a timesheet). The design is inspired by Tim Weber's timesheet.txt.

Motivation

The motivation behind this project is personal usage. I wanted to be able to track time easily in a system that was durable. This project pretends to specify a file format that is easy to parse (by a machine) and read (by a human).

The requirements to work with such format should only be access to a text editor, although there will be a script that lets the user view and edit such a file from the command line.

Why plain text? Because it is easy to read and write, and you don't need any special program to access your data. On top of that, it is easy to parse, so anyone a bit familiar with programming will be able to create a parser that works exactly how they want. Even if you don't, hopefully my parser is easy to understand, and it should take an interested user less than half an hour to get familiar with the code.

Specification

A bit more formally. In a timesheet file, each line fits in one of the following categories:

• Whitespace: blank line or line with whitespace characters only.
• Date change: a line that specifies a change in the date. Format: YYYY-MM-DD:.
• Task change: a change in the current task. This lines can be divided in the following subcategories:
  • Start task: stop last task and start a new one. Format: HHMM[SS] description.
  • Stop task: stop current task. Format: HHMM[SS]..
  • Continue last task: continue the task previous to the current one (see examples). Format: HHMM[SS]^.
  • Continue task by start time: continue a task specifying it's start time. Format: HHMM[SS]^[YYYY-DD-MMT]HHMM[SS].

The definition of the format symbols:

• On the date change, YYYY, MM and DD stand for the year, month and day, respectively.
• On task changes, HH, MM and SS stand for hour, minute and second, respectively. Note that on the subcategory "continue task by start time", the T represents the character T, not a variable.
• Square brackets ([, ]) delimit an optional value.
• description is a task description. It is a non-empty string without a newline or a # character surrounded by whitespace. Any word started with the # character is considered a tag for the task, and should not be considered part of the description message, a description doesn't need to have any other text if it already has a tag, a tag must only contain letters (lowercase or uppercase), numbers and underscores.
• A space ( ) stands for non-zero amount of spaces and/or tabs.
• Any other character stands for the literal value of the character.

On top of that, any line can start and/or end with any amount of spaces and/or tabs (which should be ignored by the parser). Any line can have comments at the end, which start with a # surrounded by spaces (or end of line characters) and end at the end of the line.

When parsing the description of a task, tags will be substituted by a space in the description, and then any leading or trailing spaces will be deleted. Therefore, any tags appearing at the start or end of the description will be completely deleted, while tags in between description text will be substituted by a space.

All entries must be in chronological order and there must not be two entries starting at the same time. If no second is specified for the start time of a task, the default value is 0.

If no day is specified when continuing a task by start time, then the current day is used (the day specified on last date change).

Examples

An example of a file would be:

TODO

Note

I hope to end up with a file without any ambiguities. If you have a question that is not answered, please contact me or open an issue.

TODO

• License
• Examples