Module:Cite archive: Difference between revisions

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

Implements {{Cite archive}}

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

require('strict')
local f = {};
local code_style="color:inherit; border:inherit; padding:inherit;";				-- used in styling error messages

local lock_icons = {															--icon classes are defined in Module:Citation/CS1/styles.css
	['free'] = {'cs1-lock-free', 'Freely accessible'},
	['registration'] = {'cs1-lock-registration', 'Free registration required'},
	['limited'] = {'cs1-lock-limited', 'Free access subject to limited trial, subscription normally required'},
	['subscription'] = {'cs1-lock-subscription', 'Paid subscription required'},
	}


--[[--------------------------< 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


--[[--------------------------< S E L E C T _ O N E >----------------------------------------------------------

Choose one parameter value from a list of parameter values.  If more than one is set, emit error message.

]]

local function select_one (list, args)
	local selected_param;
	local selected_val='';

	for param, value in pairs (list) do										-- loop through the list
		if not is_set (selected_param) then										-- if we have not yet selected a parameter value
			if is_set (value) then												-- is this value set?
				selected_val = value;											-- select it
				selected_param = param;											-- remember the name for possible error message
			end
		else
			if is_set (value) then												-- error message if we have selected and found another set parameter
				args.err_msg = string.format (
					' more than one of <code style="%s">|%s=</code> and <code style="%s">|%s=</code>',
					code_style, selected_param, code_style, param
				)
				break;
			end
		end
	end
	return selected_val or '';															-- return selected value or empty string if none set
end


--[[--------------------------< M A K E _ N A M E >------------------------------------------------------------

Assembles last, first, link, or mask into a displayable author name.

]]

local function make_name (last, first, link, mask)
	local name = last;
	
	if is_set (first) then
		name = name .. ', ' .. first;											-- concatenate first onto last
	end
	
	if is_set (link) then
		name = '[[' .. link .. '|' .. name .. ']]';								-- form a wikilink around the name
	end
	
	if is_set (mask) then														-- mask this author
		mask = tonumber (mask);													-- because the value provided might not be a number
		if is_set (mask) then
			name = string.rep ('—', mask)										-- make a string that number length of mdashes
		end
	end
	
	return name;
end


--[[-------------------------< M A K E _ A U T H O R _ L I S T >----------------------------------------------

form the authors display list:
	if |display-authors= is empty or omitted, display is similar to cs1|2: display all names in last, first order 
	if |display-authors=etal then displays all author names in last, first order and append et al.
	if value assigned to |display-authors= is less than the number of author last names, displays the specified number of author names in last, first order followed by et al.

]]

local function make_author_list (args, number_of_authors)
	local authors = '';
	local i = 1;
	local count;
	local etal = false;															-- when |display-authors= is same as number of authors in contributor list
	
	if is_set (args.display_authors) then
		if 'etal' == args.display_authors:lower():gsub("[ '%.]", '') then		-- the :gsub() portion makes 'etal' from a variety of 'et al.' spellings and stylings
			count = number_of_authors;											-- display all authors and ...
			etal = true;														-- ... append 'et al.'
		else
			count = tonumber (args.display_authors) or 0;						-- 0 if can't be converted to a number
			if 0 >= count then
				args.err_msg = string.format ('%s invalid <code style="%s">|display-authors=</code>; ', args.err_msg, code_style);
--				args.err_msg = args.err_msg .. ' invalid |display-authors=';	-- if zero, then emit error message
				count = number_of_authors;										-- and display all authors
			end
		end
		if count > number_of_authors then
			count = number_of_authors;											-- when |display-authors= is more than the number of authors, use the number of authors
		end
		if count < number_of_authors then										-- when |display-authors= is less than the number of authors
			etal = true;														-- append 'et al.'
		end
	else
		count = number_of_authors;												-- set count to display all of the authors
	end
	
	while i <= count do
		if is_set (authors) then
			authors = authors .. '; ' .. make_name (args.last[i], args.first[i], args.link[i], args.mask[i]);	-- the rest of the authors
		else
			authors = make_name (args.last[i], args.first[i], args.link[i], args.mask[i]);	-- first author's name
		end
		i = i+1;																-- bump the index
	end
	if true == etal then
		authors = authors .. '; et al.';										-- append et al.
	elseif 'yes' == args.last_author_amp then
		authors = authors:gsub('; ([^;]+)$', ' & %1')							-- replace last separator with ' & '
	end

--	if args.sepc ~= authors:sub(-1) and args.sepc .. ']]' ~= authors:sub(-3) then
--		authors = authors;											-- add separator if not same as last character in name list (|first=John S. or et al.)
--	end
																				-- TODO: better way to handle wikilink case?
	authors = authors:gsub ('%' .. args.sepc .. '$', '', 1);					-- remove trailing separator character
	authors = authors:gsub ('%' .. args.sepc .. ']]$', ']]', 1);				-- remove trailing separator character inside wikilink

	return authors;
end


--[[--------------------------< M A K E _ I T E M >------------------------------------------------------------

This function formats |item= and, if present, |item-url= into the linked part and if present appends |date= and
|type= with appropriate markup to complete the item portion of the citation.  This function assumes that item
has a value when it is called.

]]

local function make_item (item, url, item_date, item_type, item_access)
	local output = {};															-- table of item bits
	if is_set (url) then
		item = string.format ('[%s %s]', url, item);							-- make item into an external wikilink
	end
	if item_access and ('subscription' == item_access or 'registration' == item_access) then
		table.insert (output, table.concat ({									-- opening quote mark then add access icon markup to this item
						'"<span class="',										-- open the opening span tag; icon classes are defined in Module:Citation/CS1/styles.css
						lock_icons[item_access][1],								-- add the appropriate lock icon class
						'" title="',											-- and the title attribute
						lock_icons[item_access][2],								-- for an appropriate tool tip
						'">',													-- close the opening span tag
						item,
						'</span>"',												-- and close the span and close the quote
					}));
	else
		table.insert (output, string.format ('"%s"', item));					-- enclose in quotes and add to table
	end
	if is_set (item_date) then
		table.insert (output, string.format ('(%s)', item_date));				-- enclose in parentheses and add to table
	end
	if is_set (item_type) then
		table.insert (output, string.format ('[%s]', item_type));				-- enclose in square brackets and add to table
	end
	
	return table.concat (output, ' ');											-- concatenate with space as separator
end


--[[--------------------------< M A K E _ C O L L E C T I O N >------------------------------------------------

This function formats |collection= and, if present, |collection-url= into the linked part and if present, appends
the values from |fonds=, |series=, |box=, |file=, |itemid=, and |page= or |pages= to complete the collection
portion of the citation.  This function assumes that collection has a value when it is called (because that is one
of the two required parameters)

]]

local function make_collection (args)
	local output = {};															-- table of collections bits
	local collection = args.collection;
	if is_set (args.collectionURL) then
		collection = string.format ('[%s %s]', args.collectionURL, collection);				-- make collection into an external wikilink
	end
	table.insert (output, string.format ('%s', collection));					-- enclose in quotes and add to table
	if is_set (args.fonds) then
		table.insert (output, string.format ('Fonds: %s', args.fonds));			-- format and add to table
	end
	if is_set (args.series) then
		table.insert (output, string.format ('Series: %s', args.series));		-- format and add to table
	end
	if is_set (args.box) then
		table.insert (output, string.format ('Box: %s', args.box));				-- format and add to table
	end
	if is_set (args.file) then
		table.insert (output, string.format ('File: %s', args.file));			-- format and add to table
	end
	if is_set (args.itemID) then
		table.insert (output, string.format ('ID: %s', args.itemID));				-- format and add to table
	end
	
	if is_set (args.p) then
		table.insert (output, string.format ('%s%s', args.page_sep, args.p));
	elseif is_set (args.pp) then
		table.insert (output, string.format ('%s%s', args.pages_sep, args.pp));
	end      
 
 	if is_set (args.p) and is_set (args.pp) then
		args.err_msg = string.format ('%s more than one of <code style="%s">|page=</code> and <code style="%s">|pages=</code>; ', args.err_msg, code_style, code_style);
	end
 
	return table.concat (output, ', ');											-- concatenate with comma space as separator
end


--[[--------------------------< M A K E _ L O C A T I O N >----------------------------------------------------

This function formats |location=, |repository, and |institution= into the location portion of the citation.
This function assumes that |institution= (a required parameter) has a value when it is called.

Unlike other groups of parameters, the required parameter is the 'last' and separator characters are not all the same.

]]

local function make_location (location, repository, institution)
	local output = {};															-- table of location bits
	if is_set (location) then
		location = string.format ('%s: ', location);							-- format
	end
	if is_set (repository) then
		table.insert (output, repository);										-- and add to table
	end
	table.insert (output, institution);											-- and add to table
	
	return string.format ('%s%s', location, table.concat (output, ', '));		-- concatenate with comma space separators
end


--[[--------------------------< M A K E _ I D E N T I F I E R S >----------------------------------------------

This function formats |oclc= and |accession into the identifiers portion of the citation.  Neither of these
parameters are required.

]]

local function make_identifiers (args)
	local output = {};															-- table ofidentifier bits
	if is_set (args.oclc) then
		table.insert (output, string.format ('[[OCLC]]&nbsp;[https://www.worldcat.org/oclc/ %s]', args.oclc));
	end
	if is_set (args.accession) then
		table.insert (output, args.accession);
	end
	return table.concat (output, args.sepc .. ' ');								-- concatenate with sepc space as separator
end


--[[--------------------------< _ C I T E _ A R C H I V E >----------------------------------------------------

Assembles the various parts provided by the template into a properly formatted citation.  Adds punctuation
and text; encloses the whole within a cite tag with id and class attributes.

This creates a CITEREF anchor from |last1= through |last4= and the year portion of |date= when |ref=harv.

]]

local function _cite_archive (args)
	local cite_open_tag;														-- holds CITEREF and css
	local authors = '';															-- list of authors
	local identifiers = '';														-- OCLC and accession identifiers list
	local result = {};															-- the assembly of the citation's output

-- form the anchor ID
	if is_set (args.ref) and 'none' ~= args.ref and 'harv' ~= args.ref then		-- |ref= has a value that is not 'none' and not 'harv' so use that value as the anchor ID
		cite_open_tag = '<cite id="' .. args.ref .. '" class="citation archive">';
	elseif 0 ~= #args.citeref and 'none' ~= args.ref then						-- there is an author list and |ref= has a value that is not 'none' so create a CITEREF anchor
		cite_open_tag = '<cite id="CITEREF' .. table.concat (args.citeref) .. args.year .. '" class="citation archive">';
	else
		cite_open_tag = '<cite class="citation archive">';						-- no author list or |ref=none; no anchor ID
	end

	if 0 ~= #args.last then														-- if there are author names
		table.insert (result, make_author_list (args, #args.last));				-- assemble author name list and add to result table
	end
	
	if is_set (args.item) then													-- if there is an item
		table.insert (result, make_item (args.item, args.itemURL, args.date, args.type, args.item_access));	-- build the item portion of the citation
	end

	table.insert (result, make_collection (args));								-- build the collection portion of the citation (|collection= is required)

	table.insert (result, make_location (args.location, args.repository, args.institution));	-- build the location portion of the citation (institution= is required)

	identifiers = make_identifiers (args);										-- build the identifiers (oclc and accession) portion of the citation
	if is_set (identifiers) then
		table.insert (result, identifiers);
	end

	if is_set (args.accessdate) then
		table.insert (result, args.retrieved .. args.accessdate);
	end

--	wrap error messages in span and add help link
	if is_set (args.err_msg) then
		args.err_msg = '<span class="cs1-visible-error citation-comment"> cite archive:' .. args.err_msg .. ' ([[Template:cite archive|help]])</span>';
	end

-- and put it all together and be done
	return string.format ('%s%s%s</cite>%s', cite_open_tag, table.concat (result, args.sepc .. ' '), args.ps, args.err_msg);
end


--[[--------------------------< F . C I T E _ A R C H I V E >--------------------------------------------------

Entry point from {{cite archive}} template.  Fetches parent frame parameters, does a bit of simple error checking
and calls _cite_archive() if required parameters are present.

]]

function f.cite_archive (frame)
	local args = {
		err_msg = '',
		page_sep = "p.&nbsp;",													-- cs1|2 style page(s) prefixes
		pages_sep = "pp.&nbsp;",
		retrieved = 'Retrieved ',												-- cs1 style access date static text
		sepc = '.',																-- default to cs1 stylre
		ps = '.',																-- default to cs1 stylre
		last = {},																-- table of author last name values
		first = {},																-- table of author first name values
		link = {},																-- table of author link values
		mask = {},																-- table of author mask values
		citeref = {}															-- table of last names that will be used in making the CITEREF anchor
		}

	local pframe = frame:getParent();											-- get template's parameters

	args.item = pframe.args.item or '';											-- these are the 'item' group
	args.itemURL = pframe.args['item-url'] or '';
	args.item_access = pframe.args['item-url-access'];
	args.type = pframe.args.type or '';
	args.date = pframe.args.date or '';

	args.year = args.date:match ('%d%d%d%d') or '';								-- used in creation of the CITEREF anchor

	args.collection = pframe.args.collection or '';								-- these are the collection group
	args.collectionURL = pframe.args['collection-url'] or '';
	args.fonds = pframe.args.fonds or '';
	args.series = pframe.args.series or '';
	args.file = pframe.args.file or '';
	args.box = pframe.args.box or '';
	args.itemID = pframe.args['item-id'] or '';
	args.p = pframe.args.page or pframe.args.p or '';							-- if both are set, the singular is rendered
	args.pp = pframe.args.pages or pframe.args.pp or '';

	args.repository = pframe.args.repository or '';								-- these are the location group
	args.location = pframe.args.location or '';
	args.institution = pframe.args.institution or '';							-- required parameter

	args.oclc = pframe.args.oclc or '';											-- these are the identifiers group
	args.accession = pframe.args.accession or '';
	
	if not is_set (args.collection) then										-- check for required parameters
		args.err_msg = string.format (' <code style="%s">|collection=</code> required; ', code_style);
	end
	if not is_set (args.institution) then
		args.err_msg = string.format ('%s <code style="%s">|institution=</code> required; ', args.err_msg, code_style);
	end
	
	if is_set (args.err_msg) then												-- if set here, then we are missing one or both required parameters so quit
		return '<span class="cs1-visible-error citation-comment">cite archive:' .. args.err_msg .. ' ([[Template:cite archive|help]])</span>';	-- with an error message
	end

																				-- standard cs1|2 parameters
	args.accessdate = pframe.args['access-date'] or pframe.args.accessdate or '';

	args.ref = pframe.args.ref or '';
		
	args.display_authors = pframe.args['display-authors'];						-- the number of author names to display
	args.last_author_amp = pframe.args['last-author-amp'] or					-- yes only; |last-author-amp=no does not work
				pframe.args['lastauthoramp'] or '';
	args.last_author_amp:lower();												-- make it case agnostic
	
	if is_set (pframe.args['last1']) or is_set (pframe.args['last']) or
		is_set (pframe.args['author1']) or is_set (pframe.args['author']) then	-- must have at least this to continue
		
		args.last[1] = select_one ({											-- get first author's last name
			['last']=pframe.args.last,
			['last1'] = pframe.args.last1,
			['author'] = pframe.args.author,
			['author1'] = pframe.args.author1}, args);
		args.citeref[1] = args.last[1];											-- add it to the citeref

		args.first[1] = select_one ({											-- get first author's first name
			['first'] = pframe.args.first,
			['first1'] = pframe.args.first1}, args);
		args.link[1] = select_one ({											-- get first author's article link
			['author-link'] = pframe.args['author-link'],
			['author-link1'] = pframe.args['author-link1']}, args);
		args.mask[1] = select_one ({											-- get first author's mask
			['author-mask'] = pframe.args['author-mask'],
			['author-mask1'] = pframe.args['author-mask1']}, args);
	
		local i = 2;															-- index for the rest of the names
		while is_set (pframe.args['last'..i]) or is_set (pframe.args['author'..i]) do		-- loop through pframe.args and get the rest of the names
			args.last[i] = pframe.args['last'..i] or pframe.args['author'..i];				-- last names
			args.first[i] = pframe.args['first'..i];							-- first names
			args.link[i] = pframe.args['author-link'..i];						-- author-links
			args.mask[i] = pframe.args['author-mask'..i];						-- author-masks
			if 5 > i then
				args.citeref[i] = args.last[i];									-- collect first four last names for CITEREF anchor
			end
			i = i + 1															-- bump the index
		end
	end

	if 'cs2' == pframe.args.mode then
		args.ps = '';															-- set postscript character to empty string, cs2 mode
		args.sepc = ',';														-- set separator character to comma, cs2 mode
		args.retrieved = args.retrieved:lower();
	end

	return table.concat ({
		frame:extensionTag ('templatestyles', '', {src='Module:Citation/CS1/styles.css'}),	-- add template styles for access icons and .citation
		_cite_archive (args)													-- go render the citation
		});
end

return f;