lunarmodules / Penlight / 478

Committed 12 Feb 2024 09:01AM UTC coverage: 89.675% (+0.7%) from 88.938%

Build # 478

Build Type

push

appveyor

Committed by

Tieske

Commit Message

fix(docs): proper escape back-slash

Run Details

5489 of 6121 relevant lines covered (89.67%)

357.21 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

86.65

/lua/pl/Date.lua

--- Date and Date Format classes.
-- See  @{05-dates.md|the Guide}.
--
-- NOTE: the date module is deprecated! see
-- https://github.com/lunarmodules/Penlight/issues/285
--
-- Dependencies: `pl.class`, `pl.stringx`, `pl.utils`
-- @classmod pl.Date
-- @pragma nostrip

local class = require 'pl.class'
local os_time, os_date = os.time, os.date
local stringx = require 'pl.stringx'
local utils = require 'pl.utils'
local assert_arg,assert_string = utils.assert_arg,utils.assert_string


utils.raise_deprecation {
  source = "Penlight " .. utils._VERSION,
  message = "the 'Date' module is deprecated, see https://github.com/lunarmodules/Penlight/issues/285",
  version_removed = "2.0.0",
  version_deprecated = "1.9.2",
}


local Date = class()
Date.Format = class()

--- Date constructor.
-- @param t this can be either
--
--   * `nil` or empty - use current date and time
--   * number - seconds since epoch (as returned by `os.time`). Resulting time is UTC
--   * `Date` - make a copy of this date
--   * table - table containing year, month, etc as for `os.time`. You may leave out year, month or day,
-- in which case current values will be used.
--   * year (will be followed by month, day etc)
--
-- @param ...  true if  Universal Coordinated Time, or two to five numbers: month,day,hour,min,sec
-- @function Date
function Date:_init(t,...)
    local time
    local nargs = select('#',...)
    if nargs > 2 then
        local extra = {...}
        local year = t
        t = {
            year = year,
            month = extra[1],
            day = extra[2],
            hour = extra[3],
            min = extra[4],
            sec = extra[5]
        }
    end
    if nargs == 1 then
        self.utc = select(1,...) == true
    end
    if t == nil or t == 'utc' then
        time = os_time()
        self.utc = t == 'utc'
    elseif type(t) == 'number' then
        time = t
        if self.utc == nil then self.utc = true end
    elseif type(t) == 'table' then
        if getmetatable(t) == Date then -- copy ctor
            time = t.time
            self.utc = t.utc
        else
            if not (t.year and t.month) then
                local lt = os_date('*t')
                if not t.year and not t.month and not t.day then
                    t.year = lt.year
                    t.month = lt.month
                    t.day = lt.day
                else
                    t.year = t.year or lt.year
                    t.month = t.month or (t.day and lt.month or 1)
                    t.day = t.day or 1
                end
            end
            t.day = t.day or 1
            time = os_time(t)
        end
    else
        error("bad type for Date constructor: "..type(t),2)
    end
    self:set(time)
end

--- set the current time of this Date object.
-- @int t seconds since epoch
function Date:set(t)
    self.time = t
    if self.utc then
        self.tab = os_date('!*t',t)
    else
        self.tab = os_date('*t',t)
    end
end

--- get the time zone offset from UTC.
-- @int ts seconds ahead of UTC
function Date.tzone (ts)
    if ts == nil then
        ts = os_time()
    elseif type(ts) == "table" then
        if getmetatable(ts) == Date then
            ts = ts.time
        else
            ts = Date(ts).time
        end
    end
    local utc = os_date('!*t',ts)
    local lcl = os_date('*t',ts)
    lcl.isdst = false
    return os.difftime(os_time(lcl), os_time(utc))
end

--- convert this date to UTC.
function Date:toUTC ()
    local ndate = Date(self)
    if not self.utc then
        ndate.utc = true
        ndate:set(ndate.time)
    end
    return ndate
end

--- convert this UTC date to local.
function Date:toLocal ()
    local ndate = Date(self)
    if self.utc then
        ndate.utc = false
        ndate:set(ndate.time)
--~         ndate:add { sec = Date.tzone(self) }
    end
    return ndate
end

--- set the year.
-- @int y Four-digit year
-- @class function
-- @name Date:year

--- set the month.
-- @int m month
-- @class function
-- @name Date:month

--- set the day.
-- @int d day
-- @class function
-- @name Date:day

--- set the hour.
-- @int h hour
-- @class function
-- @name Date:hour

--- set the minutes.
-- @int min minutes
-- @class function
-- @name Date:min

--- set the seconds.
-- @int sec seconds
-- @class function
-- @name Date:sec

--- set the day of year.
-- @class function
-- @int yday day of year
-- @name Date:yday

--- get the year.
-- @int y Four-digit year
-- @class function
-- @name Date:year

--- get the month.
-- @class function
-- @name Date:month

--- get the day.
-- @class function
-- @name Date:day

--- get the hour.
-- @class function
-- @name Date:hour

--- get the minutes.
-- @class function
-- @name Date:min

--- get the seconds.
-- @class function
-- @name Date:sec

--- get the day of year.
-- @class function
-- @name Date:yday


for _,c in ipairs{'year','month','day','hour','min','sec','yday'} do
    Date[c] = function(self,val)
        if val then
            assert_arg(1,val,"number")
            self.tab[c] = val
            self:set(os_time(self.tab))
            return self
        else
            return self.tab[c]
        end
    end
end

