Module:Sandbox/Awesome Aasim/CS1 LDoc Test

--- This module implements all of the {{tl|citation}} and related templates.

--

-- @author Trappist_the_monk

-- @release stable

-- @module citation

-- @alias p

--

--[[

History of changes since last sync: 2024-12-28

2025-01-05: add module entry points; see Help_talk:Citation_Style_1/Archive_97#Module_support_edit_req

2025-01-15: tighten protocol-relative url-in-title test; see Help_talk:Citation_Style_1#Double_slash_%28but_not_URL%29_in_title_causes_cite_web_to_think_title_contains_URL

2025-02-27: emit error message when isbn present for pre-1965 pub date; see Help_talk:Citation_Style_1#isbn_and_pre-isbn_publication_dates

]]

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/Utilities

local z = {}; -- table of tables in Module:Citation/CS1/Utilities

local identifiers; -- functions and tables in Module:Citation/CS1/Identifiers

local metadata; -- functions in Module:Citation/CS1/COinS

local cfg = {}; -- table of configuration tables that are defined in Module:Citation/CS1/Configuration

local 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 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 added_generic_name_errs; -- Boolean flag so we only emit one generic name error / category and stop testing names once an error is encountered

local added_numeric_name_errs; -- Boolean flag so we only emit one numeric name error / category and stop testing names once an error is encountered

local added_numeric_name_maint; -- Boolean flag so we only emit one numeric name maint category and stop testing names once a category has been emitted

local 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

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

-- version the order of evaluation could not be guaranteed. With the ipairs version, a nil value would terminate

-- the for-loop before it reached the actual end of the list.

--

-- @param {table} list

-- @param {number} count

-- @return first set list member

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

end

end

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

--

-- @param source Source of error

-- @param position Position of error

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', {source, position});

end

--- Does this thing that purports to be a URI scheme seem to be a valid scheme? The scheme is checked to see if it

-- is in agreement with http://tools.ietf.org/html/std66#section-3.1 which says:

-- Scheme names consist of a sequence of characters beginning with a

-- letter and followed by any combination of letters, digits, plus

-- ("+"), period ("."), or hyphen ("-").

--

-- @param {string} scheme URI scheme to test

-- @return true if the scheme is valid, else false

local function is_scheme (scheme)

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

end

--- 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. Between

-- the 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. tld

-- is two or more alpha characters. Any preceding '//' (from splitting a URL with a scheme) will be stripped

-- here. 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

--

-- @param {string} domain domain URL

-- @return 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 = { -- patterns that look like URLs

'%f[%w][%w][%w%-]+[%w]%.%a%a+$', -- three or more character hostname.hostname or hostname.tld

'%f[%w][%w][%w%-]+[%w]%.xn%-%-[%w]+$', -- internationalized domain name with ACE prefix

'%f[%a][qxz]%.com$', -- assigned one character .com hostname (x.com times out 2015-12-10)

'%f[%a][iq]%.net$', -- assigned one character .net hostname (q.net registered but not active 2015-12-10)

'%f[%w][%w]%.%a%a$', -- one character hostname and ccTLD (2 chars)

'%f[%w][%w][%w]%.%a%a+$', -- two character hostname and TLD

'^%d%d?%d?%.%d%d?%d?%.%d%d?%d?%.%d%d?%d?', -- IPv4 address

'[%a%d]+%:?' -- IPv6 address

}

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 is

end

--- This function is the last step in the validation process. This function is separate because there are cases that

-- are not covered by split_url(), for example is_parameter_ext_wikilink() which is looking for bracketted external

-- wikilinks.

--

-- @param {string} scheme URI scheme

-- @param {string} domain Domain name

--

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

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

end

end

--- Split a URL into a scheme, authority indicator, and domain.

--

-- First remove Fully Qualified Domain Name terminator (a dot following TLD) (if any) and any path(/), query(?) or fragment(#).

--

-- If protocol-relative URL, return nil scheme and domain else return nil for both scheme and domain.

--

-- When not protocol-relative, get scheme, authority indicator, and domain. If there is an authority indicator (one

-- or more '/' characters immediately following the scheme's colon), make sure that there are only 2.

--

-- Any URL that does not have news: scheme must have authority indicator (//). @todo: are there other common schemes

-- like news: that don't use authority indicator?

--

-- Strip off any port and path;

--

-- @param {string} url_str URL string

-- @return Split URL

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

--- checks the content of |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).

--

-- @param {string} value URL parameter value

--

-- @return Whether the URL is invalid

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 URL

end

--- Use link_param_ok() to validate |-link= value and its matching |