Module:Sandbox/trappist the monk/Parameters

----< F O R W A R D  D E C L A R A T I O N S >--

local in_array, is_set, is_wikilink, make_sep_list, select_one, set_message, substitute, wrap_style;			-- functions in Module:Citation/CS1/Utilities

local z;																		-- table of tables defined in Module:Citation/CS1/Utilities

local cfg;																		-- table of configuration tables that are defined in Module:Citation/CS1/Configuration local suggestions; local whitelist;

--[[--< P A G E  S C O P E   V A R I A B L E S >--

declare variables here that have page-wide scope that are not brought in from other modules; that are created here and used here

]]

local added_deprecated_cat;														-- boolean flag so that the category is added only once local added_vanc_errs;															-- boolean flag so we only emit one Vancouver error / category local Frame;																	-- holds the module's frame table

--[[--< I S _ V A L I D _ P A R A M E T E R _ V A L U E >--

!!! TODO : MOVE from main to TO UTILITIES !!! used here by namelists_get

This function is used to validate a parameter's assigned value for those parameters that have only a limited number of allowable values (yes, y, true, live, dead, etc.). When the parameter value has not been assigned a value (missing or empty in the source template) the function returns the value specified by ret_val. If the parameter value is one of the list of allowed values returns the translated value; else, emits an error message and returns the value specified by ret_val.

]]

local function is_valid_parameter_value (value, name, possible, ret_val) if not is_set (value) then return ret_val;															-- an empty parameter is ok	elseif in_array (value, possible) then return cfg.keywords_xlate[value];										-- return translation of parameter keyword else table.insert( z.message_tail, {set_message ('err_invalid_param_val', {name, value}, true)});	-- not an allowed value so add error message return ret_val; end end

--[[--< S E L E C T _ A U T H O R _ E D I T O R _ S O U R C E >

Select one of |authors=, |authorn= / |lastn / firstn=, or |vauthors= as the source of the author name list or select one of |editorn= / editor-lastn= / |editor-firstn= or |veditors= as the source of the editor name list.

Only one of these appropriate three will be used. The hierarchy is: |authorn= (and aliases) highest and |authors= lowest;
 * editorn= (and aliases) highest and |veditors= lowest (support for |editors= withdrawn)

When looking for |authorn= / |editorn= parameters, test |xxxxor1= and |xxxxor2= (and all of their aliases); stops after the second test which mimicks the test used in extract_names when looking for a hole in the author name list. There may be a better way to do this, I just haven't discovered what that way is.

Emits an error message when more than one xxxxor name source is provided.

In this function, vxxxxors = vauthors or veditors; xxxxors = authors as appropriate.

]]

local function select_author_editor_source (vxxxxors, xxxxors, args, list_name) local lastfirst = false; if select_one ( args, cfg.aliases[list_name .. '-Last'], 'none', 1 ) or		-- do this twice in case we have a |first1= without a |last1=; this ... select_one ( args, cfg.aliases[list_name .. '-First'], 'none', 1 ) or		-- ... also catches the case where |first= is used with |vauthors= select_one ( args, cfg.aliases[list_name .. '-Last'], 'none', 2 ) or select_one ( args, cfg.aliases[list_name .. '-First'], 'none', 2 ) then lastfirst = true; end

if (is_set (vxxxxors) and true == lastfirst) or					-- these are the three error conditions (is_set (vxxxxors) and is_set (xxxxors)) or		(true == lastfirst and is_set (xxxxors)) then local err_name; if 'AuthorList' == list_name then									-- figure out which name should be used in error message err_name = 'author'; else err_name = 'editor'; end table.insert( z.message_tail, {set_message ( 'err_redundant_parameters', {err_name .. '-name-list parameters'}, true ) } );				-- add error message end

if true == lastfirst then return 1 end;										-- return a number indicating which author name source to use if is_set (vxxxxors) then return 2 end; if is_set (xxxxors) then return 3 end; return 1;																	-- no authors so return 1; this allows missing author name test to run in case there is a first without last end

--[[--< N A M E L I S T S _ G E T >

]]

local function namelists_get (params) local author_etal; local a	= {};																-- authors list from |lastn= / |firstn= pairs or |vauthors= local Authors;

local NameListStyle = is_valid_parameter_value (params['NameListStyle'].value, params['NameListStyle'].origin, cfg.keywords_lists['name-list-style'], '');