--- name of day of week.
-- @bool full abbreviated if true, full otherwise.
-- @ret string name
function Date:weekday_name(full)
    return os_date(full and '%A' or '%a',self.time)
end

--- name of month.
-- @int full abbreviated if true, full otherwise.
-- @ret string name
function Date:month_name(full)
    return os_date(full and '%B' or '%b',self.time)
end

--- is this day on a weekend?.
function Date:is_weekend()
    return self.tab.wday == 1 or self.tab.wday == 7
end

--- add to a date object.
-- @param t a table containing one of the following keys and a value:
-- one of `year`,`month`,`day`,`hour`,`min`,`sec`
-- @return this date
function Date:add(t)
    local old_dst = self.tab.isdst
    local key,val = next(t)
    self.tab[key] = self.tab[key] + val
    self:set(os_time(self.tab))
    if old_dst ~= self.tab.isdst then
        self.tab.hour = self.tab.hour - (old_dst and 1 or -1)
        self:set(os_time(self.tab))
    end
    return self
end

--- last day of the month.
-- @return int day
function Date:last_day()
    local d = 28
    local m = self.tab.month
    while self.tab.month == m do
        d = d + 1
        self:add{day=1}
    end
    self:add{day=-1}
    return self
end

--- difference between two Date objects.
-- @tparam Date other Date object
-- @treturn Date.Interval object
function Date:diff(other)
    local dt = self.time - other.time
    if dt < 0 then error("date difference is negative!",2) end
    return Date.Interval(dt)
end

--- long numerical ISO data format version of this date.
function Date:__tostring()
    local fmt = '%Y-%m-%dT%H:%M:%S'
    if self.utc then
        fmt = "!"..fmt
    end
    local t = os_date(fmt,self.time)
    if self.utc then
        return  t .. 'Z'
    else
        local offs = self:tzone()
        if offs == 0 then
            return t .. 'Z'
        end
        local sign = offs > 0 and '+' or '-'
        local h = math.ceil(offs/3600)
        local m = (offs % 3600)/60
        if m == 0 then
            return t .. ('%s%02d'):format(sign,h)
        else
            return t .. ('%s%02d:%02d'):format(sign,h,m)
        end
    end
end

--- equality between Date objects.
function Date:__eq(other)
    return self.time == other.time
end

--- ordering between Date objects.
function Date:__lt(other)
    return self.time < other.time
end

--- difference between Date objects.
-- @function Date:__sub
Date.__sub = Date.diff

--- add a date and an interval.
-- @param other either a `Date.Interval` object or a table such as
-- passed to `Date:add`
function Date:__add(other)
    local nd = Date(self)
    if Date.Interval:class_of(other) then
        other = {sec=other.time}
    end
    nd:add(other)
    return nd
end

Date.Interval = class(Date)

---- Date.Interval constructor
-- @int t an interval in seconds
-- @function Date.Interval
function Date.Interval:_init(t)
    self:set(t)
end

function Date.Interval:set(t)
    self.time = t
    self.tab = os_date('!*t',self.time)
end

local function ess(n)
    if n > 1 then return 's '
    else return ' '
    end
end

--- If it's an interval then the format is '2 hours 29 sec' etc.
function Date.Interval:__tostring()
    local t, res = self.tab, ''
    local y,m,d = t.year - 1970, t.month - 1, t.day - 1
    if y > 0 then res = res .. y .. ' year'..ess(y) end
    if m > 0 then res = res .. m .. ' month'..ess(m) end
    if d > 0 then res = res .. d .. ' day'..ess(d) end
    if y == 0 and m == 0 then
        local h = t.hour
        if h > 0 then res = res .. h .. ' hour'..ess(h) end
        if t.min > 0 then res = res .. t.min .. ' min ' end
        if t.sec > 0 then res = res .. t.sec .. ' sec ' end
    end
    if res == '' then res = 'zero' end
    return res
end

------------ Date.Format class: parsing and renderinig dates ------------

-- short field names, explicit os.date names, and a mask for allowed field repeats
local formats = {
    d = {'day',{true,true}},
    y = {'year',{false,true,false,true}},
    m = {'month',{true,true}},
    H = {'hour',{true,true}},
    M = {'min',{true,true}},
    S = {'sec',{true,true}},
}

