fix(snippets): specify date format with arg and add type annots (#16)

lua/neorg/modules/external/templates/default_snippets.lua

@@ -18,7 +18,7 @@ local m = require("luasnip.extras").m
 local lambda = require("luasnip.extras").l
 local postfix = require("luasnip.extras.postfix").postfix
 local neorg = require("neorg.core")
-local utils = neorg.utils
+local utils, log = neorg.utils, neorg.log
 
 local snippets, autosnippets = {}, {}
 local e = function(trig, name, dscr, wordTrig, regTrig, docstring, docTrig, hidden, priority)
@@ -47,40 +47,78 @@ local M = {
     },
 }
 
-M.parse_date = function(delta_date, str_or_date)
+---Convert time object into string with specified format.
+---@param delta_date integer # Shift x number of days from `str_or_date`. (-1 means yesterday)
+---@param str_or_date string|integer # osdate object or string representing date with `YYYY-mm-dd`.
+---@param date_format string? # date format. If nil, `M.date_format` will be used.
+---@return string # string representing the date.
+M.parse_date = function(delta_date, str_or_date, date_format)
+    if date_format == nil then
+        date_format = M.date_format
+    end
     if type(str_or_date) ~= "string" then
-        str_or_date = os.date(M.date_format, str_or_date)
+        local result = os.date(date_format, str_or_date + 86400 * delta_date)
+        assert(type(result) == "string", "Neorg Template: Something went wrong in `parse_date`. Please open an issue.")
+        return result
+    else
+        local year, month, day = string.match(str_or_date, [[^(%d%d%d%d)-(%d%d)-(%d%d)$]])
+        local result = os.date(date_format, os.time({ year = year, month = month, day = day }) + 86400 * delta_date)
+        assert(type(result) == "string", "Neorg Template: Something went wrong in `parse_date`. Please open an issue.")
+        return result
     end
-    local year, month, day = string.match(str_or_date, [[^(%d%d%d%d)-(%d%d)-(%d%d)$]])
-    return os.date(M.date_format, os.time({ year = year, month = month, day = day }) + 86400 * delta_date)
 end
 
-M.current_date = function(delta_day)
-    return os.date(M.date_format, os.time() + 86400 * delta_day)
+---Return string of date relative to today.
+---@param delta_date integer # Shift x number of days from `str_or_date`. (-1 means yesterday)
+---@param date_format string? # date format. If nil, `M.date_format` will be used.
+---@return string # string representing the date.
+M.current_date = function(delta_date, date_format)
+    return M.parse_date(delta_date, os.time(), date_format)
 end
 
+---Basename stem of current file. `fnamemodify(..., ":t:r")`
+---@return string # stem of current file (foo/bar.txt -> bar).
 M.file_title = function()
     return vim.fn.fnamemodify(vim.api.nvim_buf_get_name(0), ":t:r")
 end
 
-M.ostime = function(year, month, day)
+---Alias to `os.time` by specifying year, month, date as arguments. If any of fields are nil, returns today's time instead.
+---@param year integer?
+---@param month integer?
+---@param day integer?
+---@return integer # ostime object
+M.make_time_object = function(year, month, day)
     if year == nil or month == nil or day == nil then
         return os.time()
     end
     return os.time({ year = year, month = month, day = day })
 end
 
+---@deprecated Use `make_time_object` instead.
+---@param year integer?
+---@param month integer?
+---@param day integer?
+---@return integer
+M.ostime = function(year, month, day)
+    log.warn("Neorg Template: DEPRECATED: `ostime` has been renamed to `make_time_object`.")
+    return M.make_time_object(year, month, day)
+end
+
+---Extract date object from current file tree generated by journal module. (2000/04/01.norg -> os.time(2000, 4, 1))
+---@return integer # ostime object
 M.file_tree_date = function()
     local f_name = vim.api.nvim_buf_get_name(0)
     local grandparent = vim.fn.fnamemodify(f_name, ":p:h:h:h") or ""
     local date_path = vim.fn.fnamemodify(f_name:sub(grandparent:len() + 2):gsub([[\]], "/"), ":r") or ""
     local year, month, day = string.match(date_path, [[^(%d%d%d%d)/(%d%d)/(%d%d)$]])
-    return M.ostime(year, month, day)
+    return M.make_time_object(year, month, day)
 end
 
+---Extract date object from current file name generated by journal module. (2000-04-01.norg -> os.time(2000, 4, 1))
+---@return integer # ostime object
 M.file_name_date = function()
     local year, month, day = string.match(M.file_title() or "", [[^(%d%d%d%d)-(%d%d)-(%d%d)$]])
-    return M.ostime(year, month, day)
+    return M.make_time_object(year, month, day)
 end
 
 ---Parse url and return service name based on domain