imported>Trappist the monk at 19:03, 8 February 2021

2021-02-08T19:03:59Z

New page

--[[--------------------------< 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 <value> for inter-language interwiki-link markup. <prefix> must be a MediaWiki-recognized language
code. when these values have the form (without leading colon):
[[<prefix>:link|label]] return label as plain-text
[[<prefix>:link]] return <prefix>: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:
{{cite ... |title=Title access-date=2016-03-17}} -- the first parameter has a value and whitespace separates that value from the missing pipe parameter name
{{cite ... |title=access-date=2016-03-17}} -- 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

<args> an empty k/v table where k is parameter name and v is its value; filled here
<pfargs> args table from the parent frame (the template's parameters)
<class> config.CitationClass from #invoke: (frame)
<sandbox> boolean; true when this function called from ~/CS1/sandbox
<params> 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 {{#invoke:}} 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 {{#invoke:}} TODO: keep?
-- elseif args[k] ~= nil or (k == 'postscript') then -- when args[k] has a value from {{#invoke}} 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,
}

Module:Sandbox/trappist the monk/Parameters - Revision history

imported>Trappist the monk at 19:03, 8 February 2021