Module:Convert/text

Documentation for this module may be created at Module:Convert/text/doc

--[[ Text used by Module:Convert, for en.wikipedia.org (English).

This is a separate module to simplify translation for use on another wiki.
Module:Convert responds to text parameters, and can display text.
Nearly all that text is defined in:
* Module:Convert/data (unit definitions)
* Module:Convert/text (parameter and message definitions)
]]

-- Some units accept an SI prefix before the unit code, such as "kg" for kilogram.
local SIprefixes = {
	-- The prefix field is what the prefix should be, if different from the prefix used.
	['Y'] = { exponent = 24, name = 'yotta',                  },
	['Z'] = { exponent = 21, name = 'zetta',                  },
	['E'] = { exponent = 18, name = 'exa'  ,                  },
	['P'] = { exponent = 15, name = 'peta' ,                  },
	['T'] = { exponent = 12, name = 'tera' ,                  },
	['G'] = { exponent =  9, name = 'giga' ,                  },
	['M'] = { exponent =  6, name = 'mega' ,                  },
	['k'] = { exponent =  3, name = 'kilo' ,                  },
	['h'] = { exponent =  2, name = 'hecto',                  },
	['da']= { exponent =  1, name = 'deca' , name_us = 'deka' },
	['d'] = { exponent = -1, name = 'deci' ,                  },
	['c'] = { exponent = -2, name = 'centi',                  },
	['m'] = { exponent = -3, name = 'milli',                  },
	['μ'] = { exponent = -6, name = 'micro', prefix = 'µ'     },  -- key = 'GREEK SMALL LETTER MU' (U+03BC) utf-8 CE BC
	['µ'] = { exponent = -6, name = 'micro',                  },  -- key = 'MICRO SIGN' (U+00B5) utf-8 C2 B5
	['u'] = { exponent = -6, name = 'micro', prefix = 'µ'     },  -- not an SI prefix, but allow for people typing this
	['n'] = { exponent = -9, name = 'nano' ,                  },
	['p'] = { exponent =-12, name = 'pico' ,                  },
	['f'] = { exponent =-15, name = 'femto',                  },
	['a'] = { exponent =-18, name = 'atto' ,                  },
	['z'] = { exponent =-21, name = 'zepto',                  },
	['y'] = { exponent =-24, name = 'yocto',                  },
}

-- Some units can be qualified with one of the following prefixes, when linked.
local customary_units = {
	{ "US", link = "United States customary units" },
	{ "U.S.", link = "United States customary units" },
	{ "imperial", link = "Imperial unit" },
	{ "imp", link = "Imperial unit" },
}

-- Names when using engineering notation (a prefix of "eN" where N is a number; example "e6km").
-- key = { "name", link = "article title", exponent = numeric_key_value }
-- If lk=on and link is defined, the name of the number will appear as a link.
local eng_scales = {
	["3"]  = { "thousand", exponent = 3 },
	["6"]  = { "million", exponent = 6 },
	["9"]  = { "billion", link = "1000000000 (number)", exponent = 9 },
	["12"] = { "trillion", link = "1000000000000 (number)", exponent = 12 },
	["15"] = { "quadrillion", link = "1000000000000000 (number)", exponent = 15 },
}

-- One of the following categories is included in the text of each message.
local all_categories = {
	unit = "[[Category:Convert invalid units]]",
	option = "[[Category:Convert invalid options]]",
}

-- For some error messages, the following puts the wanted style around
-- each unit code marked like '...%{ft%}...'.
local unitcode_regex = '%%([{}])'
local unitcode_replace = { ['{'] = '"', ['}'] = '"' }  -- no longer need the more elaborate substitute used before 2013-09-28

