વિભાગ:Citation/CS1/Utilities

local u = {}

local z = {
 error\_categories = {}; -- for categorizing citations that contain errors
 error\_ids = {};
 message\_tail = {};
 maintenance\_cats = {}; -- for categorizing citations that aren't erroneous per se, but could use a little work
 properties\_cats = {}; -- for categorizing citations based on certain properties, language of source for instance
};

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

local cfg; -- table of tables imported from selected Module:Citation/CS1/Configuration

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

Returns true if argument is set; false otherwise. Argument is 'set' when it exists (not nil) or when it is not an empty string.

]]

local function is\_set( var )
 return not (var == nil or var == *);*
end

--[[--------------------------< I N \_ A R R A Y >--------------------------------------------------------------

Whether needle is in haystack

]]

local function in\_array( needle, haystack )
 if needle == nil then
 return false;
 end
 for n,v in ipairs( haystack ) do
 if v == needle then
 return n;
 end
 end
 return false;
end

--[[--------------------------< S U B S T I T U T E >----------------------------------------------------------

Populates numbered arguments in a message string using an argument table.

]]

local function substitute( msg, args )
 return args and mw.message.newRawMessage( msg, args ):plain() or msg;
end

--[[--------------------------< E R R O R \_ C O M M E N T >----------------------------------------------------

Wraps error messages with css markup according to the state of hidden.

]]

local function error\_comment( content, hidden )
 return substitute( hidden and cfg.presentation['hidden-error'] or cfg.presentation['visible-error'], content );
end

--[=[-------------------------< M A K E \_ W I K I L I N K >----------------------------------------------------

Makes a wikilink; when bot link and display text is provided, returns a wikilink in the form D; if only
link is provided, returns a wikilink in the form L; if neither are provided or link is omitted, returns an
empty string.

]=]

local function make\_wikilink (link, display)
 if is\_set (link) then
 if is\_set (display) then
 return table.concat ({'', display, ''});
 else
 return table.concat ({'', link, ''});
 end
 else
 return *;*
 end
end

--[[--------------------------< S E T \_ E R R O R >--------------------------------------------------------------

Sets an error condition and returns the appropriate error message. The actual placement of the error message in the output is
the responsibility of the calling function.

]]

local function set\_error( error\_id, arguments, raw, prefix, suffix )
 local error\_state = cfg.error\_conditions[ error\_id ];

 prefix = prefix or "";
 suffix = suffix or "";

 if error\_state == nil then
 error( cfg.messages['undefined\_error'] ); -- because missing error handler in Module:Citation/CS1/Configuration
 elseif is\_set( error\_state.category ) then
 table.insert( z.error\_categories, error\_state.category );
 end

 local message = substitute( error\_state.message, arguments );

 message = table.concat (
 {
 message,
 ' (',
 make\_wikilink (
 table.concat (
 {
 cfg.messages['help page link'],
 '#',
 error\_state.anchor
 }),
 cfg.messages['help page label']),
 ')'
 });

-- message = table.concat ({message, ' (', substitute (cfg.presentation['wikilink'],
-- {cfg.messages['help page link'] .. '#' .. error\_state.anchor, cfg.messages['help page label']}), ')'});
-- message = message .. " ([[" .. cfg.messages['help page link'] ..
-- "#" .. error\_state.anchor .. "|" ..
-- cfg.messages['help page label'] .. "]])";

 z.error\_ids[ error\_id ] = true;
 if in\_array( error\_id, { 'bare\_url\_missing\_title', 'trans\_missing\_title' } )
 and z.error\_ids['citation\_missing\_title'] then
 return *, false;*
 end

 message = table.concat({ prefix, message, suffix });

 if raw == true then
 return message, error\_state.hidden;
 end

 return error\_comment( message, error\_state.hidden );
end

--[[-------------------------< I S \_ A L I A S \_ U S E D >-----------------------------------------------------

This function is used by select\_one() to determine if one of a list of alias parameters is in the argument list
provided by the template.

Input:
 args – pointer to the arguments table from calling template
 alias – one of the list of possible aliases in the aliases lists from Module:Citation/CS1/Configuration
 index – for enumerated parameters, identifies which one
 enumerated – true/false flag used choose how enumerated aliases are examined
 value – value associated with an alias that has previously been selected; nil if not yet selected
 selected – the alias that has previously been selected; nil if not yet selected
 error\_list – list of aliases that are duplicates of the alias already selected

Returns:
 value – value associated with alias we selected or that was previously selected or nil if an alias not yet selected
 selected – the alias we selected or the alias that was previously selected or nil if an alias not yet selected

]]

