Profile Selector Language
The domain specific language for the profile selector can be broken into a series of clauses, some of which are optional:
- Total Temporal Duration
The total range of time in which windows may be specified
- Temporal Window Width
The size of each temporal window
- Skip distance
(optional) How far to skip between when one window starts and when the next begins
- Inclusion/Exclusion specifiers
(optional) The set of specifiers to further filter the window
You must specify either a total temporal duration or a temporal window width. The remaining clauses are optional.
From a high level, the domain specific language fits the following three forms, which are composed of the clauses above:
time_interval Window (INCLUDING specifier list) (EXCLUDING specifier list)
temporal window width inclusion specifiers exclusion specifier
time_interval WINDOW EVERY time_interval FROM time_interval (TO time_interval) (INCLUDING specifier_list) (EXCLUDING specifier list)
temporal window width skip distance total temporal duration inclusion specifiers exclusion specifier
FROM time_interval (TO time_interval)
total temporal duration total temporal duration
Total Temporal Duration
Total temporal duration is specified by a phrase: FROM time_interval AGO TO
time_interval AGO
. This indicates the beginning and ending of a time interval.
This is an inclusive duration.
FROM
Can be the words "from" or "starting from".
time_interval
A time amount followed by a unit (for example, 1 hour). Fractional amounts are not supported. The unit may be "minute", "day", "hour" with any pluralization.
TO
Can be the words "until" or "to".
AGO
(optional) The word "ago"
The TO time_interval AGO
portion is optional. If this portion is
unspecified then it is expected that the time interval ends now.
Due to the vagaries of the English language, the from
and the
to
portions, if both are specified, are interchangeable with regard to
which one specifies the start and which specifies the end. In other words "starting from 1
hour ago to 30 minutes ago" and "starting from 30 minutes ago to 1 hour ago" specify the
same temporal duration.
Total Temporal Duration Examples
The domain specific language allows for some flexibility on how to specify a duration. The following are examples of various ways you can specify the same duration.
A duration starting 1 hour ago and ending now:
from 1 hour ago
from 1 hour
starting from 1 hour ago
starting from 1 hour
A duration starting 1 hour ago and ending 30 minutes ago:
from 1 hour ago until 30 minutes ago
from 30 minutes ago until 1 hour ago
starting from 1 hour ago to 30 minutes ago
starting from 1 hour to 30 minutes
Temporal Window Width
Temporal window width is the specification of a window. A window may either repeat
within a total temporal duration or it may fill the total temporal duration. This is an
inclusive window. A temporal window width is specified by the phrase: time_interval
WINDOW
.
time_interval
A time amount followed by a unit (for example, 1 hour). Fractional amounts are not supported. The unit may be "minute", day", or "hour" with any pluralization.
- WINDOW
(optional) The word "window".
Temporal Window Width Examples
A fixed window starting 2 hours ago and going until now
2 hour
2 hours
2 hours window
A repeating 30 minute window starting 2 hours ago and repeating every hour until now. This would result in 2 30-minute wide windows: 2 hours ago and 1 hour ago
30 minute window every 1 hour starting from 2 hours ago
temporal window width skip distance total temporal duration
30 minute windows every 1 hour from 2 hours ago
temporal window width skip distance total temporal duration
Skip Distance
Skip distance is the amount of time between when one temporal window begins and the
next window starts. It is, in effect, the window period. It is specified by the phrase
EVERY time_interval
.
- time_interval
A time amount followed by a unit (for example, 1 hour). Fractional amounts are not supported. The unit may be "minute", "day", or "hour" with any pluralization.
- EVERY
The word/phrase "every" or "for every".
Skip Distance Examples
A repeating 30 minute window starting 2 hours ago and repeating every hour until now. This would result in 2 30-minute wide windows: 2 hours ago and 1 hour ago
30 minute window every 1 hour starting from 2 hours ago
temporal window width skip distance total temporal duration
30 minutes window every 1 hour from 2 hours ago
temporal window width skip distance total temporal duration
A repeating 30 minute window starting 2 hours ago and repeating every hour until 30 minutes ago. This would result in 2 30-minute wide windows: 2 hours ago and 1 hour ago
30 minute window every 1 hour starting from 2 hours ago until 30 minutes ago
temporal window width skip distance total temporal duration
30 minutes window every 1 hour from 2 hours ago to 30 minutes ago
temporal window width skip distance total temporal duration
30 minutes window for every 1 hour from 30 minutes ago to 2 hours ago
temporal window width skip distance total temporal duration
Inclusion/Exclusion Specifiers
Inclusion and Exclusion specifiers operate as filters on the set of windows. They operate on the window beginning timestamp.
For inclusion specifiers, windows that are passed by any of the set of inclusion specifiers are included. Similarly, windows that are passed by any of the set of exclusion specifiers are excluded. Exclusion specifiers trump inclusion specifiers.
Specifiers follow one of the following formats depending on if it is an inclusion or exclusion specifier:
INCLUSION specifier, specifier, ...
INCLUSION can be "include", "includes" or "including"
EXCLUSION specifier, specifier, ...
EXCLUSION can be "exclude", "excludes" or "excluding"
The specifiers are a set of fixed specifiers available as part of the language:
Fixed day of week-based specifiers - includes or excludes if the window is on the specified day of the week
"monday" or "mondays"
"tuesday" or "tuesdays"
"wednesday" or "wednesdays"
"thursday" or "thursdays"
"friday" or "fridays"
"saturday" or "saturdays"
"sunday" or "sundays"
"weekday" or "weekdays"
"weekend" or ""weekends"
Relative day of week-based specifiers - includes or excludes based on the day of week relative to now
"current day of the week"
"current day of week"
"this day of the week"
"this day of week"
Specified date - includes or excludes based on the specified date
"date" - Takes up to 2 arguments
The day in
yyyy/MM/dd
format if no second argument is providedExample:
date:2017/12/25
would include or exclude December 25, 2017(optional) The format in which to specify the first argument
Example:
date:20171225:yyyyMMdd
would include or exclude December 25, 2017
Holidays - includes or excludes based on if the window starts during a holiday
"holiday" or "holidays"
Arguments form the jollyday hierarchy of holidays. For example, "us:nyc" would be holidays for New York City, USA
Countries supported are those supported in jollyday
Example:
holiday:us:nyc
would be the holidays of New York City, USAIf none is specified, it will choose based on locale.
Example:
holiday:hu
would be the holidays of Hungary
Inclusion/Exclusion Specifiers Examples
The following are inclusion/exclusion specifier examples and identify the various clauses used in these examples.
Assume the following examples are executed at noon.
A 1 hour window for the past 8 'current day of the week'
1 hour window every 24 hours from 56 days ago including this day of the week
temporal window width skip distance total temporal duration inclusion/exclusion specifiers
A 1 hour window for the past 8 tuesdays
1 hour window every 24 hours from 56 days ago including tuesdays
temporal window width skip distance total temporal duration inclusion/exclusion specifiers
A 30 minute window every tuesday at noon starting 14 days ago until now
30 minute window every 24 hours from 14 days ago including tuesdays
temporal window width skip distance total temporal duration inclusion/exclusion specifiers
A 30 minute window every day except holidays and weekends at noon starting 14 days ago until now
30 minutes every 24 hours from 14 days ago excluding holidays:us, weekends
30 minutes every 24 hours from 14 days ago including weekdays excluding holidays:us, weekends
temporal window width skip distance total temporal duration inclusion/exclusion specifiers
A 30 minute window at noon every day from 7 days ago including saturdays and excluding weekends. Because exclusions trump inclusions, the following will never yield any windows
30 minute window every 24 hours from 7 days ago including saturdays excluding weekends
temporal window width skip distance total temporal duration inclusion/exclusion specifiers