Module:Citation/CS1 explained

require ('strict');

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

each of these counts against the Lua upvalue limit

local validation; -- functions in Module:Citation/CS1/Date_validation

local utilities; -- functions in Module:Citation/CS1/Utilitieslocal z = ; -- table of tables in Module:Citation/CS1/Utilities

local identifiers; -- functions and tables in Module:Citation/CS1/Identifierslocal metadata; -- functions in Module:Citation/CS1/COinSlocal cfg = ; -- table of configuration tables that are defined in Module:Citation/CS1/Configurationlocal whitelist = ; -- table of tables listing valid template parameter names; defined in Module:Citation/CS1/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 fromother modules; that are created here and used here

local added_deprecated_cat; -- Boolean flag so that the category is added only oncelocal added_vanc_errs; -- Boolean flag so we only emit one Vancouver error / categorylocal added_generic_name_errs; -- Boolean flag so we only emit one generic name error / category and stop testing names once an error is encounteredlocal added_numeric_name_errs; -- Boolean flag so we only emit one numeric name error / category and stop testing names once an error is encounteredlocal added_numeric_name_maint; -- Boolean flag so we only emit one numeric name maint category and stop testing names once a category has been emittedlocal Frame; -- holds the module's frame tablelocal is_preview_mode; -- true when article is in preview mode; false when using 'Preview page with this template' (previewing the module)local is_sandbox; -- true when using sandbox modules to render citation

----------------------------< F I R S T _ S E T >------------------------------------------------------------

Locates and returns the first set value in a table of values where the order established in the table,left-to-right (or top-to-bottom), is the order in which the values are evaluated. Returns nil if none are set.

This version replaces the original 'for _, val in pairs do' and a similar version that used ipairs. With the pairsversion the order of evaluation could not be guaranteed. With the ipairs version, a nil value would terminatethe for-loop before it reached the actual end of the list.

local function first_set (list, count) local i = 1; while i <= count do -- loop through all items in list if utilities.is_set(list[i]) then return list[i]; -- return the first set list member end i = i + 1; -- point to next endend

----------------------------< A D D _ V A N C _ E R R O R >----------------------------------------------------

Adds a single Vancouver system error message to the template's output regardless of how many error actually exist.To prevent duplication, added_vanc_errs is nil until an error message is emitted.

added_vanc_errs is a Boolean declared in page scope variables above

local function add_vanc_error (source, position) if added_vanc_errs then return end added_vanc_errs = true; -- note that we've added this category utilities.set_message ('err_vancouver',);end

--

local function is_scheme (scheme) return scheme and scheme:match ('^%a[%a%d%+%.%-]*:'); -- true if scheme is set and matches the patternend

--[=[-------------------------< I S _ D O M A I N _ N A M E >-------------------------------------------------- Does this thing that purports to be a domain name seem to be a valid domain name? Syntax defined here: http://tools.ietf.org/html/rfc1034#section-3.5 BNF defined here: https://tools.ietf.org/html/rfc4234 Single character names are generally reserved; see https://tools.ietf.org/html/draft-ietf-dnsind-iana-dns-01#page-15; see also [[Single-letter second-level domain]]list of TLDs: https://www.iana.org/domains/root/db

RFC 952 (modified by RFC 1123) requires the first and last character of a hostname to be a letter or a digit. Betweenthe first and last characters the name may use letters, digits, and the hyphen.

Also allowed are IPv4 addresses. IPv6 not supported

domain is expected to be stripped of any path so that the last character in the last character of the TLD. tldis two or more alpha characters. Any preceding '//' (from splitting a URL with a scheme) will be strippedhere. Perhaps not necessary but retained in case it is necessary for IPv4 dot decimal.

There are several tests: the first character of the whole domain name including subdomains must be a letter or a digit internationalized domain name (ASCII characters with .xn-- ASCII Compatible Encoding (ACE) prefix xn-- in the TLD) see https://tools.ietf.org/html/rfc3490 single-letter/digit second-level domains in the .org, .cash, and .today TLDs q, x, and z SL domains in the .com TLD i and q SL domains in the .net TLD single-letter SL domains in the ccTLDs (where the ccTLD is two letters) two-character SL domains in gTLDs (where the gTLD is two or more letters) three-plus-character SL domains in gTLDs (where the gTLD is two or more letters) IPv4 dot-decimal address format; TLD not allowed

returns true if domain appears to be a proper name and TLD or IPv4 address, else false

]=]