local function is\_alias\_used (args, alias, index, enumerated, value, selected, error\_list)
 if enumerated then -- is this a test for an enumerated parameters?
 alias = alias:gsub ('#', index); -- replace '#' with the value in index
 else
 alias = alias:gsub ('#', *); -- remove '#' if it exists*
 end

 if is\_set(args[alias]) then -- alias is in the template's argument list
 if value ~= nil and selected ~= alias then -- if we have already selected one of the aliases
 local skip;
 for \_, v in ipairs(error\_list) do -- spin through the error list to see if we've added this alias
 if v == alias then
 skip = true;
 break; -- has been added so stop looking
 end
 end
 if not skip then -- has not been added so
 table.insert( error\_list, alias ); -- add error alias to the error list
 end
 else
 value = args[alias]; -- not yet selected an alias, so select this one
 selected = alias;
 end
 end
 return value, selected; -- return newly selected alias, or previously selected alias
end

--[[--------------------------< A D D \_ M A I N T \_ C A T >------------------------------------------------------

Adds a category to z.maintenance\_cats using names from the configuration file with additional text if any.
To prevent duplication, the added\_maint\_cats table lists the categories by key that have been added to z.maintenance\_cats.

]]

local added\_maint\_cats = {} -- list of maintenance categories that have been added to z.maintenance\_cats
local function add\_maint\_cat (key, arguments)
 if not added\_maint\_cats [key] then
 added\_maint\_cats [key] = true; -- note that we've added this category
 table.insert( z.maintenance\_cats, substitute (cfg.maint\_cats [key], arguments)); -- make name then add to table
 end
end

--[[--------------------------< S A F E \_ F O R \_ I T A L I C S >----------------------------------------------

Protects a string that will be wrapped in wiki italic markup  *...*

Note: We cannot use  *for italics, as the expected behavior for italics specified by *...* in the title is that
they will be inverted (i.e. unitalicized) in the resulting references. In addition,  *and  *tend to interact*
poorly under Mediawiki's HTML tidy.**

**]]**

**local function safe\_for\_italics( str )
 if not is\_set(str) then
 return str;
 else
 if str:sub(1,1) == "'" then str = "" .. str; end
 if str:sub(-1,-1) == "'" then str = str .. ""; end**

 **-- Remove newlines as they break italics.
 return str:gsub( '\n', ' ' );
 end
end**

 **--[[--------------------------< W R A P \_ S T Y L E >----------------------------------------------------------**

**Applies styling to various parameters. Supplied string is wrapped using a message\_list configuration taking one
argument; protects italic styled parameters. Additional text taken from citation\_config.presentation - the reason
this function is similar to but separate from wrap\_msg().**

**]]**

**local function wrap\_style (key, str)
 if not is\_set( str ) then
 return "";
 elseif in\_array( key, { 'italic-title', 'trans-italic-title' } ) then
 str = safe\_for\_italics( str );
 end**

 **return substitute( cfg.presentation[key], {str} );
end**

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

**Chooses one matching parameter from a list of parameters to consider. The list of parameters to consider is just
names. For parameters that may be enumerated, the position of the numerator in the parameter name is identified
by the '#' so |author-last1= and |author1-last= are represented as 'author-last#' and 'author#-last'.**

**Because enumerated parameter |<param>1= is an alias of |<param>= we must test for both possibilities.**

 **Generates an error if more than one match is present.**

**]]**