do																			-- to limit scope of selected local selected = select_author_editor_source (A['Vauthors'], A['Authors'], args, 'AuthorList'); if 1 == selected then a, author_etal = extract_names (args, 'AuthorList');				-- fetch author list from |authorn= / |lastn= / |firstn=, |author-linkn=, and |author-maskn= elseif 2 == selected then NameListStyle = 'vanc';											-- override whatever |name-list-style= might be			a, author_etal = parse_vauthors_veditors (args, args.vauthors, 'AuthorList');	-- fetch author list from |vauthors=, |author-linkn=, and |author-maskn= elseif 3 == selected then Authors = A['Authors'];												-- use content of |authors= if 'authors' == A:ORIGIN('Authors') then							-- but add a maint cat if the parameter is |authors= set_message ('maint_authors');						-- because use of this parameter is discouraged; what to do about the aliases is a TODO: end end if is_set (params['Collaboration'].value) then author_etal = true;													-- so that |display-authors=etal not required end end

local Others = A['Others'];

local editor_etal; local e	= {};																-- editors list from |editor-lastn= / |editor-firstn= pairs or |veditors= local Editors;

do																			-- to limit scope of selected local selected = select_author_editor_source (A['Veditors'], nil, args, 'EditorList');	-- support for |editors= withdrawn if 1 == selected then e, editor_etal = extract_names (args, 'EditorList');				-- fetch editor list from |editorn= / |editor-lastn= / |editor-firstn=, |editor-linkn=, and |editor-maskn= elseif 2 == selected then NameListStyle = 'vanc';												-- override whatever |name-list-style= might be			e, editor_etal = parse_vauthors_veditors (args, args.veditors, 'EditorList');	-- fetch editor list from |veditors=, |editor-linkn=, and |editor-maskn= end end

local translator_etal; local t = {};																-- translators list from |translator-lastn= / translator-firstn= pairs local Translators;															-- assembled translators name list t = extract_names (args, 'TranslatorList');									-- fetch translator list from |translatorn= / |translator-lastn=, -firstn=, -linkn=, -maskn=

local interviewer_etal; local interviewers_list = {}; local Interviewers;															-- used later interviewers_list = extract_names (args, 'InterviewerList');				-- process preferred interviewers parameters

local contributor_etal; local c = {};																-- contributors list from |contributor-lastn= / contributor-firstn= pairs local Contributors;															-- assembled contributors name list

local Chapter = A['Chapter'];												-- done here so that we have access to |contribution= from |chapter= aliases local Chapter_origin = A:ORIGIN ('Chapter'); local Contribution;															-- because contribution is required for contributor(s) if 'contribution' == A:ORIGIN ('Chapter') then Contribution = A['Chapter'];										-- get the name of the contribution end

if in_array (config.CitationClass, {"book", "citation"}) and not is_set (A['Periodical']) then	-- |contributor= and |contribution= only supported in book cites c = extract_names (args, 'ContributorList');							-- fetch contributor list from |contributorn= / |contributor-lastn=, -firstn=, -linkn=, -maskn= if 0 < #c then if not is_set (Contribution) then							-- |contributor= requires |contribution= table.insert( z.message_tail, {set_message ( 'err_contributor_missing_required_param', 'contribution')});	-- add missing contribution error message c = {};															-- blank the contributors' table; it is used as a flag later end if 0 == #a then														-- |contributor= requires |author= table.insert( z.message_tail, {set_message ( 'err_contributor_missing_required_param', 'author')});	-- add missing author error message c = {};															-- blank the contributors' table; it is used as a flag later end end else																		-- if not a book cite if select_one (args, cfg.aliases['ContributorList-Last'], 'err_redundant_parameters', 1 ) then	-- are there contributor name list parameters? table.insert( z.message_tail, {set_message ( 'err_contributor_ignored')});	-- add contributor ignored error message end Contribution = nil;														-- unset end end

--[[--< D E P R E C A T E D _ P A R A M E T E R >--

Categorize and emit an error message when the citation contains one or more deprecated parameters. The function includes the offending parameter name to the error message. Only one error message is emitted regardless of the number of deprecated parameters in the citation.

added_deprecated_cat is a Boolean declared in page scope variables above

]]

local function deprecated_parameter(name) if not added_deprecated_cat then added_deprecated_cat = true;											-- note that we've added this category table.insert (z.message_tail, {set_message ('err_deprecated_params', {name}, true)});	-- add error message end end

--[[--< B U I L D _ P A R A M _ L I S T >--

builds a k/v table where k is the metaparameter name (same as key in aliases{} table) and v is a k/v table where: ['value'] = value assigned to the parameter ['origin'] = original parameter name ['render'] = empty string that will later hold parameter rendered value

]]

local function build_param_list (args, params) --	local params = {}; local val; local selected; for mparam, aliases in pairs (cfg.aliases) do								-- spin through the aliases table (in ~/Configuration) --error (mw.dumpObject (aliases))

