Entering activities

aka: Fact parsing

Draft proposal - 2019-09-07

This is a proposal for revising the parsing of a fact given as a single string. For discussion see issue #438.

The aim is to provide uniform parsing of input data from the CLI and the GUI "Add activity" and "Edit activity" widgets [as well as the Gnome shell plugin ???].

This proposal also aims to provide reasonable consistency with current practice and to provide a good balance between convenience and safety.

Note: Some aspects of time entry depend on the hamster tracking setting (i.e. "New day starts at", default 05:30, day-start for brevity). This setting allows activities performed in the wee hours of the night to be considered as part of the previous day for display and statistics. e.g. activities started at 23:30 and 00:30 both belong to the same hamster day. Setting day-start to 00:00 would make hamster day and calendar day coincide.

Raw input format for activities

The parser magic is space separated.

[start [end]] activity name[@category][, description] [#tag1] ... [#tagn]]

Start or end options

start or end are given as either

date time which is interpreted in local civil time (as the desktop clock),

or just time which is assigned to the current hamster day.

Note: later on we might add date timezone time format (civil time).

date

date must be given in ISO format: yyyy-mm-dd.

time

1. HH[:|.]MM - four digits, possibly without any separator

   must be in range 00:00 to 23:59

2. -n[n[n]] - minutes in the past (range -1 to -999)

   from now for both start and end.

3. planned, not implemented yet.

   +n[n[n]] - minutes later

   from now for start, and from start for end.

Guidelines

1. When date and time are given explicitly together, e.g. 2019-09-01 02:00, they refer to local time (the same as on the desktop wall clock), as in hamster-cli.

2. When a date is not provided in the input line but rather the day is selected separately, as with the GUI timeline arrows, then it means "hamster day" (that by default starts at 05:30). This way the activity will appear in exactly this selected day when displayed by the overview, hamster list, hamster search, etc.

3. When an absolute time is specified without a date, e.g. 00:15 or 12:34 alone, it is considered to be in the current hamster-day.

   In other words, with functions defined there,

   start = hamsterday_time_to_datetime(hamster_today(), time)

   This applies to either start or end time.

4. Negative durations are always treated as errors, no fragile heuristics.

   Facts overlapping day-start have to be entered with full local date time.

   Note: It is easy and harmless to change the day-start if working later or earlier than usual.

5. When no start time is specified, an existing ongoing fact is stopped and a new ongoing fact is created starting now.

6. For maximum flexibility in data entry, creation of both past and future activities is allowed. Creation of overlapping activities is described on the Help page "Splitting activities" and is currently under review (see #396).