**local function select\_one( args, aliases\_list, error\_condition, index )
 local value = nil; -- the value assigned to the selected parameter
 local selected = *; -- the name of the parameter we have chosen*
 local error\_list = {};**

 **if index ~= nil then index = tostring(index); end**

 **for \_, alias in ipairs( aliases\_list ) do -- for each alias in the aliases list
 if alias:match ('#') then -- if this alias can be enumerated
 if '1' == index then -- when index is 1 test for enumerated and non-enumerated aliases
 value, selected = is\_alias\_used (args, alias, index, false, value, selected, error\_list); -- first test for non-enumerated alias
 end
 value, selected = is\_alias\_used (args, alias, index, true, value, selected, error\_list); -- test for enumerated alias
 else
 value, selected = is\_alias\_used (args, alias, index, false, value, selected, error\_list); --test for non-enumerated alias
 end
 end**

 **if #error\_list > 0 and 'none' ~= error\_condition then -- for cases where this code is used outside of extract\_names()
 local error\_str = "";
 for \_, k in ipairs( error\_list ) do
 if error\_str ~= "" then error\_str = error\_str .. cfg.messages['parameter-separator'] end
 error\_str = error\_str .. wrap\_style ('parameter', k);
 end
 if #error\_list > 1 then
 error\_str = error\_str .. cfg.messages['parameter-final-separator'];
 else
 error\_str = error\_str .. cfg.messages['parameter-pair-separator'];
 end
 error\_str = error\_str .. wrap\_style ('parameter', selected);
 table.insert( z.message\_tail, { set\_error( error\_condition, {error\_str}, true ) } );
 end**

 **return value, selected;
end**

 **--[=[-------------------------< R E M O V E \_ W I K I \_ L I N K >----------------------------------------------**

**Gets the display text from a wikilink like B or B gives B**

**The str:gsub() returns either A|B froma B or B from B or B from B (no wikilink markup).**

**In l(), l:gsub() removes the link and pipe (if they exist); the second :gsub() trims white space from the label
if str was wrapped in wikilink markup. Presumably, this is because without wikimarkup in str, there is no match
in the initial gsub, the replacement function l() doesn't get called.**

**]=]**

**local function remove\_wiki\_link (str)
 return (str:gsub( "%[%[([^%[%]]\*)%]%]", function(l)
 return l:gsub( "^[^|]\*|(.\*)$", "%1" ):gsub("^%s\*(.-)%s\*$", "%1");
 end));
end**

 **--[=[-------------------------< I S \_ W I K I L I N K >--------------------------------------------------------**

**Determines if str is a wikilink, extracts, and returns the the wikilink type, link text, and display text parts.
If str is a complex wikilink (D):
 returns wl\_type 2 and D and L from D;
if str is a simple wikilink (D)
 returns wl\_type 1 and D from D and L as empty string;
if not a wikilink:
 returns wl\_type 0, str as D, and L as empty string.**

**trims leading and trailing white space and pipes from L and D ([[L|]] and [[|D]] are accepted by MediaWiki and
treated like D; while [[|D|]] is not accepted by MediaWiki, here, we accept it and return D without the pipes).**

**]=]**

**local function is\_wikilink (str)
 local D, L
 local wl\_type = 2; -- assume that str is a complex wikilink D**

 **L, D = str:match ('%[%[([^|]+)|([^%]]+)%]%]'); -- get L and D from D**

 **if not is\_set (D) then -- if no separate link
 D = str:match ('%[%[([^%]]\*)|\*%]%]'); -- get D from D
 wl\_type = 1;
 end**

 **if not is\_set (D) then -- no wikilink markup
 D = str; -- return the string as D
 wl\_type = 0; -- but say that it is not a wikilink
 end**

 **D = mw.text.trim (D, '%s|'); -- trim white space and pipe characters
 L = L and mw.text.trim (L, '%s|');**

 **return wl\_type, D, L or *;*
end**

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

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

**]]**

**local function set\_selected\_modules (cfg\_table\_ptr)
 cfg = cfg\_table\_ptr;**

**end**

**return { -- return exported functions and tables
 is\_set = is\_set,
 in\_array = in\_array,
 substitute = substitute,
 error\_comment = error\_comment,
 set\_error = set\_error,
 select\_one = select\_one,
 add\_maint\_cat = add\_maint\_cat,
 wrap\_style = wrap\_style,
 safe\_for\_italics = safe\_for\_italics,
 remove\_wiki\_link = remove\_wiki\_link,
 is\_wikilink = is\_wikilink,
 make\_wikilink = make\_wikilink,
 set\_selected\_modules = set\_selected\_modules,
 z = z,
 }**