local function is_domain_name (domain) if not domain then return false; -- if not set, abandon end domain = domain:gsub ('^//', ); -- strip '//' from domain name if present; done here so we only have to do it once if not domain:match ('^[%w]') then -- first character must be letter or digit return false; end

if domain:match ('^%a+:') then -- hack to detect things that look like s:Page:Title where Page: is namespace at Wikisource return false; end

local patterns =

for _, pattern in ipairs (patterns) do -- loop through the patterns list if domain:match (pattern) then return true; -- if a match then we think that this thing that purports to be a URL is a URL end end

for _, d in ipairs (cfg.single_letter_2nd_lvl_domains_t) do -- look for single letter second level domain names for these top level domains if domain:match ('%f[%w][%w]%.' .. d) then return true end end return false; -- no matches, we don't know what this thing isend

----------------------------< I S _ U R L >------------------------------------------------------------------

returns true if the scheme and domain parts of a URL appear to be a valid URL; else false.

This function is the last step in the validation process. This function is separate because there are cases thatare not covered by split_url, for example is_parameter_ext_wikilink which is looking for bracketted externalwikilinks.

local function is_url (scheme, domain) if utilities.is_set (scheme) then -- if scheme is set check it and domain return is_scheme (scheme) and is_domain_name (domain); else return is_domain_name (domain); -- scheme not set when URL is protocol-relative endend

--

local function split_url (url_str) local scheme, authority, domain; url_str = url_str:gsub ('([%a%d])%.?[/%?#].*$', '%1'); -- strip FQDN terminator and path(/), query(?), fragment (#) (the capture prevents false replacement of '//')

if url_str:match ('^//%S*') then -- if there is what appears to be a protocol-relative URL domain = url_str:match ('^//(%S*)') elseif url_str:match ('%S-:/*%S+') then -- if there is what appears to be a scheme, optional authority indicator, and domain name scheme, authority, domain = url_str:match ('(%S-:)(/*)(%S+)'); -- extract the scheme, authority indicator, and domain portions if utilities.is_set (authority) then authority = authority:gsub ('//', , 1); -- replace place 1 pair of '/' with nothing; if utilities.is_set(authority) then -- if anything left (1 or 3+ '/' where authority should be) then return scheme; -- return scheme only making domain nil which will cause an error message end else if not scheme:match ('^news:') then -- except for news:..., MediaWiki won't link URLs that do not have authority indicator; TODO: a better way to do this test? return scheme; -- return scheme only making domain nil which will cause an error message end end domain = domain:gsub ('(%a):%d+', '%1'); -- strip port number if present end return scheme, domain;end

--title-link=, |series-link=, |author-link=, etc. for properly formatted content: no wikilinks, no URLs

Link parameters are to hold the title of a Wikipedia article, so none of the WP:TITLESPECIALCHARACTERS are allowed: # < > [] | _except the underscore which is used as a space in wiki URLs and # which is used for section links

returns false when the value contains any of these characters.

When there are no illegal characters, this function returns TRUE if value DOES NOT appear to be a valid URL (the|-link= parameter is ok); else false when value appears to be a valid URL (the |-link= parameter is NOT ok).

local function link_param_ok (value) local scheme, domain; if value:find ('[<>%[%]|]') then -- if any prohibited characters return false; end

scheme, domain = split_url (value); -- get scheme or nil and domain or nil from URL; return not is_url (scheme, domain); -- return true if value DOES NOT appear to be a valid URLend

---link= value and its matching |