The time
library provides functions for determining the time and manipulating time values. KRE tries to determine the user's location and creates a time object that is localized for the user (i.e., in the user's time zone). The following functions are available:
time:now()
– returns the current date and time based upon the user's location data.time:new()
– returns a new RFC 3339 datetime string from a string formatted as described in ISO8601 (v2000).time:add()
– adds (or subtracts) a specific number of time units to a source string.
time:strftime()
– returns a datetime string in a specified format following POSIX strftime conventions.time:atom()
– converts a datetime string to an ATOM compatible form.time:compare()
– takes two datetime strings (ISO8601) and returns 1, 0, or [ms]1, depending on whether the first is before, the same, or after the second.time:now() - returns the current date based upon the user's location data
xTime = time:now() # 2010-10-06T18:11:47Z xTime = time:now({ # 2010-10-06T18:11:47Z "tz" : "America/Los_Angeles" }) |
time:new() - returns a new RFC 3339 datetime string from a string formatted as described in ISO8601 (v2000).
time:new("2010-08-08") # 2010-08-08T00:00:00Z (Date only—defaults to 00:00) time:new("67342") # 1967-12-08T00:00:00Z (Year DayOfYear) time:new("2011W206T1345-0600") # 2011-05-21T19:45:00Z (Year WeekOfYear DayOfWeek) time:new("083023Z") # 2010-10-05T08:30:23Z (Time only—defaults to today) |
Valid formats for the datetime source string can be found in ISO8601 (v2000).
time:add() - adds (or subtracts) a specific number of time units to a source string.
time:add("2010-08-08",{"weeks" : 5}) # 2010-09-12T00:00:00Z time:add("67342",{"hours": 3}) # 1967-12-08T04:00:00Z time:add("2011W206T1345-0600",{"days": -65}) # 2011-03-17T13:45:00Z time:add("083023Z",{"seconds" : 632}) # 2010-10-06T08:40:55Z time:add("1970-01-01",{"seconds": 1286388924}) # 2010-10-06T18:15:24Z |
time:strftime() - returns a datetime string in a specified format following POSIX strftime conventions.
time:strftime(xTime, "%F %T") # 2010-10-06 18:15:24 time:strftime(xTime, "%F") # 2010-10-06 time:strftime(xTime, "%T") # 18:19:29 time:strftime(xTime, "%A %d %b %Y") # Wednesday 06 Oct 2010 time:strftime(xTime, "%c") # Oct 6, 2010 6:25:55 PM time:strftime(xTime, "%s") # 1286388924 -- seconds since epoch |
Valid format arguments to strftime follow the POSIX strftime conventions.
time:strftime()
takes an optional third argument that is used to specify the timezone of the resulting formatted string. This can be used, among other things, to simply convert the timezone by returning an ISO formatted datetime string. For example, the following function uses time:strftime()
to convert an incoming datetime string to UTC:
convertToUTC = function(dt) { time:strftime(dt, "%Y%m%dT%H%M%S%z", {"tz":"UTC"}) }; |
time:atom() - converts a datetime string to an ATOM compatible form.
time:atom("2010-10-31") # 2010-10-31T00:00:00Z time:atom("2010-10-31",{ # 2010-10-31T06:00:00Z "tz" : "America/Denver" }) |
All of the following predicates are referenced to the user's local time. All times are 24-hour clock. All predicates must be preceded by the modules name, for example:
time:weekend()
timezone(<arg>) - takes a timezone abbreviation as the argument and checks the user's geo-location (based on IP address) and returns true or false
rule glee_check { select when pageview ".*" if (time:timezone("MST")) then { notify("Glee alert", "Glee starts at 7pm"); } } |
time:daytime() - returns true if it is between sunrise and sunset, otherwise returns false.
time:nighttime() - returns true if it is between sunset and sunrise, otherwise returns false.
time:morning() - returns true if it is between 0600 and 1200 hours, otherwise returns false.
time:afternoon() - returns true if it is between 1200 and 1700 hours, otherwise returns false.
time:evening() - returns true if it is bewteen 1700 and 2000 hours, otherwise returns false.
time:night() - returns true if it is between 2000 and 2400 hours, otherwise returns false.
time:lunch_time() - returns true if it is between 1130 and 1300 hours, otherwise returns false.
time:late_morning - returns true if it is between 1000 and 1200 hours, otherwise returns false.
time:early_afternoon - returns true if it is between 1200 and 1500 hours, otherwise returns false.
time:late_afternoon - returns true if it is between 1500 and 1700 hours, otherwise returns false.
time:time_between(<start hour>, <start minute>, <end hour>, <end minute>) - returns true if local time is between the time specified, otherwise returns false.
time:date_between(<start month>, <start day>, <start year>, <end month>, <end day>, <end year>) - returns true if the local time is between the specified dates (midnight), otherwise returns false.
time:date_start(<start month>, <start day>, <start year>) - returns true if the local time is on (or after) the specified date, otherwise returns false.
time:day_of_week(<day name>) - returns true if the current day of the week matches the name (capitalized) given as an argument, otherwise returns false.
time:today_is(<sun>, <mon>,<tue>, <wed>, <thur>, <fri>, <sat>) - returns true if it is the current day of the week, otherwise returns false. Note: Each argument must be either a 1 or 0 to indiate whether to check if today is the day of the week.
time:weekday() - returns true if today is a weekday, otherwise returns false.
time:weekend() - returns true if today is the weekend, otherwise returns false.