README.md (3996B) - raw

      1 # Timesheet file format
      2 
      3 The goal of this project is to define a file format that allows the user to
      4 record the time spent on tasks (a timesheet). The design is inspired by Tim
      5 Weber's [timesheet.txt][ts].
      6 
      7 ## Motivation
      8 
      9 The motivation behind this project is personal usage. I wanted to be able to
     10 track time easily in a system that was durable. This project pretends to specify
     11 a file format that is easy to parse (by a machine) and read (by a human).
     12 
     13 The requirements to work with such format should only be access to a text
     14 editor, although there will be a script that lets the user view and edit such a
     15 file from the command line.
     16 
     17 Why plain text? Because it is easy to read and write, and you don't need any
     18 special program to access your data. On top of that, it is easy to parse, so
     19 anyone a bit familiar with programming will be able to create a parser that
     20 works exactly how they want. Even if you don't, hopefully my parser is easy to
     21 understand, and it should take an interested user less than half an hour to get
     22 familiar with the code.
     23 
     24 ## Specification
     25 
     26 A bit more formally. In a timesheet file, each line fits in one of the following
     27 categories:
     28 
     29 - Whitespace: blank line or line with whitespace characters only.
     30 - Date change: a line that specifies a change in the date. Format:
     31   `YYYY-MM-DD:`.
     32 - Task change: a change in the current task. This lines can be divided in the
     33   following subcategories:
     34   - Start task: stop last task and start a new one. Format: `HHMM[SS]
     35     description`.
     36   - Stop task: stop current task. Format: `HHMM[SS].`.
     37   - Continue last task: continue the task previous to the current one (see
     38     examples). Format: `HHMM[SS]^`.
     39   - Continue task by start time: continue a task specifying it's start time.
     40     Format: `HHMM[SS]^[YYYY-DD-MMT]HHMM[SS]`.
     41 
     42 The definition of the format symbols:
     43 
     44 - On the date change, `YYYY`, `MM` and `DD` stand for the year, month and day,
     45   respectively.
     46 - On task changes, `HH`, `MM` and `SS` stand for hour, minute and second,
     47   respectively. Note that on the subcategory "continue task by start time", the
     48   `T` represents the character `T`, not a variable.
     49 - Square brackets (`[`, `]`) delimit an optional value.
     50 - `description` is a task description. It is a non-empty string without a
     51   newline or a `#` character surrounded by whitespace. Any word started with the
     52   `#` character is considered a tag for the task, and should not be considered
     53   part of the description message, a description doesn't need to have any other
     54   text if it already has a tag, a tag must only contain letters (lowercase or
     55   uppercase), numbers and underscores.
     56 - A space (` `) stands for non-zero amount of spaces and/or tabs.
     57 - Any other character stands for the literal value of the character.
     58 
     59 On top of that, any line can start and/or end with any amount of spaces and/or
     60 tabs (which should be ignored by the parser). Any line can have comments at the
     61 end, which start with a `#` surrounded by spaces (or end of line characters) and
     62 end at the end of the line.
     63 
     64 When parsing the description of a task, tags will be substituted by a space in
     65 the description, and then any leading or trailing spaces will be deleted.
     66 Therefore, any tags appearing at the start or end of the description will be
     67 completely deleted, while tags in between description text will be substituted
     68 by a space.
     69 
     70 All entries must be in chronological order and there must not be two entries
     71 starting at the same time. If no second is specified for the start time of a
     72 task, the default value is 0.
     73 
     74 If no day is specified when continuing a task by start time, then the current
     75 day is used (the day specified on last date change).
     76 
     77 ### Examples
     78 
     79 An example of a file would be:
     80 
     81 ```
     82 TODO
     83 ```
     84 
     85 ## Note
     86 
     87 I hope to end up with a file without any ambiguities. If you have a question
     88 that is not answered, please [contact me][c] or open an issue.
     89 
     90 ## TODO
     91 
     92 - License
     93 - Examples
     94 
     95 [ts]: <https://github.com/scy/timesheet.txt>
     96 [c]: <https://oscarbenedito.com/contact/>