if 'table' == type (aliases) then										-- if there are multiple possible parameters val, selected = select_one (args, aliases, 'err_redundant_parameters', 1);	-- select one of them if not selected then												-- TODO: is this even possible? selected = '';													 -- Empty string, not nil end elseif aliases ~= nil then												-- not nil so must be a single parameter name val = args[aliases];												-- get the assigned value selected = aliases;													-- and the parameter name else																	-- here when aliases is nil error( cfg.messages['unknown_argument_map'] .. ': ' .. k);			-- throw a major error because no key end if val then params[mparam] = {value=val, origin=selected, render=''};			-- when parameter has a value, add it to params{} table end end --error (mw.dumpObject (params)) return params; end

--[[--< H A S _ I N V I S I B L E _ C H A R S >

This function searches a parameter's value for non-printable or invisible characters. The search stops at the first match.

This function will detect the visible replacement character when it is part of the Wikisource.

Detects but ignores nowiki and math stripmarkers. Also detects other named stripmarkers (gallery, math, pre, ref) and identifies them with a slightly different error message. See also coins_cleanup.

Output of this function is an error message that identifies the character or the Unicode group, or the stripmarker that was detected along with its position (or, for multi-byte characters, the position of its first byte) in the parameter value.

]]

local function has_invisible_chars (param, v)	local position = '';														-- position of invisible char or starting position of stripmarker local dummy;																-- end of matching string; not used but required to hold end position when a capture is returned local capture;																-- used by stripmarker detection to hold name of the stripmarker local i = 1; local stripmarker, apostrophe; capture = string.match (v, '[%w%p ]*');										-- test for values that are simple ASCII text and bypass other tests if true if capture == v then														-- if same there are no Unicode characters return; end

while cfg.invisible_chars[i] do		local char = cfg.invisible_chars[i][1]									-- the character or group name local pattern = cfg.invisible_chars[i][2]									-- the pattern used to find it		position, dummy, capture = mw.ustring.find (v, pattern)					-- see if the parameter value contains characters that match the pattern if position and (char == 'zero width joiner') then						-- if we found a zero-width joiner character if mw.ustring.find (v, cfg.indic_script) then						-- it's ok if one of the Indic scripts position = nil;													-- unset position end end if position then if 'nowiki' == capture or 'math' == capture or						-- nowiki and math stripmarkers (not an error condition) ('templatestyles' == capture and in_array (param, {'id', 'quote'})) then	-- templatestyles stripmarker allowed in these parameters stripmarker = true;											-- set a flag elseif true == stripmarker and 'delete' == char then				-- because stripmakers begin and end with the delete char, assume that we've found one end of a stripmarker position = nil;													-- unset else local err_msg; if capture then err_msg = capture .. ' ' .. char; else err_msg = char .. ' ' .. 'character'; end

table.insert (z.message_tail, {set_message ('err_invisible_char', {err_msg, wrap_style ('parameter', param), position}, true)});	-- add error message return;															-- and done with this parameter end end i = i + 1;																-- bump our index end end

--[[--< V A L I D A T E >--

Looks for a parameter's name in one of several whitelists.

Parameters in the whitelist can have three values: true - active, supported parameters false - deprecated, supported parameters nil - unsupported parameters ]]

local function validate (name, cite_class, empty) local name = tostring (name); local enum_name;															-- for enumerated parameters, is name with enumerator replaced with '#' local state; local function state_test (state, name)										-- local function to do testing of state values if true == state then return true; end									-- valid actively supported parameter if false == state then if empty then return nil; end										-- deprecated empty parameters are treated as unknowns deprecated_parameter (name);										-- parameter is deprecated but still supported return true; end return nil; end

if name:find ('#') then														-- # is a cs1|2 reserved character so parameters with # not permitted return nil; end

if in_array (cite_class, whitelist.preprint_template_list) then	-- limited parameter sets allowed for these templates state = whitelist.limited_basic_arguments[name]; if true == state_test (state, name) then return true; end

state = whitelist.preprint_arguments[cite_class][name];					-- look in the parameter-list for the template identified by cite_class if true == state_test (state, name) then return true; end

-- limited enumerated parameters list enum_name = name:gsub ("%d+", "#");										-- replace digit(s) with # (last25 becomes last#) (mw.ustring because non-Western 'local' digits) state = whitelist.limited_numbered_arguments[enum_name]; if true == state_test (state, name) then return true; end

return false;															-- not supported because not found or name is set to nil end																			-- end limited parameter-set templates

