Modulus:scripts

Purpose

This module is used to retrieve and manage Wiktionary's various writing systems and the information associated with them. See Wiktionary:Scripts for more information.

The information itself is stored in Module:scripts/data. The data module should not be used directly by any other module, the data should only be accessed through the functions provided by Module:scripts.

For functions that allow templates to use this module, see Module:scripts/templates.

Finding and retrieving scripts

The module exports a number of functions that are used to find scripts.

getByCode

getByCode(code)

Finds the script whose code matches the one provided. If it exists, it returns a Script object representing the script. Otherwise, it returns nil.

findBestScript

findBestScript(text, lang)

Given some text and a language object, this function iterates through the scripts of the given language and tries to find the script that best matches the text. It returns a Script object representing the script. If no match is found at all, it returns the None script object.

Script objects

A Script object is returned from one of the functions above. It is a Lua representation of a script and the data associated with it. It has a number of methods that can be called on it, using the : syntax. For example:

local m_scripts = require("Module:scripts")
local sc = m_scripts.getByCode("Latn")
local name = sc:getCanonicalName()
-- "name" will now be "Latin"

Script:getCode

:getCode()

Returns the script code of the language. Example: "Cyrl" for Cyrillic.

Script:getCanonicalName

:getCanonicalName()

Returns the canonical name of the script. This is the name used to represent that script on Wiktionary. Example: "Cyrillic" for Cyrillic.

Script:getParent

:getParent()

Returns the parent of the script. Example: "Latn" for "Latinx" and "Arab" for "fa-Arab". It returns "top" for scripts without a parent, like "Latn", "Grek", etc.

Script:getWikipediaArticle

:getWikipediaArticle()

Returns the wikipedia_article item in the language's data file, or else calls Script:getCategoryName().

Script:countCharacters

:countCharacters(text)

Returns the number of characters in the text that are part of this script.

Note: You should never rely on text consisting entirely of the same script. Strings may contain spaces, punctuation and even wiki markup or HTML tags. HTML tags will skew the counts, as they contain Latin-script characters. So it's best to avoid them.

Script:getCharacters

:getCharacters()

Returns the regex defining the script's characters from the language's data file.

This can be used to search for words consisting only of this script, but see the warning above.

Script:getCategoryName

:getCategoryName()

Returns the name of the main category of that script. Example: "Cyrillic script" for Cyrillic, whose category is at Category:Cyrillic script.

Script:getDirection

:getDirection()

Returns the text direction, if any. Currently, left-to-right scripts are unmarked, while most right-to-left scripts have direction specified as "rtl" and Mongolian as "down".

See also

• Module:script utilities

---

local export = {}
local Script = {}

function Script:getCode()
	return self._code
end

function Script:getCanonicalName()
	return self._rawData.canonicalName
end

function Script:getOtherNames()
	return self._rawData.otherNames or {}
end

function Script:getParent()
	return self._rawData.parent
end

function Script:getSystems()
	if not self._systemObjects then
		local m_systems = require("Module:writing systems")
		self._systemObjects = {}
		
		for _, sys in ipairs(self._rawData.systems or {}) do
			table.insert(self._systemObjects, m_systems.getByCode(sys))
		end
	end
	
	return self._systemObjects
end

--function Script:getAllNames()
--	return self._rawData.names
--end


function Script:getType()
	return "script"
end


function Script:getCategoryName()
	local name = self._rawData.canonicalName
	
	-- If the name already has "code" or "semaphore" in it, don't add it.
	-- No names contain "script".
	if name:find("[Cc]ode$") or name:find("[Ss]emaphore$") then
		return name
	else
		return name .. " script"
	end
end


function Script:getWikipediaArticle()
	return self._rawData.wikipedia_article or self:getCategoryName()
end


function Script:getCharacters()
	if self._rawData.characters then
		return self._rawData.characters
	else
		return nil
	end
end


function Script:countCharacters(text)
	if not self._rawData.characters then
		return 0
	else
		local _, num = mw.ustring.gsub(text, "[" .. self._rawData.characters .. "]", "")
		return num
	end
end

function Script:getDirection()
	local direction = self._rawData.direction
	if not direction then
		return nil
	else
		return direction
	end
end


function Script:getRawData()
	return self._rawData
end


function Script:toJSON()
	local ret = {
		canonicalName = self:getCanonicalName(),
		categoryName = self:getCategoryName(),
		code = self._code,
		otherNames = self:getOtherNames(),
		type = self:getType(),
		}
	
	return require("Module:JSON").toJSON(ret)
end


Script.__index = Script


function export.makeObject(code, data)
	return data and setmetatable({ _rawData = data, _code = code }, Script) or nil
end


function export.getByCode(code)
	if code == "IPAchar" then
		require("Module:debug").track("IPAchar")
	end
	return export.makeObject(code, mw.loadData("Module:scripts/data")[code])
end

function export.getByCanonicalName(name)
	local code = mw.loadData("Module:scripts/by name")[name]
	
	if not code then
		return nil
	end
	
	return export.makeObject(code, mw.loadData("Module:scripts/data")[code])
end

-- Find the best script to use, based on the characters of a string.
function export.findBestScript(text, lang)
	if not text or not lang or not lang.getScripts then
		return export.getByCode("None")
	end
	
	local scripts = lang:getScripts()
	
	if not scripts[2] then
		return scripts[1]
	end
	
	--[=[
		Remove any HTML entities; catfix function in [[Module:utilities]]
		adds tagging to a no-break space ( ), which contains Latin characters;
		hence Latin was returned as the script if "Latn" is one of the language's scripts.
	]=]
	text = string.gsub(text, "&[a-zA-Z0-9]+;", "")
	
	-- Try to match every script against the text,
	-- and return the one with the most matching characters.
	local bestcount = 0
	local bestscript = nil
	
	-- Get length of text minus any spacing or punctuation characters.
	-- Counting instances of UTF-8 character pattern is faster than mw.ustring.len.
	local _, length = string.gsub(mw.ustring.gsub(text, "[%s%p]+", ""), "[\1-\127\194-\244][\128-\191]*", "")
	
	if length == 0 then
		return export.getByCode("None")
	end
	
	for i, script in ipairs(scripts) do
		local count = script:countCharacters(text)
		
		if count >= length then
			return script
		end
		
		if count > bestcount then
			bestcount = count
			bestscript = script
		end
	end
	
	if bestscript then
		return bestscript
	end
	
	-- No matching script was found. Return "None".
	return export.getByCode("None")
end

return export