Modulo:Data
Instruçioìn pe l'ûzoQuésto o l'é 'n mòdolo scrîto in Lua. E instruçioìn chi de sótta són contegnûe inta sotopàgina Modulo:Data/man (modìfica · stöia)
Sandbox: Modulo:Data/sandbox (modìfica · stöia) · Test: Modulo:Data/test (modìfica · stöia · ezegoi)
Modulo per eseguire operazioni sulle date.
Funzioni
diff
Questa funzione ritorna la differenza tra le date inserite tramite i parametri "inizio" e "fine" in una sola unità tra "anni", "mesi", "settimane", "giorni", "ore", "minuti" e "secondi". L'unità può essere specificata tramite il parametro "magnitudine", se non inserito viene utilizzata automaticamente l'unità più adatta. Il formato per le date è quello accettato dalla funzione parser #time.
- Uso
{{#invoke:Data|diff|inizio=data1|fine=data2}}
- Parametri
- inizio: data di partenza
- fine: data di arrivo, può essere successiva o anteriore a inizio, se anteriore verrà anteposto il segno "-" (meno) al risultato.
- magnitudine: l'unità da ritornare nel risultato, tra "anni", "mesi", "settimane", "giorni", "ore", "minuti" e "secondi". Se non inserita è utilizzata automaticamente la più adatta.
- magnitudine min: quando non è utilizzata magnitudine e il modulo utilizza automaticamente l'unità più adatta, serve per configurare l'unità minima da usare. Se per esempio "magnitudine min" viene impostata a "mesi" allora non verranno usate le unità minori (giorni, minuti e secondi) anche se queste fossero le più adatte. È utile quando il modulo è usato in un template: pur non conoscendo a priori le date che verranno utilizzate si può così stabilire una unità minima che verrà visualizzata.
- dir: se impostato a qualunque valore, esempio "dir=sì", nel risultato invece del segno verrà utilizzato il prefisso "tra" se positivo (esempio: "tra 1 mese") o verrà appeso "fa" se negativo (esempio "un mese fa").
- Esempi
{{#invoke:Data|diff|inizio=2016/01/01|fine=2016/02/10}}→ 40 giorni{{#invoke:Data|diff|inizio=2016/01/01|fine=2016/02/10|magnitudine=mesi}}→ 1 mese{{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01}}→ -18 mesi{{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01|magnitudine=anni}}→ -1 anno
Gli stessi esempi con dir=sì:
{{#invoke:Data|diff|inizio=2016/01/01|fine=2016/02/10|dir=sì}}→ tra 40 giorni{{#invoke:Data|diff|inizio=2016/01/01|fine=2016/02/10|magnitudine=mesi|dir=sì}}→ tra 1 mese{{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01|dir=sì}}→ 18 mesi fa{{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01|magnitudine=anni|dir=sì}}→ 1 anno fa
diff_ymd
Questa funzione ritorna la differenza in anni, mesi e giorni tra le date inserite tramite i parametri "inizio" e "fine". Il formato per le date è quello accettato dalla funzione parser #time.
- Uso
{{#invoke:Data|diff_ymd|inizio=data1|fine=data2}}
- Parametri
- inizio: data di partenza
- fine: data di arrivo, può essere successiva o anteriore a inizio, se anteriore verrà anteposto il segno "-" (meno) al risultato.
- dir: se impostato a qualunque valore, esempio "dir=sì", nel risultato invece del segno verrà utilizzato il prefisso "tra" se positivo (esempio: "tra 1 mese e 1 giorno") o verrà appeso "fa" se negativo (esempio "un mese e un giorno fa").
- Esempi
{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2015/01/01}}→ -1 anno{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2017/03/04}}→ 1 anno, 2 mesi e 3 giorni{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2012/12/31}}→ -3 anni e 1 giorno
Gli stessi esempi con dir=sì:
{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2015/01/01|dir=sì}}→ 1 anno fa{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2017/03/04|dir=sì}}→ tra 1 anno, 2 mesi e 3 giorni{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2012/12/31|dir=sì}}→ 3 anni e 1 giorno fa
compare
Questa funzione confronta due date e restituisce 0 se le date sono uguali, -1 se la prima è anteriore alla seconda, altrimenti 1. Il formato per le date è quello accettato dalla funzione parser #time.
- Uso
{{#invoke:Data|compare|data1=prima data|data2=seconda data}}
- Parametri
- data1: la prima data
- data2: la seconda data
- Esempi
{{#invoke:Data|compare|data1=2016/01/01|data2=2016/01/01}}→ 0{{#invoke:Data|compare|data1=2016/01/01|data2=2016/01/10}}→ -1{{#invoke:Data|compare|data1=2016/01/10|data2=2016/01/01}}→ 1
Utilizzo da un altro modulo
Oltre che attraverso #invoke, il modulo può essere utilizzato tramite "require" da un altro modulo. Le stesse funzioni sono disponibili tramite la classe Date:
local Date = require('Modulo:Data').Date
- Esempio
local Date = require('Modulo:Data').Date
local p = {}
function p.main(frame)
local inizio, fine, diff1, diff2, text1, text2, anteriore
inizio = Date:new('2016/01/01')
fine = Date:new('2017/03/04')
-- utilizzo della funzione diff
diff1 = inizio:diff(fine, 'mesi')
-- utilizzo della funzione diff_ymd
diff2 = inizio:diffYMD(fine)
-- data per esteso
text1 = inizio:getDateString()
text2 = fine:getDateString()
-- confronto
anteriore = inizio < fine
return string.format('La differenza tra il %s e il %s è di %s, più precisamente di %s. ' ..
'La prima data è anteriore alla seconda: %s.',
text1, text2, diff1, diff2, tostring(anteriore))
end
return p
Unit test
Unit test per questo modulo sono disponibili a Modulo:Data/test, per la loro esecuzione visitare Discussioni_modulo:Data/test.
--[[
* Modulo per eseguire operazioni sulle date.
* Utilizzato da template come {{Età wikipediana}} e {{Tempo trascorso}}.
]]
require('Modulo:No globals')
local getArgs = require('Modulo:Arguments').getArgs
local errorCategory = '[[Categoria:Voci con errori del modulo Data]]'
-- classe esportata
local Date = {}
-------------------------------------------------------------------------------
-- Funzioni di utilità
-------------------------------------------------------------------------------
-- Error handler per xpcall, formatta l'errore
local function errhandler(msg)
local cat = mw.title.getCurrentTitle().namespace == 0 and errorCategory or ''
return string.format('<span class="error">Errore: %s</span>%s', msg, cat)
end
local function isValidDate(date)
return pcall(function() mw.getContentLanguage():formatDate('', date) end)
end
-- Controlla le date inserite dall'utente e le restituisce come oggetti Date
local function parseArgs(args, isCompare)
local data1, data2, label1, label2
if isCompare then
data1, data2 = 'data1', 'data2'
label1, label2 = 'prima data', 'seconda data'
else
data1, data2 = 'inizio', 'fine'
label1, label2 = 'data di partenza', 'data di fine'
end
if not args[data1] then
error(string.format('la %s è obbligatoria', label1), 2)
elseif not isValidDate(args[data1]) then
error(string.format('la %s non è valida', label1), 2)
elseif not args[data2] then
error(string.format('la %s è obbligatoria', label2), 2)
elseif not isValidDate(args[data2]) then
error(string.format('la %s non è valida', label2), 2)
end
return {
d1 = Date:new(args[data1]),
d2 = Date:new(args[data2])
}
end
-------------------------------------------------------------------------------
-- classe Date
-------------------------------------------------------------------------------
local function date_eq(t, t2)
return t.ut == t2.ut
end
local function date_lt(t, t2)
return t.ut < t2.ut
end
-- Costruisce un oggetto Date a partire da una stringa nel formato
-- accettato dalla funzione parser #time.
function Date:new(str, precision)
local self = {}
setmetatable(self, { __index = Date, __eq = date_eq, __lt = date_lt })
self.ut = tonumber(mw.getContentLanguage():formatDate('U', str, true))
self.precision = precision or 11
return self
end
-- Costruisce un oggetto Date a partire da una stringa nel formato:
-- "giorno mese_per_esteso anno" oppure "mese_per_esteso anno" oppure "anno".
function Date:newDMY(str)
local months = {
gennaio = 1, febbraio = 2, marzo = 3, aprile = 4, maggio = 5, giugno = 6,
luglio = 7, agosto = 8, settembre = 9, ottobre = 10, novembre = 11, dicembre = 12
}
local success, result = pcall(function()
local day, month, year = str:match("(%d+) (%a+) (%d+)")
if day then
return Date:new(string.format('%d-%d-%d', year, months[month], day))
else
month, year = str:match("(%a+) (%d+)")
if month then
return Date:new(string.format('%d-%d', year, months[month]), 10)
else
return Date:new(string.format('%d', str:match("(%d+)")), 9)
end
end
end )
return success and result or nil
end
-- Restituisce una stringa che rappresenta la data, senza l'ora.
function Date:getDateString()
local fmt = self.precision == 9 and 'Y' or
(self.precision == 10 and 'F Y' or
(self.precision == 11 and 'j F Y' or 'j F Y'))
return (mw.getContentLanguage():formatDate(fmt, '@' .. self.ut):gsub('^1%s', '1º '))
end
-- Restituisce un nuovo oggetto Date la cui data è avanzata del numero di giorni specificati.
function Date:addDays(days)
return Date:new('@' .. (self.ut + days * 86400))
end
-- Funzione di utilità per Date:diffYMD e Date:diff
-- Aggiunge un eventuale prefisso e suffisso al risultato invece del segno.
-- L'ultimo parametro diffVal è utilizzato solo da diff per evitare che
-- {{#invoke:Data|diff|inizio=2016/01/01|fine=2015/12/31|magnitudine=anni}} ritorni "-0 anni".
local function formatResult(result, date1, date2, dir, diffVal)
local ret
if dir then
-- ritorna il 'fa' anche con date1.ut == date2.ut (si potrebbe configurare con un parametro)
ret = date1.ut < date2.ut and 'tra ' .. result or result .. ' fa'
else
ret = (date1.ut <= date2.ut or diffVal == 0) and result or '-' .. result
end
return ret
end
-- Restituisce la differenza con la data date2 in anni, mesi e giorni.
function Date:diffYMD(date2, rawTable, dir)
local monthdays = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }
local d1, d2 = os.date('*t', self.ut), os.date('*t', date2.ut)
local ret = { seconds = math.abs(self.ut - date2.ut) }
if self.ut >= date2.ut then d1, d2 = d2, d1 end
-- anni
ret.years = d2.year - d1.year
if ret.years > 0 and (d1.month > d2.month or (d1.month == d2.month and d1.day > d2.day)) then
ret.years = ret.years - 1
end
-- mesi
ret.months = (d2.month - d1.month + 12) % 12
if d1.day > d2.day then
ret.months = (ret.months == 0 and d1.year < d2.year) and 11 or ret.months - 1
end
-- giorni
ret.days = d2.day >= d1.day and d2.day - d1.day or (monthdays[d1.month] - d1.day) + d2.day
-- utilizza la sequence per ritornare anche la versione testuale
if ret.years > 0 then
table.insert(ret, string.format('%s %s', ret.years, ret.years == 1 and 'anno' or 'anni'))
end
if ret.months > 0 then
table.insert(ret, string.format('%s %s', ret.months, ret.months == 1 and 'mese' or 'mesi'))
end
if ret.days > 0 or ret.years + ret.months + ret.days == 0 then
table.insert(ret, string.format('%s %s', ret.days, ret.days == 1 and 'giorno' or 'giorni'))
end
return rawTable and ret or formatResult(mw.text.listToText(ret, ', ', ' e '), self, date2, dir)
end
-- Funzione di utilità per Date:diff
local function getMagnitudine(diff, magnitudine_min)
local units = {
secondi = 0, minuti = 1, ore = 2, giorni = 3, settimane = 4, mesi = 5, anni = 6
}
local ret
if diff.seconds < 120 then -- minore di due minuti
ret = 'secondi'
elseif diff.seconds < 7200 then -- minore di due ore
ret = 'minuti'
elseif diff.seconds < 172800 then -- minore di due giorni
ret = 'ore'
elseif diff.years == 0 and diff.months < 2 then -- minore di due mesi
ret = 'giorni'
elseif diff.years < 2 then -- minore di due anni
ret = 'mesi'
else
ret = 'anni'
end
-- utilizzo di magnitudine_min (il valore minimo quando è automatica)
if magnitudine_min and units[magnitudine_min] then
ret = units[magnitudine_min] > units[ret] and magnitudine_min or ret
end
return ret
end
-- Funzione di utilità per Date:diff
local function convert(seconds, unit, text, text2)
local ret = math.floor(seconds / unit)
return ret, string.format('%s %s', ret, ret == 1 and text or text2)
end
-- Restituisce la differenza con la data d2 in solo una tra le unità:
-- anni, mesi, settimane, giorni, ore, minuti e secondi.
function Date:diff(date2, magnitudine, magnitudine_min, dir)
local diff, ret, val, result
diff = self:diffYMD(date2, true)
magnitudine = magnitudine or getMagnitudine(diff, magnitudine_min)
if magnitudine == 'secondi' then
val, result = convert(diff.seconds, 1, 'secondo', 'secondi')
elseif magnitudine == 'minuti' then
val, result = convert(diff.seconds, 60, 'minuto', 'minuti')
elseif magnitudine == 'ore' then
val, result = convert(diff.seconds, 3600, 'ora', 'ore')
elseif magnitudine == 'giorni' then
val, result = convert(diff.seconds, 86400, 'giorno', 'giorni')
elseif magnitudine == 'settimane' then
val, result = convert(diff.seconds, 604800, 'settimana', 'settimane')
elseif magnitudine == 'mesi' then
val = diff.years * 12 + diff.months
result = string.format('%s %s', val, val == 1 and 'mese' or 'mesi')
else
val = diff.years
result = string.format('%s %s', diff.years, diff.years == 1 and 'anno' or 'anni')
end
return formatResult(result, self, date2, dir, val)
end
-------------------------------------------------------------------------------
-- API
-------------------------------------------------------------------------------
local p = { Date = Date }
-- Entry point per {{#invoke:Data|diff}}
function p.diff(frame)
local args = getArgs(frame)
local success, result = xpcall(function() return parseArgs(args) end, errhandler)
return success and result.d1:diff(result.d2, args.magnitudine, args['magnitudine min'], args.dir) or result
end
-- Entry point per {{#invoke:Data|diff_ymd}}
function p.diff_ymd(frame)
local args = getArgs(frame)
local success, result = xpcall(function() return parseArgs(args) end, errhandler)
return success and result.d1:diffYMD(result.d2, false, args.dir) or result
end
-- Entry point per {{#invoke:Data|compare}}
function p.compare(frame)
local success, result = xpcall(function() return parseArgs(getArgs(frame), true) end, errhandler)
return success and (result.d1 == result.d2 and 0 or ( result.d1 < result.d2 and -1 or 1 )) or result
end
return p