-- All messages that may be displayed if a problem occurs.
local all_messages = {
	-- Message format string, %s parameters: anchor, title, text, category.
	-- Each displayed message starts with "Convert:" so can easily locate by searching article.
	cvt_format = '<sup class="noprint Inline-Template" style="white-space:nowrap;">[<i>[[Help:Convert messages#%s|<span title="Convert: %s">Convert: %s</span>]]</i>]</sup>%s',
	-- Each of following messages is a table:
	-- { [1] = 'title',         -- mouseover title text
	--   [2] = 'text',          -- link text displayed in article
	--   [3] = 'category key',  -- key to lookup category in all_categories
	--   [4] = 'anchor',        -- anchor for link to relevant section on help page
	--   regex = gsub_regex,
	--   replace = gsub_table,
	-- }                    Mouseover title text                           Link text               CatKey     Anchor
	cvt_bad_num        = { 'Value "%s" must be a number'                , 'Invalid number'      , 'option',  'invalid_number'       },
	cvt_big_prec       = { 'Precision "%s" is too large'                , 'Precision too large' , 'option',  'precision_too_large'  },
	cvt_invalid_num    = { 'Number has overflowed'                      , 'Number overflow'     , 'option',  'number_overflow'      },
	cvt_no_num         = { 'Needs the number to be converted'           , 'Needs a number'      , 'option',  'needs_number'         },
	cvt_no_num2        = { 'Needs another number for a range'           , 'Needs another number', 'option',  'needs_another_number' },
	cvt_bad_prec       = { 'Precision "%s" must be an integer'          , 'Invalid precision'   , 'option',  'invalid_precision'    },
	cvt_bad_sigfig     = { 'sigfig "%s" must be a positive integer'     , 'Invalid sigfig'      , 'option',  'invalid_sigfig'       },
	cvt_empty_option   = { 'Ignored empty option "%s"'                  , 'Empty option'        , 'option',  'empty_option'         },
	cvt_no_spell       = { 'Spelling is not available'                  , 'Bug, ask for help'   , 'option',  'ask_for_help'         },
	cvt_unknown_option = { 'Ignored invalid option "%s"'                , 'Invalid option'      , 'option',  'invalid_option'       },
	cvt_bad_default    = { 'Unit "%s" has an invalid default'           , 'Bug, ask for help'   , 'unit'  ,  'ask_for_help'         },
	cvt_bad_unit       = { 'Unit "%s" is invalid here'                  , 'Unit invalid here'   , 'unit'  ,  'unit_invalid_here'    },
	cvt_no_default     = { 'Unit "%s" has no default output unit'       , 'Bug, ask for help'   , 'unit'  ,  'ask_for_help'         },
	cvt_no_unit        = { 'Needs name of unit'                         , 'Needs unit name'     , 'unit'  ,  'needs_unit_name'      },
	cvt_unknown        = { 'Unit name "%s" is not known'                , 'Unknown unit'        , 'unit'  ,  'unknown_unit'         },
	cvt_should_be      = { '%s'                                         , 'Ambiguous unit'      , 'unit'  ,  'ambiguous_unit', regex = unitcode_regex, replace = unitcode_replace },
	cvt_mismatch       = { 'Cannot convert "%s" to "%s"'                , 'Unit mismatch'       , 'unit'  ,  'unit_mismatch'        },
	cvt_bug_convert    = { 'Bug: Cannot convert between specified units', 'Bug, ask for help'   , 'unit'  ,  'ask_for_help'         },
	cvt_lookup         = { 'Unit "%s" is incorrectly defined'           , 'Bug, ask for help'   , 'unit'  ,  'ask_for_help'         },
}

-- Text to join input value/unit with output value/unit.
local disp_joins = {
	["or"]         = { " or "    , ""  },
	["sqbr-sp"]    = { " ["      , "]" },
	["sqbr-nbsp"]  = { "&nbsp;[" , "]" },
	["comma"]      = { ", "      , ""  },
	["slash-sp"]   = { " / "     , ""  },
	["slash-nbsp"] = { "&nbsp;/ ", ""  },
	["slash-nosp"] = { "/"       , ""  },
	["b"]          = { " ("      , ")" },
	["br"]         = { "<br/>"   , ""  },
}