if in_array (cite_class, whitelist.unique_param_template_list) then 	-- experiment for template-specific parameters for templates that accept parameters from the basic argument list state = whitelist.unique_arguments[cite_class][name];					-- look in the template-specific parameter-lists for the template identified by cite_class if true == state_test (state, name) then return true; end end																			-- if here, fall into general validation state = whitelist.basic_arguments[name];									-- all other templates; all normal parameters allowed if true == state_test (state, name) then return true; end

-- all enumerated parameters allowed enum_name = name:gsub ("%d+", "#");											-- replace digit(s) with # (last25 becomes last#) (mw.ustring because non-Western 'local' digits) state = whitelist.numbered_arguments[enum_name]; if true == state_test (state, name) then return true; end

return false;																-- not supported because not found or name is set to nil end

--[=[-< I N T E R _ W I K I _ C H E C K >--

check for inter-language interwiki-link markup. must be a MediaWiki-recognized language code. when these values have the form (without leading colon): label return label as plain-text :link return :link as plain-text

return value as is else

]=]

local function inter_wiki_check (parameter, value) local prefix = value:match ('%[%[(%a+):');									-- get an interwiki prefix if one exists local _; if prefix and cfg.inter_wiki_map[prefix:lower] then						-- if prefix is in the map, needs preceding colon so		table.insert (z.message_tail, {set_message ('err_bad_paramlink', parameter)});	-- emit an error message _, value, _ = is_wikilink (value);							-- extract label portion from wikilink end return value; end

--[[--< M I S S I N G _ P I P E _ C H E C K >--

Look at the contents of a parameter. If the content has a string of characters and digits followed by an equal sign, compare the alphanumeric string to the list of cs1|2 parameters. If found, then the string is possibly a parameter that is missing its pipe. There are two tests made: -- the first parameter has a value and whitespace separates that value from the missing pipe parameter name -- the first parameter has no value (whitespace after the first = is trimmed by MediaWiki) cs1|2 shares some parameter names with XML/HTML attributes: class=, title=, etc. To prevent false positives XML/HTML tags are removed before the search.

If a missing pipe is detected, this function adds the missing pipe maintenance category.

]]

local function missing_pipe_check (parameter, value) local capture; value = value:gsub ('%b<>', '');											-- remove XML/HTML tags because attributes: class=, title=, etc.

capture = value:match ('%s+(%a[%w%-]+)%s*=') or value:match ('^(%a[%w%-]+)%s*=');	-- find and categorize parameters with possible missing pipes if capture and validate (capture) then										-- if the capture is a valid parameter name table.insert (z.message_tail, {set_message ('err_missing_pipe', parameter)}); end end

--[[--< H A S _ E X T R A N E O U S _ P U N C T >--

look for extraneous terminal punctuation in most parameter values; parameters listed in skip table are not checked

]]

local function has_extraneous_punc (param, value) if 'number' == type (param) then return; end param = param:gsub ('%d+', '#');											-- enumerated name-list mask params allow terminal punct; normalize if cfg.punct_skip[param] then return;																	-- parameter name found in the skip table so done end if value:match ('[,;:]$') then set_message ('maint_extra_punct');							-- has extraneous punctuation; add maint cat end end

