Module:Unit

Template:Doc/start Template:Template backend Unit definitions are loaded from Module:Unit/data. Template:Doc/end

---

local p = {}
local Utils = require("Module:Utils")
local UnitsData = mw.loadData("Module:Sandbox/Demian/Unit/data")
local HTMLUtils = require("Module:UtilsHTML")

--- Find a definition for a unit measurement with the given case sensitive abbreviation and return a HTML <code>abbr</code> tag with the appropriate unit details.
--
-- Most abbreviations are <strong>case sensitive</strong> to differentiate between the milli- and mega- prefixes for example (e.g., millihertz (mHz) and megahertz (MHz)), but about a third of the abbreviations are not.
-- Non-case sensitivity is simply provided as an <em>ease of use</em> feature in the case that user mistypes a unit (e.g., writing "MO" instead of "mo" for month): the only way to truly know if a unit is or is not case sensitive is to read the module data file.
--
-- For example the meter per second abbreviation ("m/s" or "mps") is not case sensitive as there is no other unit defined by just the letter "m".
-- All units that contain a forward slash (e.g., "rad/s" radian per second) can be written with the character "p" replacing the slash. So "radps" and "rad/s" are equivalent.
-- @param #string abbr Abbreviation for a unit. This should be treated as case sensitive because <strong>most</strong>, but not all, units are case sensitive.
-- @return #table String with a HTML abbr element, if a unit definition was found.
-- @author User:Demian
-- @usage getUnit("kWh") = { "kW&sdot;h", "kilowatt-hour" }
-- @usage getUnit("ppm") = { "ppm", "part per million" }
-- @usage getUnit("GiB") = { "GiB", "gibibyte" }
function p.getUnit(abbr)
	local abbrKey = tostring(abbr)
	local unitData = UnitsData["caseSensitiveUnits"][abbrKey]

	if not unitData then
		-- All case insensitive unit abbreviations are lower case, the user written abbreviation may not be.
		abbrKey = mw.ustring.lower(abbrKey)
		unitData = UnitsData["caseInsensitiveUnits"][abbrKey]
	end

	return unitData
end

--- Find a definition for a unit measurement with the given case sensitive abbreviation and return a HTML <code>abbr</code> tag with the appropriate unit details.
-- @param #string abbr Case sensitive abbreviation for a unit.
-- @return #string String with a HTML abbr element, if a unit definition was found.
-- @return #string <code>abbr</code> with whitespace trimmed if no unit definition is found.
-- @return #string "" if a value that evaluates as <code>false</code> is given e.g., <code>nil</code>.
-- @author User:Demian
-- @see getUnit
-- @usage _unit("kWh") = "<abbr title="kilowatt-hour">kW&sdot;h</abbr>"
-- @usage _unit("ppm") = "<abbr title="part per million">ppm</abbr>"
-- @usage _unit("GiB") = "<abbr title="gibibyte">GiB</abbr>"
function p._unit(abbr)
	if abbr then
		local unitData = getUnit(abbr)

		if unitData then
			return HTMLUtils.tagAbbr(unitData[1], unitData[2])
		else
			return abbr
		end
	else
		return ""
	end
end

function p.unit(frame)
	local args = Utils.normaliseArgs(frame)
	return p._unit(args[1])
end

return p