-- Text to separate values in a range.
local range_types = {
	-- Specifying a table requires "off" and "on" values (for "abbr=off" and "abbr=on");
	-- other fields are optional.
	-- Normally, "adj=on" uses hyphens with unabbreviated units (names, not symbols).
	-- However, "exception = true" means hyphens are also used with "adj=on|abbr=on".
	-- If "adj" is defined here, that text is used with "adj=on" (without hyphens).
	["+"]      = " + ",
	[","]      = ",&nbsp;",
	[", and"]  = ", and ",
	[", or"]   = ", or ",
	["by"]     = " by ",
	["-"]      = "–",
	["to about"] = " to about ",
	["and"]    = { off = " and ", on = " and ", exception = true },
	["or"]     = { off = " or " , on = " or " , exception = true },
	["to"]     = { off = " to " , on = " to " , exception = true },
	["to(-)"]  = { off = "&nbsp;to ", on = "–" },
	["+/-"]    = { off = "&nbsp;±&nbsp;", on = "&nbsp;±&nbsp;", adj = "&nbsp;±&nbsp;" },
	["x"]      = { off = " by ", on = " ×&nbsp;", is_range_x = true },
	["xx"]     = "&nbsp;×&nbsp;",
	["*"]      = "×",  -- use "*" to replace "x" in {{convert/2}} which is different from "x" in old {{convert}}
}

local range_aliases = {
	-- ["alternative name for a range"] = "standard range name"
	["and(-)"]  = "and",
	["&"]       = "and",
	["–"]       = "-",
	["&ndash;"] = "-",
	["to-"]     = "to(-)",
	["×"]       = "x",
	["±"]       = "+/-",
}

-- Valid option names.
local en_option_name = {
	-- ["local text for option name"] = "en name used in this module"
	["abbr"] = "abbr",
	["adj"]  = "adj",
	["debug"] = "debug",
	["disp"] = "disp",
	["comma"]  = "comma",
	["lang"]  = "lang",
	["lk"]   = "lk",
	["near"] = "near",
	["order"] = "order",
	["sigfig"] = "sigfig",
	["sing"] = "adj",                   -- "sing" is an old alias for "adj"
	["sortable"] = "sortable",
	["sp"] = "sp",
	["spell"] = "spell",
}

