Module:London Gazette util

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

Utility module for {{London Gazette}}

interaction between |supp= and |display-supp=

row	|display-supp=	|supp=	condition	displayed result	url	comment
1	–	–	–	<no supplement display>	/page/	most common non-supplement form
2	–	y	–	Supplement	/supplement/	unnumbered supplement
3	–	##	–	{{{supp}}}<suffix> supplement	/supplement/	specific numbered supplement
4	–	<text>	–		/page/	invalid or out of range
5	none	y	–	<no supplement display>	/supplement/	when page not at /page/ url
6	y	–	–	Supplement	/supplement/	when unnumbered supplement not at /supplement/ url
7	##	–	–	{{{display-supp}}}<suffix> supplement	/page/	when supplement not at /supplement/ url
8	##	y	–	{{{display-supp}}}<suffix> supplement	/supplement/	specific numbered supplement (similar to 3)
9	##	##	{{{supp}}} == {{{display-supp}}}	{{{display-supp}}}<suffix> supplement	/supplement/	|supp= and |display-supp= must agree
10	##	##	{{{supp}}} != {{{display-supp}}}		/supplement/	ambiguous; which supplement number is correct?
11	<text>	–	–	{{{display-supp}}}	/page/	user specified text; not at /supplement/ url
12	<text>	y	–	{{{display-supp}}}	/supplement/	user specified text
13	<text>	##	–	{{{display-supp}}}	/supplement/	user specified text
14	<text>	<text>	–		/supplement/	|supp= invalid or out of range
key
–		parameter is empty or missing; a condition does not apply
##		a number greater than zero and less than 100
<suffix>		the appropriate ordinal suffix: 1st, 2nd, 3rd, 4th, ...
<text>		any characters that are not ## or the letter y (or, for |disp-supp=, not the keyword none)
==		logical equality; the statement A == B is true when A and B hold the same value
!=		logical inequality; the statement A != B is true when A and B hold different values

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

-- this module is created to support {{London Gazette}}

require('Module:No globals')
local getArgs = require('Module:Arguments').getArgs

local span_open = '<span style="font-size:100%; font-weight:normal" class="error">';
local code_style="color:inherit; border:inherit; padding:inherit;";
local help_link = ' ([[Template:London Gazette#error messages|help]])';

local supp_error = span_open .. 'invalid <code style="'..code_style..'">&#124;supp=</code>' .. help_link .. '</span>';

local startpage_ignored_error = ' ' .. span_open .. '<code style="'..code_style..'">&#124;startpage=</code> ignored' .. help_link .. '</span>';
local endpage_ignored_error = ' ' .. span_open .. '<code style="'..code_style..'">&#124;endpage=</code> ignored' .. help_link .. '</span>';

local start_end_page_ignored_error = ' ' .. span_open .. '<code style="'..code_style..'">&#124;startpage=</code> and <code style="'..code_style..'">&#124;endpage=</code> ignored' .. help_link .. '</span>';

local endpage_error = ' ' .. span_open .. '<code style="'..code_style..'">&#124;endpage=</code> requires <code style="'..code_style..'">&#124;startpage=</code>' .. help_link .. '</span>';
local duplicate_page_error = ' ' .. span_open .. 'more than one of <code style="'..code_style..'">&#124;page=</code> and <code style="'..code_style..'">&#124;pages=</code>' .. help_link .. '</span>';

local p = {}

--[[--------------------------< I S _ S E T >------------------------------------------------------------------

Whether variable is set or not.  A variable is set when it is not nil and not empty.

]]

local function is_set( var )
	return not (var == nil or var == '');
end


--[[--------------------------< C I T Y >----------------------------------------------------------------------

sets the city element of the url path according to |city= value; defaults to London

]]

local function city (city_param)
	local city_names = {['b'] = 'Belfast', ['belfast'] = 'Belfast', ['e'] = 'Edinburgh', ['edinburgh'] = 'Edinburgh'};
	
	if is_set (city_param) then
		city_param = city_param:lower();										-- lower() to index into the city_names table
	end
	
	return city_names[city_param] or 'London';									-- the city, or default to London
end

	
--[[--------------------------< O R D I N A L _ S U F F I X >--------------------------------------------------

render a numerical text string in ordinal form suitable for English language use.  In this module, num_str is
limited by calling functions to the integer values 1-99.

TODO: use Module:Ordinal instead?

]]

local function ordinal_suffix (num_str)
	local lsd;																	-- least significant digit
	local suffixes = {['1'] = 'st', ['2'] = 'nd', ['3'] = 'rd'};				-- table of suffixes except 'th'

	if num_str:match ('^1[1-3]$') then											-- check the 11-13 odd balls first to get them out of the way
		return num_str .. 'th';													-- 11th, 12th, 13th
	end
	
	lsd = num_str:match ('^%d?(%d)$');											-- all other numbers, get the least significant digit
	return num_str .. (suffixes[lsd] or 'th');									-- append the suffix from the suffixes table or default to 'th'
