Legacy information

This page tries to collect information about all those assumptions, specifications and design decisions not actually documented in the original legacy hamster-cli to help our goal of creating an API compatible release.

Also, it may be that arguments specified as [start-time] [end-time] actually mean [start-time [end-time]]. Needs confirmation!

Time and Time-ranges

We actually have to situations where we parse times.

• When a raw_fact is parsed its start and endtime information is extracted.
• client functions (for example in hamster_cli) may allow explicit time(range?) information as a string that needs to be parsed. Both sets of information may be present at the same time. For example when hamster_cli start is called with an 'activity' that contains time information as well as additional start/end arguments.

The original Fact constructor handles parsing of implicit time information. If in addition to that explicit time info (for example from the initiating client command) is provided, it overrides implicit information.

It is worth mentioning that time-info mentioned by legacy --help refers to a single datetime-point. In contrast out undocumented but clearly present time-info for list and the like is actually one timerange-string. Bot need different handling/parsing.

Time info when parsing a raw_fact

Timeinfo of a raw_fact can take one of the following three forms:

• Duration: -
• Time: HH:MM
• Timerange HH:MM-HH:MM (Note: only only timeranges, not date(time)-ranges are allowed)

Commands

start

start <activity> [start-time] [end-time]: Track an activity

Args:

• start-time (str): Start time, optional.
• end-time (str): End time, optional.

Returns:

• Nothing

track

see start. Alias command.

stop

stop: Stop tracking current activity.

list

list [start-time] [end-time]: List activities

• __list collects the facts. For that it passes start/end datetimes. However the following __get_facts only deals with dates. Seems strange.

search

search [terms] [start-time] [end-time]: List activities matching a search term.

• term is matched against activity.name, category.name and tag.name

export

export [html|tsv|ical|xml] [start-time] [end-time]: Export activities with the specified format.

current

current: Print current activity

activities

activities: List all the activities names, one per line. legacy code actually has two functions

• _activities: never actually used! wat!
• allows for a search parameter with syntax: activity.name@category.name
• however, actual code block is most bizzare...
• activities: this is the one actually reference in the "API"/help.
• takes a search argument, however, this gets passed on the the storage method without further work. as a consequence there is no notion of filter by category as far as we can tell.

Search:

• syntax:

categories

categories: List all the categories names, one per line.

overview

overview: Launch overview window of th GTK client.

statistics

statistics: Launch statistics window of the GTK client.

about

about: Launch about window of the GTK client.

Time format

Please note: This seems to be different (more extensive) than the the original backend time parsing code. Needs confirmation!

Fixed time

YYYY-MM-DD hh:mm:ss

• If date is missing, it will default to today!
• If time is missing, it will default to 00:00 for start time and 23:59 for end time.

Relative time

-minutes

• Relative time in minutes from the current date and time.