Dates and Ranges
Commands that report on the data in the timelog need a way of specifying either a date or range of dates for the report. By default, these reports cover the current day. The date range descriptor supports specifying different dates or ranges of dates. For convenience, these descriptors can take on several forms.
Single Date
A single date is specified in one of the following forms:
- explicit date of the form
yyyy-mm-dd - the string today
- the string yesterday
- a day of the week: sunday, monday, tuesday, wednesday, … etc.
The values of today and yesterday describe the appropriate expected day. Each of the weekday values references the last instance of that day before today.
Any of these single dates results in a range spanning one day.
Date Pair
A pair of dates in one the forms above.
This pair results in a range that covers the two supplied dates. If the dates are in order, the start is the first date and end is the second date. If the dates are out of order, the range is not valid.
The two dates are not required to be in the same form. So, the following ranges are legal (assuming a current date of 2023-10-30):
| date range | start | end |
|---|---|---|
| sunday today | 2023-10-29 | 2023-10-30 |
| 2023-10-20 yesterday | 2023-10-20 | 2023-10-29 |
| 2023-10-01 2023-10-10 | 2023-10-01 | 2023-10-10 |
| monday 2023-10-28 | 2023-10-23 | 2023-10-28 |
| monday wednesday | 2023-10-23 | 2023-10-25 |
Range Description
A range description in one of the following forms:
- a month name: january, february, march, … etc.
- a short (3 char) month name: jan, feb, mar, … etc.
- a relative time frame: (this|last) (week|month|year)
- the string ytd
If the range description is a month name, the range will cover the whole month with that name before today. If we are in the month of June, a value of may will refer to the previous month, but a value of july will refer to last year’s July.
If the range description is this followed by week, month, or year, the resultant range covers:
- this week: from the last Sunday to Saturday of this week,
- this month: from the first day of the current month to last day of the month,
- this year: from the January 1 of the current year to the last day of the year.
If the range description is last followed by week, month, or year, the resultant range covers:
- last week: from the two Sundays ago to last Saturday,
- last month: from the first of the month before this one to the last day of that month,
- last year: from January 1 of the year before the current one to December 31 of the same year.
If the range description is the string ytd, the range will be from January 1 of the current year up to today.