-- Valid option values.
-- Convention: parms.opt_xxx refers to an option that is set here
-- (not intended to be set by the template which invokes this module).
-- Example: At en.wiki, "abbr" includes:
--     ["comma"] = "opt_nocomma"
-- As a result, if the template uses abbr=comma, this script sets:
--     parms["opt_nocomma"] = true
--     parms["abbr"] = nil
-- Therefore parms.abbr will be nil, or will have one of the listed values
-- that do not start with "opt_".
local en_option_value = {
	["abbr"] = {
		-- ["local text for option value"] = "en value used in this module"
		["comma"] = "opt_nocomma",      -- no numsep in input or output numbers
		["in"] = "in",                  -- use symbol for LHS unit
		["mos"] = "mos",                -- in a range, repeat the input unit (no longer used)
		["none"] = "off",               -- old name for "off"
		["off"] = "off",                -- use name for all units
		["on"] = "on",                  -- use symbol for all units
		["out"] = "out",                -- use symbol for RHS unit (default)
		["values"] = "opt_values",      -- show only input and output numbers, not units
		["~"] = "opt_also_symbol",      -- show input unit symbol as well as name
	},
	["adj"] = {
		["1"] = "opt_singular",         -- unit name is singular when value satisfies: (-1 <= v and v < 0) or (0 < v and v <= 1)
		["flip"] = "opt_flip",          -- reverse order of input/output
		["j"] = "opt_use_nbsp",         -- "join": use "&nbsp;" instead of " " between value and unit name
		["mid"] = "opt_adj_mid",        -- adj=on with user-specified text before input unit
		["nocomma"] = "opt_nocomma",    -- no numsep in input or output numbers
		["off"] = "",                   -- ignored (off is the default)
		["on"] = "opt_adjectival",      -- unit name is singular and hyphenated
		["pre"] = "opt_one_preunit",    -- user-specified text before input unit
		["ri1"] = "ri1",                -- round input with precision = 1
		["ri2"] = "ri2",                -- round input with precision = 2
		["ri3"] = "ri3",                -- round input with precision = 3
	},
	["disp"] = {
		["/"] = "slash",                -- join: '/'
		["2"] = "opt_output_only",      -- display only output value and symbol/name (not input)
		["5"] = "opt_round5",           -- round output value to nearest 5
		["b"] = "b",                    -- join: '(...)'
		["br"] = "br",                  -- join: '<br/>'
		["comma"] = "comma",            -- join: ','
		["flip"] = "opt_flip",          -- reverse order of input/output
		["flip5"] = "opt_flip, opt_round5",  -- disp=flip + disp=5
		["nocomma"] = "opt_nocomma",    -- no numsep in input or output numbers
		["number"] = "opt_output_number_only",  -- display output value (not input, and not output symbol/name)
		["or"] = "or",                  -- join: 'or'
		["out"] = "opt_output_only",
		["output number only"] = "opt_output_number_only",
		["output only"] = "opt_output_only",
		["preunit"] = "opt_two_preunits",    -- user-specified text before input and output units
		["s"] = "slash",                -- join: '/'
		["slash"] = "slash",            -- join: '/'
		["sqbr"] = "sqbr",              -- join: '[...]'
		["table"] = "opt_table",        -- output is suitable for a table cell with align="right"
		["tablecen"] = "opt_tablecen",  -- output is suitable for a table cell with align="center"
		["u2"] = "opt_output_unit_only",  -- display output symbol/name (not input, and not output value)
		["unit"] = "opt_input_unit_only", -- display input symbol/name (not output, and not input value)
		["unit2"] = "opt_output_unit_only",
		["x"] = "x",                    -- join: <first>...<second> (user-specified text)
	},
	["near"] = {
		["5"] = "opt_round5",           -- round output value to nearest 5
	},
	["order"] = {
		["flip"] = "opt_flip",          -- reverse order of input/output
	},
	["comma"] = {
		["5"] = "opt_comma5",           -- only use numsep grouping if 5 or more digits
		["gaps"] = "opt_gaps",          -- use gaps, not numsep, to separate groups of digits
		["gaps5"] = "opt_gaps, opt_comma5",  -- opt_gaps + opt_comma5
	},
	["debug"] = {
		["yes"] = "opt_sortable_debug", -- make the normally hidden sort key visible
	},
	["lang"] = {
		["en"] = "opt_lang_en",         -- use en digits for output, regardless of local language
	},
	["lk"] = {
		["in"] = "in",                  -- link LHS unit name or symbol
		["off"] = "",                   -- ignored (off is the default)
		["on"] = "on",                  -- link all unit names or symbols (but not twice for the same unit)
		["out"] = "out",                -- link RHS unit name or symbol
	},
	-- sigfig=x is handled as a special case: x must be an integer (possibly in local language) = 1 or more
	["sortable"] = {
		["off"] = "",                   -- ignored (off is the default)
		["on"] = "opt_sortable",        -- output numeric hidden sort field for use in a sortable table
	},
	["sp"] = {
		["us"] = "opt_sp_us",           -- use U.S. spelling (like "meter" instead of default "metre")
	},
	["spell"] = {                       -- only English spelling is supported; only for input; not scientific notation; only some fractions
		["in"] = "opt_spell_in",        -- spell input value in words
		["In"] = "opt_spell_in, opt_spell_upper",  -- spell input value in words with first letter uppercase
	},
}

return {
	SIprefixes = SIprefixes,
	all_categories = all_categories,
	all_messages = all_messages,
	customary_units = customary_units,
	disp_joins = disp_joins,
	en_option_name = en_option_name,
	en_option_value = en_option_value,
	eng_scales = eng_scales,
	range_aliases = range_aliases,
	range_types = range_types,
}