app.date - Date and Time API
Date and time formatting and calculations.
Getting the Current Time
app.date.now()
Gets the current Unix timestamp (seconds).
Returns: number - Unix timestamp
local ts = app.date.now() -- 1701234567.123
app.date.nowMs()
Gets the current Unix timestamp (milliseconds).
Returns: number - Millisecond timestamp
local ms = app.date.nowMs() -- 1701234567123
app.date.today()
Gets today’s date string.
Returns: string - YYYY-MM-DD format
local today = app.date.today() -- "2024-12-01"
app.date.time()
Gets the current time string.
Returns: string - HH:mm:ss format
local time = app.date.time() -- "14:30:00"
Formatting
app.date.format(timestamp?, pattern?)
Formats a timestamp.
Parameters:
timestamp(number, optional) - Unix timestamp (defaults to current time)pattern(string, optional) - Format string (default “yyyy-MM-dd HH:mm:ss”)
Returns: string - Formatted date and time
app.date.format() -- "2024-12-01 14:30:00"
app.date.format(nil, "yyyy/MM/dd") -- "2024/12/01"
app.date.format(1701234567) -- "2023-11-29 10:49:27"
app.date.format(1701234567, "HH:mm") -- "10:49"
app.date.parse(dateString, pattern?)
Parses a date string into a timestamp.
Parameters:
dateString(string) - Date stringpattern(string, optional) - Format string (default “yyyy-MM-dd HH:mm:ss”)
Returns: number|nil - Unix timestamp or nil
app.date.parse("2024-12-01 14:30:00") -- 1701434200
app.date.parse("2024/12/01", "yyyy/MM/dd")
app.date.iso(timestamp?)
Returns the date and time in ISO 8601 format.
Parameters:
timestamp(number, optional) - Unix timestamp (defaults to current time)
Returns: string - ISO 8601 format
app.date.iso() -- "2024-12-01T14:30:00Z"
Date Components
app.date.year(timestamp?)
Gets the year.
Parameters:
timestamp(number, optional) - Unix timestamp (defaults to current time)
Returns: number - Year
app.date.year() -- 2024
app.date.month(timestamp?)
Gets the month (1-12).
app.date.month() -- 12
app.date.day(timestamp?)
Gets the day of the month (1-31).
app.date.day() -- 1
app.date.hour(timestamp?)
Gets the hour (0-23).
app.date.hour() -- 14
app.date.minute(timestamp?)
Gets the minute (0-59).
app.date.minute() -- 30
app.date.second(timestamp?)
Gets the second (0-59).
app.date.second() -- 0
app.date.weekday(timestamp?)
Gets the day of the week (1=Sunday, 7=Saturday).
app.date.weekday() -- 1 (Sunday)
app.date.dayOfYear(timestamp?)
Gets the day of the year (1-366).
app.date.dayOfYear() -- 336
Date Calculations
app.date.add(timestamp, value, unit)
Adds time to a date.
Parameters:
timestamp(number) - Base timestampvalue(integer) - Amount (can be negative, must be an integer)unit(string) - Unit: year/years, month/months, week/weeks, day/days, hour/hours, minute/minutes, second/seconds
Returns: number|nil - New timestamp
local now = app.date.now()
app.date.add(now, 1, "days") -- Tomorrow
app.date.add(now, -7, "days") -- 7 days ago
app.date.add(now, 2, "months") -- 2 months later
app.date.diff(timestamp1, timestamp2, unit?)
Calculates the difference between two timestamps.
Parameters:
timestamp1(number) - First timestamptimestamp2(number) - Second timestampunit(string, optional) - Unit (default “seconds”)
Returns: number - Difference
local diff = app.date.diff(ts1, ts2, "days")
-- Returns the difference in days
app.date.startOf(timestamp, unit)
Gets the start of a time unit.
Parameters:
timestamp(number) - Timestampunit(string) - Unit: year, month, week, day, hour, minute
Returns: number|nil - Start timestamp
local startOfDay = app.date.startOf(app.date.now(), "day") -- Today 0:00
local startOfMonth = app.date.startOf(app.date.now(), "month") -- 1st of this month
app.date.endOf(timestamp, unit)
Gets the end of a time unit.
Parameters:
timestamp(number) - Timestampunit(string) - Unit: year, month, week, day, hour, minute
Returns: number|nil - End timestamp
local endOfDay = app.date.endOf(app.date.now(), "day") -- Today 23:59:59
Comparison
app.date.isBefore(timestamp1, timestamp2)
Checks whether timestamp1 is before timestamp2.
Returns: boolean
app.date.isBefore(ts1, ts2) -- true/false
app.date.isAfter(timestamp1, timestamp2)
Checks whether timestamp1 is after timestamp2.
Returns: boolean
app.date.isAfter(ts1, ts2) -- true/false
app.date.isSame(timestamp1, timestamp2, unit?)
Checks whether two timestamps fall within the same time unit.
Parameters:
timestamp1(number)timestamp2(number)unit(string, optional) - Unit (default “day”)
Returns: boolean
app.date.isSame(ts1, ts2, "month") -- Whether in the same month
app.date.isToday(timestamp)
Checks whether a timestamp is today.
app.date.isToday(app.date.now()) -- true
app.date.isWeekend(timestamp)
Checks whether a timestamp falls on a weekend.
app.date.isWeekend(app.date.now()) -- true/false
app.date.isLeapYear(year)
Checks whether a year is a leap year.
app.date.isLeapYear(2024) -- true
Examples
Organize Files by Date
function MyPlugin:handleOrganizeByDate(context)
for _, file in ipairs(context.selectedFiles) do
local modTime = app.file.modificationDate(file)
if modTime then
local dateStr = app.date.format(modTime, "yyyy-MM")
local destDir = app.path.join(context.currentDirectory, dateStr)
if not app.path.exists(destDir) then
app.file.mkdir(destDir)
end
local destPath = app.path.join(destDir, app.path.basename(file))
app.file.move(file, destPath)
end
end
app.notification.show("Done", "Files organized by date")
end
Add Date Stamp
function MyPlugin:handleAddDateStamp(context)
local dateStr = app.date.format(nil, "yyyyMMdd")
for _, file in ipairs(context.selectedFiles) do
local dir = app.path.dirname(file)
local name = app.path.name(file)
local ext = app.path.extension(file)
local newName = name .. "_" .. dateStr
if ext ~= "" then
newName = newName .. "." .. ext
end
local newPath = app.path.join(dir, newName)
app.file.move(file, newPath)
end
end