One of the most common queries and use of tag will probably related with dates. Although the documentation provided is excellent, some people will have a hard time understanding some of the concepts. I am going to try to add basic primer to get you started with dates and how to query them. I highly recommend you to read the documentation first or to have it available as you read this. Here are the links,
First - Modifier
Date based queries need to have the [d] modifier. Other modifiers available not related to dates are the following,
[i] --- Case insensitive. This is the default of all the queries.
[s] --- Case sensitive.
[n] -- Numeric compare
Now. you need to remember that the [d] query is numeric in nature. This means that it needs to be compared. This translation takes place within a library that translates dates to something the computer can understand. The dates should be in the ISO 8601 format. If you are wondering what is ISO 8601, that leads us to the next topic,
Date format (ISO 8601)
There are so many possible ways to write a date. I grew up writing dates like dd/mm/yyyy but then I had to relearn to write everything in the mm/dd/yyyy format that the US uses. The standard 8601 sets a specific way dates should be written. This is the ISO 8601
YYYY-MM-DD HH:MM:SS.MMM
YYYY - Stands for year and it would be something like 2016
MM - Month
DD - Day
HH - Hour in the 24 hour format. So if you mean 7:00pm you will have to write it like 19:00
MM - Minutes
SS - Seconds
MMM - Millisecond.
Only the whole year is required to be translated into a date by TaskPaper. That means that this (2016) is considered a correct date in the ISO 8601 standard. Since you are not providing more information, the program will assume that you are talking about January 1st 2016 at 12:00am or
2016-01-01 00:00:00.000
If you want to add more information, you can also include that,
2016-03-14
Again, since you are not including a time, the program will assume that you are talking about the beginning of the day which happens to be 12:00am or 00:00.
The tag you will be using for dates the most in TaskPaper is probably @due, but you can use any tags and include a date within. That means that if you are an event planner and happen to have hundreds of @meetings, or @weddings, or whatever comes to your mind, you can include a date, and TaskPaper’s engine can perform all kinds of queries on those tags too.
Comparison
Because the computer is translating this date into a numeric value, you will need the ><= signs to compare that date to something. For example,
@date <= [d] 2016
The first thing to remember is that in order for Taskpaper to understand that you are talking about dates, the [d] operator needs to be there. Now, this search will give you all the date tag values within the @date that are equal or less than (2016-01-01 00:00:00.000). The means that unless you have the following values, you will not get anything above that.
@date(2016)
@date(2016-01)
@date(2016-01-01)
But these dates are greater than 2016 not equal,
@date(2016-02-04)
@date(2016-01-02)
@date(2016-01-01 00:01)
That might be hard to grasp, because when we speak saying something like “I want all the dates where the year is equal to 2016” the computer has to translate that into something like,
@date >= [d] 2016 and @date < [d] 2017
But our natural instinct is to write
@date = [d] 2016
Which of course will not return anything since the computer again is assuming you mean…
2016-01-01 00:00:00.000
Or January 1, 2016 at exactly 00:00:00.000
So just remember that. The same applies to months. So if you want to look for dates before May, make sure that you start to look before the beginning of June like this,
@date < [d] 2016-06
Date Parsing
TaskPaper not only understands dates in the ISO 8601, but it has the ability to resolve other dates. The dates are included in the documentation, but here are the most useful,
tomorrow
today
week
month
monday
January - December (and their common abbreviations, ie. Jan-Dec)
Date Queries
This parser of natural language into a date becomes very useful when searching dates. Let’s say that you want to look at all the tags that are due in the beginning of next week.
@date < [d] next week
Now, you do have to remember that weeks start on Sunday. So this means that you will get all dates that are due before the beginning of next week that starts on Sunday. If with next week you mean in seven days. You should write something like,
@date < [d] + 7 days
You could even use and combine natural language with the times that are included in the guides.
@date <[d] July 23 2pm
TaskPaper uses that to translate into the appropriate ISO 8601 format.
Advance tagging.
Maybe now is a good time to mention that the same parsing that takes place on the queries is available for the tags. This is extremely useful to do ticker files or recurring events. Let’s say that you are keeping track of your payments and need to be reminded when to pay what. You could use text like this in your tag.
- US Bank @due(this month +5 days)
That means that this happens every month on the fifth, and it will come up if your current date happens to be within seven days of the fifth of the month and you query something like,
@due < [d] + 7 days
If you prefer, you can even use a tag like @recurring to hint at the fact that this dates happens every month on the fifth day.
You can also say that something is to happen every 4th of July at 2:00pm with something like
- Office party @recurring(July 4 2pm)
I think this is pretty basic primer of how to use date. If you have any questions related to dates, ask. Remember that ye have not because ye ask not
I also mentioned that you can input things in a more natural way if you rather do that. For example,