Module:Auto date formatter: Difference between revisions

Module documentation[view] [edit] [history] [purge]

This module allows non-cs1|2 templates and templates that do not wrap cs1|2 templates to have automatic date formatting according to an article's {{use dmy dates}} or {{use mdy dates}} template. This module obeys date style (long, abbreviated, year initial) specified by the |cs1-dates= parameter. See Template:Use dmy dates § Auto-formatting citation template dates for additional information about |cs1-dates=.

Usage

This module should be invoked from within other citation templates.

For publication dates:

{{#invoke:auto date formatter|pub_date_format|<date>}}

For access and archive dates:

{{#invoke:auto date formatter|access_archive_format|<date>}}

If {{use dmy dates}} or {{use mdy dates}} are present in an article, the above functions return <date> in the format specified by the {{use xxx dates}} template in the style specified by |cs1-dates= if present. This module uses Module:Citation/CS1/Configuration to determine the format and style to apply to dates.

When the article does not have a {{use xxx dates}} template, this module returns <date> as is. If it cannot parse the date, the module will output the date as written. It does not offer warnings or maintenance categories for malformed or unusual dates.

The table below shows how the module would modify several dates on a page with {{use dmy dates|cs1-dates=ly}}:

Example dates as rendered with {{use dmy dates|cs1-dates=ly}}

Date as written	pub_date_format	access_archive_format
31 October 1990
October 31, 1990
31-10-1990
Oct. 31st, 1990
31 de octubre de 1990
Halloween 1990

Adding to a template

Most citation templates on Wikipedia are CS1 or CS2 templates, and they auto-format dates. You can make new citation templates as specific-source templates. Built on existing CS1 templates, they also auto-format dates. This results in consistency with the most used citation templates and reduces the maintenance burden on the specific-source template. For example, {{cite sports-reference}} is based on the widely used {{cite web}} template.

Source types that do not easily map to a CS1 template may have citation templates written from scratch. In these cases, this module can provide similar auto-formatting for dates. For example, {{cite comic}} was not converted to CS1 because of the way it handles authors. When a template is written in wikitext, you can wrap the parameter reference inside an invocation of this module:

Wrapping wikitext

Wikitext	Replacement
{{{date}}}	{{#invoke:Auto date formatter|pub_date_format|{{{date}}}}}
{{{access-date}}}	{{#invoke:Auto date formatter|access_archive_format|{{{access-date}}}}}

Lua modules for non-CS1 templates can access this template from the functions _pub_date_format() and _access_archive_format().

The above documentation is transcluded from Module:Auto date formatter/doc. (edit | history)
Editors can experiment in this module's sandbox (create | mirror) and testcases (create) pages.
Subpages of this module.

require ('strict');

local global_df = mw.loadData ('Module:Citation/CS1/Configuration').global_df;	-- fetch global date format specified by {{use xxx dates}} template

local lang_obj = mw.language.getContentLanguage();								-- function to reformat dates

--[[--------------------------< F O R M A T T E R >------------------------------------------------------------

local function to format <date> according to <format> (dmy or mdy) and <style> (long, short, year initial) as
specified by the |cs1-dates= parameter of the {{use xxx dates}} template.

valid |cs1-dates= format character strings are:
	l, ll, all	– default; long-form publication and access- / archive-dates; 'all' when |cs1-dates= omitted or empty
	ls			– long-form publication dates; abbreviated access- / archive-dates
	ly			– long-form publication dates; year-initial numeric access- / archive-dates (ymd)
	s, ss		– abbreviated publication and access- / archive-dates
	sy			– abbreviated publication dates; year-initial numeric access- / archive-dates (ymd)
	y, yy		– year-initial numeric publication, access- and archive-dates (ymd); overrides base format

note: 'all' is added by get_date_format() in Module:Citation/CS1/Configuration when |cs1-dates= is omitted or empty

]]

local function formatter (date, format, style)
	local function do_format (format_str, date)									-- local function to do the actual formatting
		local good, new_date = pcall (lang_obj.formatDate, lang_obj, format_str, date);			-- attempt to reformat; on success, <good> is boolean true
		return (good and new_date) or date;										-- when <good> is boolean true, return <new_date>; return <date> else
	end

	if 'l' == style then														-- long month-name format
		if 'dmy' == format then
			return do_format ('j F Y', date);
		else																	-- must be mdy
			return do_format ('F j, Y', date);
		end

	elseif 's' == style then													-- abbreviated month-name format
		if 'dmy' == format then
			return do_format ('j M Y', date);
		else																	-- must be mdy
			return do_format ('M j, Y', date);
		end

	else																		--<style> must be 'y', year-initial numeric format; overrides dmy/mdy in <format>
		return do_format ('Y-m-d', date);
	end
end


--[[--------------------------< P U B _ D A T E _ F O R M A T >------------------------------------------------

For publication dates |date=, |publication-date=, etc

	{{#invoke:Sandbox/Trappist the monk/df|pub_date_format|16 March 2025}}

]]

local function pub_date_format (frame)
	if not global_df then
		return date;															-- when article does not have {{use xxx dates}}, abandon
	end

	local date = frame.args[1];													-- <args[1]> is date to be formatted
	
	local base_format = global_df:match ('^(%a%a%a)');							-- get {{use xxx dates}} base date format: 'dmy' or 'mdy'
	local date_style = global_df:match ('^%a%a%a%-(.+)');						-- get |cs1-dates= style modifiers

	if ({['all'] = true, ['ll'] = true, ['l'] = true, ['ls'] = true, ['ly'] = true})[date_style] then	-- default long-form style
		return formatter (date, base_format, 'l');
	elseif ({['s'] = true, ['ss'] = true, ['sy'] = true})[date_style] then		-- abbrviated style
		return formatter (date, base_format, 's');
	else																		-- must be year-initial style; overrides format in <base_format>
		return formatter (date, base_format, 'y');
	end
end


--[[--------------------------< A C C E S S _ A R C H I V E _ F O R M A T >------------------------------------

For access and archive dates |access-date=, |accessdate=, archive-date=, archivedate=

	{{#invoke:Sandbox/Trappist the monk/df|access_archive_format|16 March 2025}}

]]

local function access_archive_format (frame)
	if not global_df then
		return date;															-- when article does not have {{use xxx dates}}, abandon
	end

	local date = frame.args[1];													-- <args[1]> is date to be formatted

	local base_format = global_df:match ('^(%a%a%a)');							-- get {{use xxx dates}} base date format: 'dmy' or 'mdy'
	local date_style = global_df:match ('^%a%a%a%-(.+)');						-- get |cs1-dates= style modifiers

	if ({['all'] = true, ['ll'] = true, ['l'] = true})[date_style] then			-- default long-form style
		return formatter (date, base_format, 'l');
	elseif ({['ls'] = true, ['s'] = true, ['ss'] = true})[date_style] then		-- abbrviated style
		return formatter (date, base_format, 's');
	else																		-- must be year-initial style; overrides format in <base_format>
		return formatter (date, base_format, 'y');
	end
end


--[[--------------------------< E X P O R T S >----------------------------------------------------------------
]]

return {
	pub_date_format = pub_date_format,
	access_archive_format = access_archive_format,
	}