end


--[[--------------------------< P A G E _ O R _ S U P P L E M E N T >------------------------------------------

sets the page/supplement element of the url path according to |supp= value; defaults to page

Only limited |supp= values will set the page/supplement path element to /supplement/.  These are: 'y', 'yes', a number 1-99

]]

local function page_or_supplement (supp_param)
	if not is_set (supp_param) then
		return 'page';															-- default value
	end
	
	supp_param = supp_param:lower();											--make sure lower case for comparisons
	
	if ('y' == supp_param) or ('yes' == supp_param) or supp_param:match ('^%d%d?$') then
		return 'supplement';
	else
		return 'page';															-- anything else
	end
end

	
--[[--------------------------< M A K E _ P A G E _ P A R A M >------------------------------------------------

Determine the value to be assigned to the specified cs1|2 |page= or |pages= parameter in {{London Gazette}}.
The arguments |param=page and |param=pages specify which of the cs1|2 parameters |page= or |pages= for which this
function is to create a value.

This function inspects the content of the various |startpage= (or {{{2|}}}), |endpage=, |page=, and |pages= parameters,
along with the |param= specifier.  From this information it creates a value appropriate for the specified |page=
or |pages= parameter.  Only one will have a value, the other will get an empty string.

This function is called twice; once for each of |page= and |pages=:
	|page={{#invoke:Gazette util|make_page_param|param=page|startpage={{{startpage|{{{2|}}}}}}|endpage={{{endpage|}}}|page={{{page|}}}|pages={{{pages|}}}}}
	|pages={{#invoke:Gazette util|make_page_param|param=pages|startpage={{{startpage|{{{2|}}}}}}|endpage={{{endpage|}}}|page={{{page|}}}|pages={{{pages|}}}}}

except for the lvalue and the rvalue assigned to |param=, the two calls must be identical else odd results.

|page= or |pages= without a comma, hyphen, or en dash separator → |page=
|page= or |pages= with a separator → |pages=
|startpage= without |endpage= → |page=
|startpage= with |endpage= → |pages=

Hyphen separator characters are converted to en dash characters.  Any white space around hyphen and en dash
separators is removed.

|page= or |pages= parameters have priority over |startpage= and |endpage=.  If both |page= and |pages= are
set, this function mimics cs1|2 and chooses |page=.

Another function, page_error() is required for error messaging because we don't want to dump css markup into a
parameter value that will be included in the cs1|2 metadata.

]]

function p.make_page_param (frame)
	local args = getArgs(frame);
	local page_or_pages;

	page_or_pages = args.page or args.pages;									-- only one; prefer |page=
	
	if is_set (page_or_pages) then
		if 'pages' == args.param then
			if page_or_pages:match ('[,%-–]') then								-- only for |pages= parameter
				page_or_pages = mw.ustring.gsub (page_or_pages, '%s*[%-–]%s*', '–');	-- hyphen to en dash; remove spaces
				return page_or_pages;											-- has separator character so make the parameter |pages=
			else
				return '';														-- no separator so value will be assigned to |page=
			end
		elseif 'page' == args.param then
			if page_or_pages:match ('[,%-–]') then								-- only for |pages= parameter
				return '';														-- has separator so value will be assigned to |pages=
			else
				return page_or_pages;											-- no separator character so make the parameter |page=
			end
		else
			return '';															-- |param= something else
		end
	end
	
	if is_set (args.startpage) then
		if 'pages' == args.param then											-- if this call is for the |pages= parameter
			if is_set (args.endpage) then										-- only for |pages= parameter
				return args.startpage .. '–' .. args.endpage;					-- make |pages= value from |startpage= and |endpage=
			else
				return '';														-- |startpage= will be assigned to |page= 
			end
		elseif 'page' == args.param then										-- |param=page
			if is_set (args.endpage) then										-- only for |pages= parameter
				return '';														-- |endpage= will be part of |pages= 
			else
				return args.startpage;											-- make |page= value from |startpage=
			end
		else
			return '';															-- |param= something else
		end
	end
	
	return '';																	-- if here no pagination or not for correct |page= or |pages= parameter
end


--[[--------------------------< P A G E _ E R R O R >----------------------------------------------------------

Inspect page number parameters and return an error message that will be appended to the end of the {{cite magazine}}
template rendering.  Error messages are handled this way so that the error message is not made part of the cs1|2
citation's metadata.

{{#invoke:Gazette util|page_error|startpage={{{startpage|}}}|endpage={{{endpage|}}}|page={{{page|}}}|pages={{{pages|}}}|unnamed={{{2|}}}}}

]]

function p.page_error (frame)
	local args = getArgs(frame);

	if is_set (args.page) and is_set (args.pages) then
		return duplicate_page_error;											-- more than one of |page= and |pages=
	elseif (is_set (args.page) or is_set (args.pages)) and is_set (args.startpage) and is_set (args.endpage) then
		return start_end_page_ignored_error;									-- mix of page or pages and startpage and endpage

	elseif is_set (args.startpage) and (is_set (args.page) or is_set (args.pages)) then
		return startpage_ignored_error;											-- mix of startpage and page or pages
	elseif is_set (args.endpage) and (is_set (args.page) or is_set (args.pages)) then
		return endpage_ignored_error;											-- mix of endpage and page or pages
	elseif (not is_set (args.startpage) and not is_set (args.unnamed)) and is_set (args.endpage) then
		return endpage_error;													-- |endpage= requires |startpage=
	else
		return '';
	end
end


--[[--------------------------< T Y P E _ P A R A M >----------------------------------------------------------

set the value that is assigned to the cite magazine |type= parameter using the values of the London Gazette
|supp= and |display-supp= parameters

row numbers in comments apply to the table in Template_talk:London_Gazette#Rewrite_as_wrapper_around_template:cite_news

]]

function p.type_param (frame)
	local args = getArgs(frame);
	
	if not is_set (args['display-supp']) and not is_set (args.supp) then		-- when both |display-supp= and |supp= are not set
		return '';																-- [row 1] not a supplement so no display
	end
	
	if not is_set (args['display-supp']) and is_set (args.supp) then			-- when only |supp= is set
		if ('y' == args.supp:lower()) or ('yes' == args.supp:lower()) then
			return 'Supplement';												-- [row 2] the first or only supplement
		elseif args.supp:match ('^%d%d?$') then									-- one or two digits
			if '1' == args.supp then
				return 'Supplement';											-- [row 3] the first or only supplement; a legacy value TODO:deprecate this use?
			else
				return ordinal_suffix (args.supp) .. ' supplement';				-- [row 4] for the 2nd-99th supplement
			end
		else
			return supp_error;													-- [row 5] any other text not supported show an error message
		end
	end

	if is_set (args['display-supp']) and not is_set (args.supp) then			-- when only |display-supp= is set
		if args['display-supp']:match ('^%d%d?$') then							-- one or two digits
			return ordinal_suffix (args['display-supp']) .. ' supplement';		-- [row 6] for the 1st-99th supplement
		else
			return args['display-supp'];										-- [row 10] user specified text; supplement is not in supplement space (a Gazette website error)
		end
	end
																				-- here when both |display-supp= and |supp= are set
	if args['display-supp']:match ('^%d%d?$') then								-- supplement number
		if ('y' == args.supp:lower()) or ('yes' == args.supp:lower()) or (args['display-supp'] == args.supp) then
			return ordinal_suffix (args['display-supp']) .. ' supplement';		-- [rows 7, 8]
		else																	-- |supp= is not a number or number isn't same as number in |display-supp=
			return supp_error;													-- [row 9] different values are ambiguous
		end
	else																		-- not a supplement number
		if ('y' == args.supp) or ('yes' == args.supp) or (args['display-supp'] == args.supp) then
			return args['display-supp'];										-- [rows 11, 12] user specified text
		else
			return supp_error;													-- [row 13] any other text not supported show an error message
		end
	end
end


--[[--------------------------< U R L _ P A R A M >------------------------------------------------------------

Build a url given |city=, |issue=, |supp=, and one of |page=, |pages=, |startpage=, or {{{2}}}; result is assigned
to |url=

|url={{#invoke:Gazette util|url_param|city={{{city|}}}|issue={{{issue|{{{1|}}} }}}|supp={{{supp|}}}|startpage={{{startpage|}}}|page={{{page|}}}|pages={{{pages|}}}|unnamed={{{2|}}}}}

]]

function p.url_param (frame)
	local args = getArgs(frame);
	local pg = args.page or args.page or args.startpage or args.unnamed or '';	-- first set parameter or empty string
	
	pg = (pg and mw.text.trim (pg):match ('^%d*')) or '';						-- unnamed might have extraneous spaces; digits only; if not digit then empty string for concatenation
	
	local url_table = {															-- a table of the various url parts
		'https://www.thegazette.co.uk',											-- static domain name
		city (args.city),														-- default to London
		'issue',																-- static path text
		mw.text.trim (args.issue),												-- issue number; trim because {{{1|}}} won't be trimmed
		page_or_supplement (args.supp),											-- either of /page/ or /supplement/ according to the state of |supp=
--		(args.pg and args.pg:match ('^%d*')) or ''								-- digits only; if not digit then empty string for concatenation
		pg								-- digits only; if not digit then empty string for concatenation
		};
	
	return table.concat (url_table, '/');										-- concatenate all of the parts together and done
end


return p;