--[[--< A R G S _ G E T >--

get arguments from template frame, do validation and some error checking

an empty k/v table where k is parameter name and v is its value; filled here args table from the parent frame (the template's parameters) config.CitationClass from #invoke: (frame) boolean; true when this function called from ~/CS1/sandbox an empty k/v table filled by build_param_list

]]

local function args_get (args, pfargs, class, sandbox, params) local suggestions = {};														-- table where we store suggestions if we need to loadData them local empty_unknowns = {};													-- sequence table of empty unknown parameter names local error_text, error_state;

local capture;																-- the single supported capture when matching unknown parameters using patterns

for k, v in pairs (pfargs) do												-- get parameters from the parent (template) frame v = mw.ustring.gsub (v, '^%s*(.-)%s*$', '%1');							-- trim leading/trailing whitespace; when v is only whitespace, becomes empty string if v ~= '' then if ('string' == type (k)) then k = mw.ustring.gsub (k, '%d', cfg.date_names.local_digits);		-- for enumerated parameters, translate 'local' digits to Western 0-9 end if not validate (k, class) then error_text = ""; if type (k) ~= 'string' then -- exclude empty numbered parameters if v:match ("%S+") ~= nil then error_text, error_state = set_message ('err_text_ignored', {v}, true); end elseif validate (k:lower, class) then error_text, error_state = set_message ('err_parameter_ignored_suggest', {k, k:lower}, true);	-- suggest the lowercase version of the parameter else if nil == suggestions.suggestions then						-- if this table is nil then we need to load it --						if nil ~= string.find (frame:getTitle, 'sandbox', 1, true) then			-- did the use sandbox version? if sandbox then suggestions = mw.loadData ('Module:Citation/CS1/Suggestions/sandbox');	-- use the sandbox version else suggestions = mw.loadData ('Module:Citation/CS1/Suggestions');			-- use the live version end end for pattern, param in pairs (suggestions.patterns) do		-- loop through the patterns to see if we can suggest a proper parameter capture = k:match (pattern);							-- the whole match if no capture in pattern else the capture if a match if capture then											-- if the pattern matches param = substitute (param, capture);				-- add the capture to the suggested parameter (typically the enumerator) if validate (param, class) then		-- validate the suggestion to make sure that the suggestion is supported by this template (necessary for limited parameter lists) error_text, error_state = set_message ('err_parameter_ignored_suggest', {k, param}, true);	-- set the suggestion error message else error_text, error_state = set_message ('err_parameter_ignored', {param}, true);	-- suggested param not supported by this template v = '';											-- unset end end end if not is_set (error_text) then					-- couldn't match with a pattern, is there an explicit suggestion? if suggestions.suggestions[ k:lower ] ~= nil then error_text, error_state = set_message ('err_parameter_ignored_suggest', {k, suggestions.suggestions[ k:lower ]}, true); else error_text, error_state = set_message ('err_parameter_ignored', {k}, true); v = '';												-- unset value assigned to unrecognized parameters (this for the limited parameter lists) end end end if error_text ~= '' then table.insert (z.message_tail, {error_text, error_state}); end end

args[k] = v;														-- save this parameter and its value

elseif not is_set (v) then												-- for empty parameters if not validate (k, class, true) then				-- is this empty parameter a valid parameter k = ('' == k) and '(empty string)' or k;						-- when k is empty string (or was space(s) trimmed to empty string), replace with descriptive text; TODO: i18n table.insert (empty_unknowns, wrap_style ('parameter', k));		-- format for error message and add to the list end -- crude debug support that allows us to render a citation from module TODO: keep? --	elseif args[k] ~= nil or (k == 'postscript') then						-- when args[k] has a value from frame (we don't normally do that) --		args[k] = v;														-- overwrite args[k] with empty string from pframe.args[k] (template frame); v is empty string here end																		-- not sure about the postscript bit; that gets handled in parameter validation; historical artifact? end

if 0 ~= #empty_unknowns then												-- create empty unknown error message table.insert (z.message_tail, {set_message ('err_param_unknown_empty', { 1 == #empty_unknowns and '' or 's', make_sep_list (#empty_unknowns, empty_unknowns) }, true)}); end for k, v in pairs( args ) do		if 'string' == type (k) then											-- don't evaluate positional parameters has_invisible_chars (k, v);											-- look for invisible characters end has_extraneous_punc (k, v);												-- look for extraneous terminal punctuation in parameter values missing_pipe_check (k, v);												-- do we think that there is a parameter that is missing a pipe? args[k] = inter_wiki_check (k, v);										-- when language interwiki-linked parameter missing leading colon replace with wiki-link label end params = build_param_list (args, params); return args, params; end

--[[--< S E T _ S E L E C T E D _ M O D U L E S >--

Sets local cfg table and imported functions table to same (live or sandbox) as that used by the other modules.

]]

local function set_selected_modules (cfg_table_ptr, utilities_page_ptr, whitelist_page_ptr) cfg = cfg_table_ptr; whitelist = whitelist_page_ptr; --	has_accept_as_written = utilities_page_ptr.has_accept_as_written;			-- import functions from select Module:Citation/CS1/Utilities module in_array = utilities_page_ptr.in_array; is_set = utilities_page_ptr.is_set; is_wikilink = utilities_page_ptr.is_wikilink; make_sep_list = utilities_page_ptr.make_sep_list set_message = utilities_page_ptr.set_message; select_one = utilities_page_ptr.select_one; substitute = utilities_page_ptr.substitute; --	make_wikilink = utilities_page_ptr.make_wikilink; wrap_style = utilities_page_ptr.wrap_style;

z = utilities_page_ptr.z;													-- table of tables in Module:Citation/CS1/Utilities end

----< E X P O R T E D  F U N C T I O N S >--

return { args_get = args_get, has_extraneous_punc = has_extraneous_punc, has_invisible_chars = has_invisible_chars, inter_wiki_check = inter_wiki_check, missing_pipe_check = missing_pipe_check, set_selected_modules = set_selected_modules, validate = validate, }