--- Date.Format constructor.
-- @string fmt. A string where the following fields are significant:
--
--   * d day (either d or dd)
--   * y year (either yy or yyy)
--   * m month (either m or mm)
--   * H hour (either H or HH)
--   * M minute (either M or MM)
--   * S second (either S or SS)
--
-- Alternatively, if fmt is nil then this returns a flexible date parser
-- that tries various date/time schemes in turn:
--
--  * [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601), like `2010-05-10 12:35:23Z` or `2008-10-03T14:30+02`
--  * times like 15:30 or 8.05pm  (assumed to be today's date)
--  * dates like 28/10/02 (European order!) or 5 Feb 2012
--  * month name like march or Mar (case-insensitive, first 3 letters); here the
-- day will be 1 and the year this current year
--
-- A date in format 3 can be optionally followed by a time in format 2.
-- Please see test-date.lua in the tests folder for more examples.
-- @usage df = Date.Format("yyyy-mm-dd HH:MM:SS")
-- @class function
-- @name Date.Format
function Date.Format:_init(fmt)
    if not fmt then
        self.fmt = '%Y-%m-%d %H:%M:%S'
        self.outf = self.fmt
        self.plain = true
        return
    end
    local append = table.insert
    local D,PLUS,OPENP,CLOSEP = '\001','\002','\003','\004'
    local vars,used = {},{}
    local patt,outf = {},{}
    local i = 1
    while i < #fmt do
        local ch = fmt:sub(i,i)
        local df = formats[ch]
        if df then
            if used[ch] then error("field appeared twice: "..ch,4) end
            used[ch] = true
            -- this field may be repeated
            local _,inext = fmt:find(ch..'+',i+1)
            local cnt = not _ and 1 or inext-i+1
            if not df[2][cnt] then error("wrong number of fields: "..ch,4) end
            -- single chars mean 'accept more than one digit'
            local p = cnt==1 and (D..PLUS) or (D):rep(cnt)
            append(patt,OPENP..p..CLOSEP)
            append(vars,ch)
            if ch == 'y' then
                append(outf,cnt==2 and '%y' or '%Y')
            else
                append(outf,'%'..ch)
            end
            i = i + cnt
        else
            append(patt,ch)
            append(outf,ch)
            i = i + 1
        end
    end
    -- escape any magic characters
    fmt = utils.escape(table.concat(patt))
   -- fmt = table.concat(patt):gsub('[%-%.%+%[%]%(%)%$%^%%%?%*]','%%%1')
    -- replace markers with their magic equivalents
    fmt = fmt:gsub(D,'%%d'):gsub(PLUS,'+'):gsub(OPENP,'('):gsub(CLOSEP,')')
    self.fmt = fmt
    self.outf = table.concat(outf)
    self.vars = vars
end

local parse_date

--- parse a string into a Date object.
-- @string str a date string
-- @return date object
function Date.Format:parse(str)
    assert_string(1,str)
    if self.plain then
        return parse_date(str,self.us)
    end
    local res = {str:match(self.fmt)}
    if #res==0 then return nil, 'cannot parse '..str end
    local tab = {}
    for i,v in ipairs(self.vars) do
        local name = formats[v][1] -- e.g. 'y' becomes 'year'
        tab[name] = tonumber(res[i])
    end
    -- os.date() requires these fields; if not present, we assume
    -- that the time set is for the current day.
    if not (tab.year and tab.month and tab.day) then
        local today = Date()
        tab.year = tab.year or today:year()
        tab.month = tab.month or today:month()
        tab.day = tab.day or today:day()
    end
    local Y = tab.year
    if Y < 100 then -- classic Y2K pivot
        tab.year = Y + (Y < 35 and 2000 or 1999)
    elseif not Y then
        tab.year = 1970
    end
    return Date(tab)
end

--- convert a Date object into a string.
-- @param d a date object, or a time value as returned by @{os.time}
-- @return string
function Date.Format:tostring(d)
    local tm
    local fmt = self.outf
    if type(d) == 'number' then
        tm = d
    else
        tm = d.time
        if d.utc then
            fmt = '!'..fmt
        end
    end
    return os_date(fmt,tm)
end

--- force US order in dates like 9/11/2001
function Date.Format:US_order(yesno)
    self.us = yesno
end

--local months = {jan=1,feb=2,mar=3,apr=4,may=5,jun=6,jul=7,aug=8,sep=9,oct=10,nov=11,dec=12}
local months
local parse_date_unsafe
local function create_months()
    local ld, day1 = parse_date_unsafe '2000-12-31', {day=1}
    months = {}
    for i = 1,12 do
        ld = ld:last_day()
        ld:add(day1)
        local mon = ld:month_name():lower()
        months [mon] = i
    end
end

--[[
Allowed patterns:
- [day] [monthname] [year] [time]
- [day]/[month][/year] [time]

]]

local function looks_like_a_month(w)
    return w:match '^%a+,*$' ~= nil
end
local is_number = stringx.isdigit
local function tonum(s,l1,l2,kind)
    kind = kind or ''
    local n = tonumber(s)
    if not n then error(("%snot a number: '%s'"):format(kind,s)) end
    if n < l1 or n > l2 then
        error(("%s out of range: %s is not between %d and %d"):format(kind,s,l1,l2))
    end
    return n
end

local function  parse_iso_end(p,ns,sec)
    -- may be fractional part of seconds
    local _,nfrac,secfrac = p:find('^%.%d+',ns+1)
    if secfrac then
        sec = sec .. secfrac
        p = p:sub(nfrac+1)
    else
        p = p:sub(ns+1)
    end
    -- ISO 8601 dates may end in Z (for UTC) or [+-][isotime]
    -- (we're working with the date as lower case, hence 'z')
    if p:match 'z$' then -- we're UTC!
        return  sec, {h=0,m=0}
    end
    p = p:gsub(':','') -- turn 00:30 to 0030
    local _,_,sign,offs = p:find('^([%+%-])(%d+)')
    if not sign then return sec, nil end -- not UTC

    if #offs == 2 then offs = offs .. '00' end -- 01 to 0100
    local tz = { h = tonumber(offs:sub(1,2)), m = tonumber(offs:sub(3,4)) }
    if sign == '-' then tz.h = -tz.h; tz.m = -tz.m end
    return sec, tz
end

function parse_date_unsafe (s,US)
    s = s:gsub('T',' ') -- ISO 8601
    local parts = stringx.split(s:lower())
    local i,p = 1,parts[1]
    local function nextp() i = i + 1; p = parts[i] end
    local year,min,hour,sec,apm
    local tz
    local _,nxt,day, month = p:find '^(%d+)/(%d+)'
    if day then
        -- swop for US case
        if US then
            day, month = month, day
        end
        _,_,year = p:find('^/(%d+)',nxt+1)
        nextp()
    else -- ISO
        year,month,day = p:match('^(%d+)%-(%d+)%-(%d+)')
        if year then
            nextp()
        end
    end
    if p and not year and is_number(p) then -- has to be date
        if #p < 4 then
            day = p
            nextp()
        else -- unless it looks like a 24-hour time
            year = true
        end
    end
    if p and looks_like_a_month(p) then -- date followed by month
        p = p:sub(1,3)
        if not months then
            create_months()
        end
        local mon = months[p]
        if mon then
            month = mon
        else error("not a month: " .. p) end
        nextp()
    end
    if p and not year and is_number(p) then
        year = p
        nextp()
    end

    if p then -- time is hh:mm[:ss], hhmm[ss] or H.M[am|pm]
        _,nxt,hour,min = p:find '^(%d+):(%d+)'
        local ns
        if nxt then -- are there seconds?
            _,ns,sec = p:find ('^:(%d+)',nxt+1)
            --if ns then
                sec,tz = parse_iso_end(p,ns or nxt,sec)
            --end
        else -- might be h.m
            _,ns,hour,min = p:find '^(%d+)%.(%d+)'
            if ns then
                apm = p:match '[ap]m$'
            else  -- or hhmm[ss]
                local hourmin
                _,nxt,hourmin = p:find ('^(%d+)')
                if nxt then
                   hour = hourmin:sub(1,2)
                   min = hourmin:sub(3,4)
                   sec = hourmin:sub(5,6)
                   if #sec == 0 then sec = nil end
                   sec,tz = parse_iso_end(p,nxt,sec)
                end
            end
        end
    end
    local today
    if year == true then year = nil end
    if not (year and month and day) then
        today = Date()
    end
    day = day and tonum(day,1,31,'day') or (month and 1 or today:day())
    month = month and tonum(month,1,12,'month') or today:month()
    year = year and tonumber(year) or today:year()
    if year < 100 then -- two-digit year pivot around year < 2035
        year = year + (year < 35 and 2000 or 1900)
    end
    hour = hour and tonum(hour,0,apm and 12 or 24,'hour') or 12
    if apm == 'pm' then
        hour = hour + 12
    end
    min = min and tonum(min,0,59) or 0
    sec = sec and tonum(sec,0,60) or 0  --60 used to indicate leap second
    local res = Date {year = year, month = month, day = day, hour = hour, min = min, sec = sec}
    if tz then -- ISO 8601 UTC time
        local corrected = false
        if tz.h ~= 0 then res:add {hour = -tz.h}; corrected = true end
        if tz.m ~= 0 then res:add {min = -tz.m}; corrected = true end
        res.utc = true
        -- we're in UTC, so let's go local...
        if corrected then
            res = res:toLocal()
        end-- we're UTC!
    end
    return res
end

function parse_date (s)
    local ok, d = pcall(parse_date_unsafe,s)
    if not ok then -- error
        d = d:gsub('.-:%d+: ','')
        return nil, d
    else
        return d
    end
end

return Date


1	--- Date and Date Format classes.
2	-- See @{05-dates.md\|the Guide}.
3	--
4	-- NOTE: the date module is deprecated! see
5	-- https://github.com/lunarmodules/Penlight/issues/285
6	--
7	-- Dependencies: `pl.class`, `pl.stringx`, `pl.utils`
8	-- @classmod pl.Date
9	-- @pragma nostrip
10
11	local class = require 'pl.class'	24✔
12	local os_time, os_date = os.time, os.date	24✔
13	local stringx = require 'pl.stringx'	24✔
14	local utils = require 'pl.utils'	24✔
15	local assert_arg,assert_string = utils.assert_arg,utils.assert_string	24✔
16
17
18	utils.raise_deprecation {	48✔
19	source = "Penlight " .. utils._VERSION,	24✔
20	message = "the 'Date' module is deprecated, see https://github.com/lunarmodules/Penlight/issues/285",	12✔
21	version_removed = "2.0.0",	12✔
22	version_deprecated = "1.9.2",	12✔
23	}
24
25
26	local Date = class()	24✔
27	Date.Format = class()	36✔
28
29	--- Date constructor.
30	-- @param t this can be either
31	--
32	-- * `nil` or empty - use current date and time
33	-- * number - seconds since epoch (as returned by `os.time`). Resulting time is UTC
34	-- * `Date` - make a copy of this date
35	-- * table - table containing year, month, etc as for `os.time`. You may leave out year, month or day,
36	-- in which case current values will be used.
37	-- * year (will be followed by month, day etc)
38	--
39	-- @param ... true if Universal Coordinated Time, or two to five numbers: month,day,hour,min,sec
40	-- @function Date
41	function Date:_init(t,...)	24✔
42	local time
43	local nargs = select('#',...)	528✔
44	if nargs > 2 then	528✔
45	local extra = {...}	24✔
46	local year = t	24✔
47	t = {	24✔
48	year = year,	24✔
49	month = extra[1],	24✔
50	day = extra[2],	24✔
51	hour = extra[3],	24✔
52	min = extra[4],	24✔
53	sec = extra[5]	24✔
54	}	24✔
55	end
56	if nargs == 1 then	528✔
57	self.utc = select(1,...) == true	×
58	end
59	if t == nil or t == 'utc' then	528✔
60	time = os_time()	80✔
61	self.utc = t == 'utc'	80✔
62	elseif type(t) == 'number' then	448✔
63	time = t	80✔
64	if self.utc == nil then self.utc = true end	80✔
65	elseif type(t) == 'table' then	368✔
66	if getmetatable(t) == Date then -- copy ctor	368✔
67	time = t.time	56✔
68	self.utc = t.utc	56✔
69	else
70	if not (t.year and t.month) then	312✔
71	local lt = os_date('*t')	32✔
72	if not t.year and not t.month and not t.day then	32✔
73	t.year = lt.year	16✔
74	t.month = lt.month	16✔
75	t.day = lt.day	16✔
76	else
77	t.year = t.year or lt.year	16✔
78	t.month = t.month or (t.day and lt.month or 1)	16✔
79	t.day = t.day or 1	16✔
80	end
81	end
82	t.day = t.day or 1	312✔
83	time = os_time(t)	312✔
84	end
85	else
86	error("bad type for Date constructor: "..type(t),2)	×
87	end
88	self:set(time)	528✔
89	end
90
91	--- set the current time of this Date object.
92	-- @int t seconds since epoch
93	function Date:set(t)	24✔
94	self.time = t	3,472✔
95	if self.utc then	3,472✔
96	self.tab = os_date('!*t',t)	136✔
97	else
98	self.tab = os_date('*t',t)	3,336✔
99	end
100	end
101
102	--- get the time zone offset from UTC.
103	-- @int ts seconds ahead of UTC
104	function Date.tzone (ts)	24✔
105	if ts == nil then	×
106	ts = os_time()	×
107	elseif type(ts) == "table" then	×
108	if getmetatable(ts) == Date then	×
109	ts = ts.time	×
110	else
111	ts = Date(ts).time	×
112	end
113	end
114	local utc = os_date('!*t',ts)	×
115	local lcl = os_date('*t',ts)	×
116	lcl.isdst = false	×
117	return os.difftime(os_time(lcl), os_time(utc))	×
118	end
119
120	--- convert this date to UTC.
121	function Date:toUTC ()	24✔
122	local ndate = Date(self)	32✔
123	if not self.utc then	32✔
124	ndate.utc = true	24✔
125	ndate:set(ndate.time)	24✔
126	end
127	return ndate	32✔
128	end
129
130	--- convert this UTC date to local.
131	function Date:toLocal ()	24✔
132	local ndate = Date(self)	16✔
133	if self.utc then	16✔
134	ndate.utc = false	16✔
135	ndate:set(ndate.time)	16✔
136	--~ ndate:add { sec = Date.tzone(self) }
137	end
138	return ndate	16✔
139	end
140
141	--- set the year.
142	-- @int y Four-digit year
143	-- @class function
144	-- @name Date:year
145
146	--- set the month.
147	-- @int m month
148	-- @class function
149	-- @name Date:month
150
151	--- set the day.
152	-- @int d day
153	-- @class function
154	-- @name Date:day
155
156	--- set the hour.
157	-- @int h hour
158	-- @class function
159	-- @name Date:hour
160
161	--- set the minutes.
162	-- @int min minutes
163	-- @class function
164	-- @name Date:min
165
166	--- set the seconds.
167	-- @int sec seconds
168	-- @class function
169	-- @name Date:sec
170
171	--- set the day of year.
172	-- @class function
173	-- @int yday day of year
174	-- @name Date:yday
175
176	--- get the year.
177	-- @int y Four-digit year
178	-- @class function
179	-- @name Date:year
180
181	--- get the month.
182	-- @class function
183	-- @name Date:month
184
185	--- get the day.
186	-- @class function
187	-- @name Date:day
188
189	--- get the hour.
190	-- @class function
191	-- @name Date:hour
192
193	--- get the minutes.
194	-- @class function
195	-- @name Date:min
196
197	--- get the seconds.
198	-- @class function
199	-- @name Date:sec
200
201	--- get the day of year.
202	-- @class function
203	-- @name Date:yday
204
205
206	for _,c in ipairs{'year','month','day','hour','min','sec','yday'} do	192✔
207	Date[c] = function(self,val)
208	if val then	192✔
209	assert_arg(1,val,"number")	×
210	self.tab[c] = val	×
211	self:set(os_time(self.tab))	×
212	return self	×
213	else
214	return self.tab[c]	192✔
215	end
216	end
217	end
218
219	--- name of day of week.
220	-- @bool full abbreviated if true, full otherwise.
221	-- @ret string name
222	function Date:weekday_name(full)	24✔
223	return os_date(full and '%A' or '%a',self.time)	×
224	end
225
226	--- name of month.
227	-- @int full abbreviated if true, full otherwise.
228	-- @ret string name
229	function Date:month_name(full)	24✔
230	return os_date(full and '%B' or '%b',self.time)	96✔
231	end
232
233	--- is this day on a weekend?.
234	function Date:is_weekend()	24✔
235	return self.tab.wday == 1 or self.tab.wday == 7	×
236	end
237
238	--- add to a date object.
239	-- @param t a table containing one of the following keys and a value:
240	-- one of `year`,`month`,`day`,`hour`,`min`,`sec`
241	-- @return this date
242	function Date:add(t)	24✔
243	local old_dst = self.tab.isdst	2,904✔
244	local key,val = next(t)	2,904✔
245	self.tab[key] = self.tab[key] + val	2,904✔
246	self:set(os_time(self.tab))	2,904✔
247	if old_dst ~= self.tab.isdst then	2,904✔
248	self.tab.hour = self.tab.hour - (old_dst and 1 or -1)	×
249	self:set(os_time(self.tab))	×
250	end
251	return self	2,904✔
252	end
253
254	--- last day of the month.
255	-- @return int day
256	function Date:last_day()	24✔
257	local d = 28	96✔
258	local m = self.tab.month	96✔
259	while self.tab.month == m do	2,776✔
260	d = d + 1	2,680✔
261	self:add{day=1}	4,020✔
262	end
263	self:add{day=-1}	96✔
264	return self	96✔
265	end
266
267	--- difference between two Date objects.
268	-- @tparam Date other Date object
269	-- @treturn Date.Interval object
270	function Date:diff(other)	24✔
271	local dt = self.time - other.time	24✔
272	if dt < 0 then error("date difference is negative!",2) end	24✔
273	return Date.Interval(dt)	24✔
274	end
275
276	--- long numerical ISO data format version of this date.
277	function Date:__tostring()	24✔
278	local fmt = '%Y-%m-%dT%H:%M:%S'	×
279	if self.utc then	×
280	fmt = "!"..fmt	×
281	end
282	local t = os_date(fmt,self.time)	×
283	if self.utc then	×
284	return t .. 'Z'	×
285	else
286	local offs = self:tzone()	×
287	if offs == 0 then	×
288	return t .. 'Z'	×
289	end
290	local sign = offs > 0 and '+' or '-'	×
291	local h = math.ceil(offs/3600)	×
292	local m = (offs % 3600)/60	×
293	if m == 0 then	×
294	return t .. ('%s%02d'):format(sign,h)	×
295	else
296	return t .. ('%s%02d:%02d'):format(sign,h,m)	×
297	end
298	end
299	end
300
301	--- equality between Date objects.
302	function Date:__eq(other)	24✔
303	return self.time == other.time	120✔
304	end
305
306	--- ordering between Date objects.
307	function Date:__lt(other)	24✔
308	return self.time < other.time	8✔
309	end
310
311	--- difference between Date objects.
312	-- @function Date:__sub
313	Date.__sub = Date.diff	24✔
314
315	--- add a date and an interval.
316	-- @param other either a `Date.Interval` object or a table such as
317	-- passed to `Date:add`
318	function Date:__add(other)	24✔
319	local nd = Date(self)	8✔
320	if Date.Interval:class_of(other) then	12✔
321	other = {sec=other.time}	×
322	end
323	nd:add(other)	8✔
324	return nd	8✔
325	end
326
327	Date.Interval = class(Date)	36✔
328
329	---- Date.Interval constructor
330	-- @int t an interval in seconds
331	-- @function Date.Interval
332	function Date.Interval:_init(t)	48✔
333	self:set(t)	40✔
334	end
335
336	function Date.Interval:set(t)	48✔
337	self.time = t	40✔
338	self.tab = os_date('!*t',self.time)	40✔
339	end
340
341	local function ess(n)
342	if n > 1 then return 's '	8✔
343	else return ' '	8✔
344	end
345	end
346
347	--- If it's an interval then the format is '2 hours 29 sec' etc.
348	function Date.Interval:__tostring()	48✔
349	local t, res = self.tab, ''	24✔
350	local y,m,d = t.year - 1970, t.month - 1, t.day - 1	24✔
351	if y > 0 then res = res .. y .. ' year'..ess(y) end	24✔
352	if m > 0 then res = res .. m .. ' month'..ess(m) end	28✔
353	if d > 0 then res = res .. d .. ' day'..ess(d) end	24✔
354	if y == 0 and m == 0 then	24✔
355	local h = t.hour	16✔
356	if h > 0 then res = res .. h .. ' hour'..ess(h) end	16✔
357	if t.min > 0 then res = res .. t.min .. ' min ' end	16✔
358	if t.sec > 0 then res = res .. t.sec .. ' sec ' end	16✔
359	end
360	if res == '' then res = 'zero' end	24✔
361	return res	24✔
362	end
363
364	------------ Date.Format class: parsing and renderinig dates ------------
365
366	-- short field names, explicit os.date names, and a mask for allowed field repeats
367	local formats = {	24✔
368	d = {'day',{true,true}},	24✔
369	y = {'year',{false,true,false,true}},	24✔
370	m = {'month',{true,true}},	24✔
371	H = {'hour',{true,true}},	24✔
372	M = {'min',{true,true}},	24✔
373	S = {'sec',{true,true}},	24✔
374	}
375
376	--- Date.Format constructor.
377	-- @string fmt. A string where the following fields are significant:
378	--
379	-- * d day (either d or dd)
380	-- * y year (either yy or yyy)
381	-- * m month (either m or mm)
382	-- * H hour (either H or HH)
383	-- * M minute (either M or MM)
384	-- * S second (either S or SS)
385	--
386	-- Alternatively, if fmt is nil then this returns a flexible date parser
387	-- that tries various date/time schemes in turn:
388	--
389	-- * [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601), like `2010-05-10 12:35:23Z` or `2008-10-03T14:30+02`
390	-- * times like 15:30 or 8.05pm (assumed to be today's date)
391	-- * dates like 28/10/02 (European order!) or 5 Feb 2012
392	-- * month name like march or Mar (case-insensitive, first 3 letters); here the
393	-- day will be 1 and the year this current year
394	--
395	-- A date in format 3 can be optionally followed by a time in format 2.
396	-- Please see test-date.lua in the tests folder for more examples.
397	-- @usage df = Date.Format("yyyy-mm-dd HH:MM:SS")
398	-- @class function
399	-- @name Date.Format
400	function Date.Format:_init(fmt)	48✔
401	if not fmt then	80✔
402	self.fmt = '%Y-%m-%d %H:%M:%S'	16✔
403	self.outf = self.fmt	16✔
404	self.plain = true	16✔
405	return	16✔
406	end
407	local append = table.insert	64✔
408	local D,PLUS,OPENP,CLOSEP = '\001','\002','\003','\004'	64✔
409	local vars,used = {},{}	64✔
410	local patt,outf = {},{}	64✔
411	local i = 1	64✔
412	while i < #fmt do	352✔
413	local ch = fmt:sub(i,i)	288✔
414	local df = formats[ch]	288✔
415	if df then	288✔
416	if used[ch] then error("field appeared twice: "..ch,4) end	184✔
417	used[ch] = true	184✔
418	-- this field may be repeated
419	local _,inext = fmt:find(ch..'+',i+1)	184✔
420	local cnt = not _ and 1 or inext-i+1	184✔
421	if not df[2][cnt] then error("wrong number of fields: "..ch,4) end	184✔
422	-- single chars mean 'accept more than one digit'
423	local p = cnt==1 and (D..PLUS) or (D):rep(cnt)	184✔
424	append(patt,OPENP..p..CLOSEP)	184✔
425	append(vars,ch)	184✔
426	if ch == 'y' then	184✔
427	append(outf,cnt==2 and '%y' or '%Y')	56✔
428	else
429	append(outf,'%'..ch)	128✔
430	end
431	i = i + cnt	184✔
432	else
433	append(patt,ch)	104✔
434	append(outf,ch)	104✔
435	i = i + 1	104✔
436	end
437	end
438	-- escape any magic characters
439	fmt = utils.escape(table.concat(patt))	96✔
440	-- fmt = table.concat(patt):gsub('[%-%.%+%[%]%(%)%$%^%%%?%*]','%%%1')
441	-- replace markers with their magic equivalents
442	fmt = fmt:gsub(D,'%%d'):gsub(PLUS,'+'):gsub(OPENP,'('):gsub(CLOSEP,')')	64✔
443	self.fmt = fmt	64✔
444	self.outf = table.concat(outf)	64✔
445	self.vars = vars	64✔
446	end
447
448	local parse_date
449
450	--- parse a string into a Date object.
451	-- @string str a date string
452	-- @return date object
453	function Date.Format:parse(str)	48✔
454	assert_string(1,str)	216✔
455	if self.plain then	216✔
456	return parse_date(str,self.us)	144✔
457	end
458	local res = {str:match(self.fmt)}	72✔
459	if #res==0 then return nil, 'cannot parse '..str end	72✔
460	local tab = {}	72✔
461	for i,v in ipairs(self.vars) do	280✔
462	local name = formats[v][1] -- e.g. 'y' becomes 'year'	208✔
463	tab[name] = tonumber(res[i])	208✔
464	end
465	-- os.date() requires these fields; if not present, we assume
466	-- that the time set is for the current day.
467	if not (tab.year and tab.month and tab.day) then	72✔
468	local today = Date()	8✔
469	tab.year = tab.year or today:year()	12✔
470	tab.month = tab.month or today:month()	12✔
471	tab.day = tab.day or today:day()	12✔
472	end
473	local Y = tab.year	72✔
474	if Y < 100 then -- classic Y2K pivot	72✔
475	tab.year = Y + (Y < 35 and 2000 or 1999)	24✔
476	elseif not Y then	48✔
477	tab.year = 1970	×
478	end
479	return Date(tab)	72✔
480	end
481
482	--- convert a Date object into a string.
483	-- @param d a date object, or a time value as returned by @{os.time}
484	-- @return string
485	function Date.Format:tostring(d)	48✔
486	local tm
487	local fmt = self.outf	64✔
488	if type(d) == 'number' then	64✔
489	tm = d	×
490	else
491	tm = d.time	64✔
492	if d.utc then	64✔
493	fmt = '!'..fmt	×
494	end
495	end
496	return os_date(fmt,tm)	64✔
497	end
498
499	--- force US order in dates like 9/11/2001
500	function Date.Format:US_order(yesno)	48✔
501	self.us = yesno	×
502	end
503
504	--local months = {jan=1,feb=2,mar=3,apr=4,may=5,jun=6,jul=7,aug=8,sep=9,oct=10,nov=11,dec=12}
505	local months
506	local parse_date_unsafe
507	local function create_months()
508	local ld, day1 = parse_date_unsafe '2000-12-31', {day=1}	12✔
509	months = {}	8✔
510	for i = 1,12 do	104✔
511	ld = ld:last_day()	144✔
512	ld:add(day1)	96✔
513	local mon = ld:month_name():lower()	144✔
514	months [mon] = i	96✔
515	end
516	end
517
518	--[[
519	Allowed patterns:
520	- [day] [monthname] [year] [time]
521	- [day]/[month][/year] [time]
522
523	]]
524
525	local function looks_like_a_month(w)
526	return w:match '^%a+,*$' ~= nil	120✔
527	end
528	local is_number = stringx.isdigit	24✔
529	local function tonum(s,l1,l2,kind)
530	kind = kind or ''	448✔
531	local n = tonumber(s)	448✔
532	if not n then error(("%snot a number: '%s'"):format(kind,s)) end	448✔
533	if n < l1 or n > l2 then	448✔
534	error(("%s out of range: %s is not between %d and %d"):format(kind,s,l1,l2))	16✔
535	end
536	return n	432✔
537	end
538
539	local function parse_iso_end(p,ns,sec)
540	-- may be fractional part of seconds
541	local _,nfrac,secfrac = p:find('^%.%d+',ns+1)	80✔
542	if secfrac then	80✔
543	sec = sec .. secfrac	×
544	p = p:sub(nfrac+1)	×
545	else
546	p = p:sub(ns+1)	120✔
547	end
548	-- ISO 8601 dates may end in Z (for UTC) or [+-][isotime]
549	-- (we're working with the date as lower case, hence 'z')
550	if p:match 'z$' then -- we're UTC!	80✔
551	return sec, {h=0,m=0}	16✔
552	end
553	p = p:gsub(':','') -- turn 00:30 to 0030	64✔
554	local _,_,sign,offs = p:find('^([%+%-])(%d+)')	64✔
555	if not sign then return sec, nil end -- not UTC	64✔
556
557	if #offs == 2 then offs = offs .. '00' end -- 01 to 0100	16✔
558	local tz = { h = tonumber(offs:sub(1,2)), m = tonumber(offs:sub(3,4)) }	32✔
559	if sign == '-' then tz.h = -tz.h; tz.m = -tz.m end	16✔
560	return sec, tz	16✔
561	end
562
563	function parse_date_unsafe (s,US)	21✔
564	s = s:gsub('T',' ') -- ISO 8601	152✔
565	local parts = stringx.split(s:lower())	228✔
566	local i,p = 1,parts[1]	152✔
567	local function nextp() i = i + 1; p = parts[i] end	320✔
568	local year,min,hour,sec,apm
569	local tz
570	local _,nxt,day, month = p:find '^(%d+)/(%d+)'	152✔
571	if day then	152✔
572	-- swop for US case
573	if US then	16✔
574	day, month = month, day	×
575	end
576	_,_,year = p:find('^/(%d+)',nxt+1)	16✔
577	nextp()	24✔
578	else -- ISO
579	year,month,day = p:match('^(%d+)%-(%d+)%-(%d+)')	136✔
580	if year then	136✔
581	nextp()	80✔
582	end
583	end
584	if p and not year and is_number(p) then -- has to be date	180✔
585	if #p < 4 then	24✔
586	day = p	24✔
587	nextp()	36✔
588	else -- unless it looks like a 24-hour time
589	year = true	×
590	end
591	end
592	if p and looks_like_a_month(p) then -- date followed by month	212✔
593	p = p:sub(1,3)	48✔
594	if not months then	32✔
595	create_months()	8✔
596	end
597	local mon = months[p]	32✔
598	if mon then	32✔
599	month = mon	32✔
600	else error("not a month: " .. p) end	×
601	nextp()	32✔
602	end
603	if p and not year and is_number(p) then	172✔
604	year = p	16✔
605	nextp()	16✔
606	end
607
608	if p then -- time is hh:mm[:ss], hhmm[ss] or H.M[am\|pm]	152✔
609	_,nxt,hour,min = p:find '^(%d+):(%d+)'	96✔
610	local ns
611	if nxt then -- are there seconds?	96✔
612	_,ns,sec = p:find ('^:(%d+)',nxt+1)	72✔
613	--if ns then
614	sec,tz = parse_iso_end(p,ns or nxt,sec)	108✔
615	--end
616	else -- might be h.m
617	_,ns,hour,min = p:find '^(%d+)%.(%d+)'	24✔
618	if ns then	24✔
619	apm = p:match '[ap]m$'	16✔
620	else -- or hhmm[ss]
621	local hourmin
622	_,nxt,hourmin = p:find ('^(%d+)')	8✔
623	if nxt then	8✔
624	hour = hourmin:sub(1,2)	12✔
625	min = hourmin:sub(3,4)	12✔
626	sec = hourmin:sub(5,6)	12✔
627	if #sec == 0 then sec = nil end	8✔
628	sec,tz = parse_iso_end(p,nxt,sec)	12✔
629	end
630	end
631	end
632	end
633	local today
634	if year == true then year = nil end	152✔
635	if not (year and month and day) then	152✔
636	today = Date()	60✔
637	end
638	day = day and tonum(day,1,31,'day') or (month and 1 or today:day())	220✔
639	month = month and tonum(month,1,12,'month') or today:month()	216✔
640	year = year and tonumber(year) or today:year()	164✔
641	if year < 100 then -- two-digit year pivot around year < 2035	144✔
642	year = year + (year < 35 and 2000 or 1900)	16✔
643	end
644	hour = hour and tonum(hour,0,apm and 12 or 24,'hour') or 12	184✔
645	if apm == 'pm' then	136✔
646	hour = hour + 12	8✔
647	end
648	min = min and tonum(min,0,59) or 0	176✔
649	sec = sec and tonum(sec,0,60) or 0 --60 used to indicate leap second	156✔
650	local res = Date {year = year, month = month, day = day, hour = hour, min = min, sec = sec}	136✔
651	if tz then -- ISO 8601 UTC time	136✔
652	local corrected = false	32✔
653	if tz.h ~= 0 then res:add {hour = -tz.h}; corrected = true end	40✔
654	if tz.m ~= 0 then res:add {min = -tz.m}; corrected = true end	32✔
655	res.utc = true	32✔
656	-- we're in UTC, so let's go local...
657	if corrected then	32✔
658	res = res:toLocal()	24✔
659	end-- we're UTC!
660	end
661	return res	136✔
662	end
663
664	function parse_date (s)	21✔
665	local ok, d = pcall(parse_date_unsafe,s)	144✔
666	if not ok then -- error	144✔
667	d = d:gsub('.-:%d+: ','')	16✔
668	return nil, d	16✔
669	else
670	return d	128✔
671	end
672	end
673
674	return Date	24✔
675

lunarmodules / Penlight / 478

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous