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)

In addition to the parameters defined here, Module:Convert accepts built-in
parameters shown in the following examples:
    debug=yes       Can be used with sortable=on.
    sigfig=3        To set number of output significant figures.
]]

-- 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).
-- key = { "name", link = "article title", exponent = key }
-- 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 },
}

-- When appropriate, the following categories can be included in the output.
local all_categories = {
    general = "[[Category:Convert error]]",
    mismatch = "[[Category:Convert dimension mismatch]]",
    option = "[[Category:Convert invalid option]]",
    unknown = "[[Category:Convert unknown unit]]",
}

-- Following puts wanted style around each unit code marked like '...%{ft%}...'.
local unitcode_regex = '%%([{}])'
local unitcode_replace = { ['{'] = '<code style="background:transparent;">', ['}'] = '</code>' }

-- All messages that may be displayed if a problem occurs.
local all_messages = {
    -- One of the following prefixes is inserted before each message.
    cvt_prefix_error = '<span style="color:black; background-color:orange;">[[Module talk:Convert|Conversion error]]:',
    cvt_prefix_warning = '<span style="color:black; background-color:peachpuff;">[[Module talk:Convert|Conversion warning]]:',
    -- Each of following messages is a table:
    -- { [1] = 'error text',
    --   [2] = 'category key',
    --   regex = gsub_regex,
    --   replace = gsub_table,
    --   warning = true,        -- omitted for an error message; selects cvt_prefix_error or cvt_prefix_warning
    -- }
    cvt_bad_default = { 'Unit "%s" has an invalid default', 'unknown' },
    cvt_bad_num = { 'Value "%s" must be a number', 'general' },
    cvt_bad_prec = { 'Parameter precision "%s" must be an integer', 'general' },
    cvt_bad_sigfig = { 'Parameter sigfig "%s" must be a positive integer', 'general' },
    cvt_bad_unit = { 'Unit "%s" is invalid here', 'unknown' },
    cvt_big_prec = { 'Precision "%s" is too large', 'general' },
    cvt_bug_convert = { 'Bug: Cannot convert between specified units', 'general' },
    cvt_empty_option = { 'Ignored empty option "%s"', 'option', warning = true },
    cvt_invalid_num = { 'Number is too large or too small', 'general' },
    cvt_lookup = { 'Unit "%s" is incorrectly defined', 'general' },
    cvt_mismatch = { 'Cannot convert "%s" to "%s"', 'mismatch' },
    cvt_no_default = { 'Unit "%s" has no default output unit', 'unknown' },
    cvt_no_num = { 'Need value', 'general' },
    cvt_no_num2 = { 'Need another value', 'general' },
    cvt_no_unit = { 'Need name of unit', 'unknown' },
    cvt_should_be = { '%s', 'general', regex = unitcode_regex, replace = unitcode_replace },
    cvt_spell_unavailable = { 'Spelling is not available', 'option', warning = true },
    cvt_unknown = { 'Unit "%s" is not known', 'unknown' },
    cvt_unknown_option = { 'Ignored invalid option "%s"', 'option', warning = true },
}

-- 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 = {
    ["+"]      = " + ",
    [","]      = ",&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 = {
    ["and(-)"]  = "and",
    ["&"]       = "and",
    ["–"]       = "-",
    ["&ndash;"] = "-",
    ["to-"]     = "to(-)",
    ["×"]       = "x",
    ["±"]       = "+/-",
}

-- Valid option names.
local local_option_name = {
    -- ["en name used in this module"] = "local text for option name"
    ["abbr"] = "abbr",
    ["adj"]  = "adj",
    ["disp"] = "disp",
    ["comma"]  = "comma",
    ["lang"]  = "lang",
    ["lk"]   = "lk",
    ["sing"] = "sing",
    ["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",
        ["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",
        ["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 suitable for a table cell with align="right"
        ["tablecen"] = "opt_tablecen",  -- output suitable for a table cell with align="center"
        ["u2"] = "opt_output_unit_only",
        ["unit"] = "opt_input_unit_only",
        ["unit2"] = "opt_output_unit_only",
        ["x"] = "x",                    -- join: 'by...×'
    },
    ["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
    },
    ["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
        ["out"] = "out",                -- link RHS unit name or symbol
    },
    ["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_value = en_option_value,
    eng_scales = eng_scales,
    local_option_name = local_option_name,
    range_aliases = range_aliases,
    range_types = range_types,
}