Módulo:Mbabel

Módulo projetado para simplificar a criação de predefinições de narrativas estruturadas usadas pelo Mbabel. Quando chamado, ele retorna o texto com a informação desejada do Wikidata substituída; Caso a informação não exista, o texto não é exibido.

Uso

O módulo apresenta três tipos de chamadas: title, phrase e reference. Dentro do ambiente de criação dos templates para o Mbabel, todas as chamadas devem ser configuradas de modo a só serem substituídas quando o usuário salvar sua página de testes. Isso é feito usando uma combinação de subst e da tag <noinclude/>, por exemplo: {{subst:<noinclude />#invoke:Mbabel|title|qid=<qid>}}

Função title

A função title retorna o título de um item Wikidata.

Parâmetros

• qid: Código identificador do item no Wikidata.

Uso

• Sem substituição:
  • {{#invoke:Mbabel|title|qid=<qid>}}
• Com substituição:
  • {{subst:#invoke:Mbabel|title|qid=<qid>}}
• Com substituição (para uso na construção de predefinições):
  • {{subst:<noinclude />#invoke:Mbabel|title|qid=<qid>}}

Exemplos

• Sem substituição:
  • {{#invoke:Mbabel|title|qid=Q208363}} → Eru Ilúvatar
• Com substituição:
  • {{subst:#invoke:Mbabel|title|qid=Q208363}} → Eru Ilúvatar
• Com substituição (para uso na construção de predefinições):
  • {{subst:<noinclude/>#invoke:Mbabel|title|qid=Q208363}} → {{subst:#invoke:Mbabel|title|qid=Q208363}}

Função phrase

A função phrase retorna uma frase substituída com uma informação do Wikidata.

Parâmetros

Obrigatórios

• pid: Código identificador de uma propriedade Wikidata (Ex: P1441).
• qid: Código identificador do item no Wikidata (Ex: Q208363).
• text: Frase com partes fixas e partes variáveis que dependem do valor retornado do Wikidata (Ex: Presente em @.).
• var: Expressão ou variável ou caractere que identifica na |text= as partes variáveis (Ex: @).

Nota: O primeiro parâmetro pid é um parâmetro não nomeado, isto é, deve ser passado como |<pid>|. Os demais são passados como |qid=<qid>, |text=<text> e |var=<var>.

Opcionais

Esta função aceita todos os parâmetros opcionais que a função getPreferredValue aceita.

Uso

• Sem substituição:
  • {{#invoke:Mbabel|phrase|<pid>|qid=<qid>|text=<text>|var=<var>}}
  • {{#invoke:Mbabel|phrase|<pid>|qid=<qid>|text=<text>|var=<var>|parameter1=<parameter1>|...|parameterx=<parameterx>}}
• Com substituição:
  • {{subst:#invoke:Mbabel|phrase|<pid>|qid=<qid>|text=<text>|var=<var>}}
  • {{subst:#invoke:Mbabel|phrase|<pid>|qid=<qid>|text=<text>|var=<var>|parameter1=<parameter1>|...|parameterx=<parameterx>}}
• Com substituição (para uso na construção de predefinições):
  • {{subst:<noinclude />#invoke:Mbabel|phrase|<pid>|qid=<qid>|text=<text>|var=<var>}}
  • {{subst:<noinclude />#invoke:Mbabel|phrase|<pid>|qid=<qid>|text=<text>|var=<var>|parameter1=<parameter1>|...|parameterx=<parameterx>}}

Exemplos

• Sem substituição:
  • {{#invoke:Mbabel|phrase|P1441|qid=Q208363|text=Presente em ''@''|var=@}} → Presente em O Silmarillion, Contos Inacabados de Númenor e da Terra Média
  • {{#invoke:Mbabel|phrase|P1441|qid=Q208363|text=Presente em ''@''|var=@|artigosemlink=sim}} → Presente em O Silmarillion, Contos Inacabados de Númenor e da Terra Média
• Com substituição:
  • {{subst:#invoke:Mbabel|phrase|P1441|qid=Q208363|text=Presente em ''@''|var=@}} → Presente em O Silmarillion
  • {{subst:#invoke:Mbabel|phrase|P1441|qid=Q208363|text=Presente em ''@''|var=@|artigosemlink=sim}} → Presente em O Silmarillion
• Com substituição (para uso na construção de predefinições):
  • {{subst:<noinclude />#invoke:Mbabel|phrase|P1441|qid=Q208363|text=Presente em ''@''|var=@}} → {{subst:#invoke:Mbabel|phrase|P1441|qid=Q208363|text=Presente em @|var=@}}
  • {{subst:<noinclude />#invoke:Mbabel|phrase|P1441|qid=Q208363|text=Presente em ''@''|var=@|artigosemlink=sim}} → {{subst:#invoke:Mbabel|phrase|P1441|qid=Q208363|text=Presente em @|var=@|artigosemlink=sim}}

Função reference

A função reference retorna uma referência substituída com uma informação do Wikidata.

Parâmetros

Obrigatórios

• pid: Código identificador de uma propriedade Wikidata (Ex: P268).
• qid: Código identificador do item no Wikidata (Ex: Q892).
• text: Código da referência desejada com partes fixas e partes variáveis que dependem do valor retornado do Wikidata (Ex: {{citar web|url=https://catalogue.bnf.fr/ark:/12148/cb@|título=J.R.R.Tolkien - Biblioteca Nacional da França|publicado=[[Biblioteca Nacional da França]]|acessodata=4 de maio de 2024}}.).
• var: Expressão ou variável ou caractere que identifica na |text= as partes variáveis (Ex: @).
• name: Nome da referência. Ajuda a criar a referência no formato <ref name = "<name>">...</ref>

Nota: O primeiro parâmetro pid é um parâmetro não nomeado, isto é, deve ser passado como |<pid>|. Os demais são passados como |qid=<qid>, |text=<text>, |var=<var> e |name=<name>.

Opcionais

Esta função aceita todos os parâmetros opcionais que a função getPreferredValue aceita.

Uso

• Sem substituição:
  • {{#invoke:Mbabel|reference|<pid>|qid=<qid>|text=<text>|var=<var>}}
  • {{#invoke:Mbabel|reference|<pid>|qid=<qid>|text=<text>|var=<var>|parameter1=<parameter1>|...|parameterx=<parameterx>}}
• Com substituição:
  • {{subst:#invoke:Mbabel|reference|<pid>|qid=<qid>|text=<text>|var=<var>}}
  • {{subst:#invoke:Mbabel|reference|<pid>|qid=<qid>|text=<text>|var=<var>|parameter1=<parameter1>|...|parameterx=<parameterx>}}
• Com substituição (para uso na construção de predefinições):
  • {{subst:<noinclude />#invoke:Mbabel|reference|<pid>|qid=<qid>|text=<text>|var=<var>}}
  • {{subst:<noinclude />#invoke:Mbabel|reference|<pid>|qid=<qid>|text=<text>|var=<var>|parameter1=<parameter1>|...|parameterx=<parameterx>}}

Exemplos

• Sem substituição:
  • {{#invoke:Mbabel|phrase|P268|qid=Q892|text={{citar web|url=https://catalogue.bnf.fr/ark:/12148/cb@|título=J.R.R.Tolkien - Biblioteca Nacional da França|publicado=[[Biblioteca Nacional da França]]}}|var=@|name=BNF}} → <ref name = "BNF">J.R.R.Tolkien - Biblioteca Nacional da França. Biblioteca Nacional da França.</ref>
• Com substituição:
  • {{subst:#invoke:Mbabel|phrase|P268|qid=Q892|text={{citar web|url=https://catalogue.bnf.fr/ark:/12148/cb@|título=J.R.R.Tolkien - Biblioteca Nacional da França|publicado=[[Biblioteca Nacional da França]]}}|var=@|name=BNF}} →
• Com substituição (para uso na construção de predefinições):
  • {{subst:<noinclude />#invoke:Mbabel|phrase|P268|qid=Q892|text={{citar web|url=https://catalogue.bnf.fr/ark:/12148/cb@|título=J.R.R.Tolkien - Biblioteca Nacional da França|publicado=[[Biblioteca Nacional da França]]}}|var=@|name=BNF}} → {{subst:#invoke:Mbabel|phrase|P268|qid=Q892|text=J.R.R.Tolkien - Biblioteca Nacional da França. Biblioteca Nacional da França.|var=@|name=BNF}}

Referências

---

local p = {}

--------------------------------------------------------------------------------
-- GLOBAL CONSTANTS
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
-- Internationalization
--
local i18n =
{
	["errors"]=
	{
		["command-error"] = "Erro de comando",									-- Command error
		["pid-not-passed"] = "Propriedade Wikidata não fornecida",				-- Wikidata property not passed
		["qid-not-passed"] = "Item Wikidata não fornecido",						-- Wikidata item not passed 
		["text-not-passed"] = "Nenhum texto fornecido",							-- No text was passed
		["var-not-passed"] = "Argumento da frase não fornecido",				-- No argument to be substituted was passed
		["nothing-passed"] = "Nenhum parâmetro foi fornecido"					-- No parameter was passed
	}
}

--------------------------------------------------------------------------------
-- PRIVATE FUNCTIONS
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
-- subst substitutes all ocurrences of "old" in "text" with "new"
-- string text, old, new
--
local function subst(text, old, new)
	local new_text = string.gsub(text, old, new)
	return new_text
end

--------------------------------------------------------------------------------
-- get_value returns the Wikidata value if exists. It takes an argument _type
-- that determines which function of the Wikidata module it will be used.
-- Accepts all the usual parameters of the Wikidata module, as it calls that
-- module to get the value. Here, it is used the WikidataIB, but others could
-- be used, especially in internationalization.
-- frame object frame,
-- string _type
--
local function get_value(frame, _type)
	local value = ""
	
	if _type == 'title' then
		local qid = frame.args.qid
		frame.args[1] = qid
		
		-- {{#invoke:WikidataIB|getLabel|<qid>}}
		value = require("Módulo:WikidataIB").getLabel(frame)
	else
		frame.args['fetchwikidata'] = 'ALL'
		frame.args['noicon'] = 'yes'
		frame.args['onlysourced'] = 'no'
		
		-- {{#invoke:WikidataIB|getPreferredValue|<pid>|fetchwikidata=ALL|noicon=yes|onlysourced=no|...|qid=<qid>}}
		value = require("Módulo:WikidataIB").getPreferredValue(frame)
	end
	
	return value
end

--------------------------------------------------------------------------------
-- validation verifies if the obligatory parameters were passed
-- The obligatory parameters are pid, qid, text and var
-- An extra parameter (name) is used with 'reference' requests
-- frame object frame
--
local function validation(frame, _type)
	local text = frame.args.text
	local var = frame.args.var
	local name = frame.args.name
	local msg = '<span class="error"><b><span class="scribunto-error" id="mw-scribunto-error-0">' .. i18n["errors"]["command-error"] .. ': @. </span></b></span>'

	if _type ~= 'title' then
		local pid = frame.args[1]
		local qid = frame.args.qid
		
		if not pid and not qid and not text and not var then
			msg = string.gsub(msg, "@", i18n["errors"]["nothing-passed"])
			return false, msg, nil, nil, nil, nil, nil
		end
		if pid and (#pid == 0) or not pid then
			msg = string.gsub(msg, "@", i18n["errors"]["pid-not-passed"])
			return false, msg, nil, nil, nil, nil, nil
		end
		if qid and (#qid == 0) or not qid then
			msg = string.gsub(msg, "@", i18n["errors"]["qid-not-passed"])
			return false, msg, nil, nil, nil, nil, nil
		end
		if text and (#text == 0) or not text then
			msg = string.gsub(msg, "@", i18n["errors"]["text-not-passed"])
			return false, msg, nil, nil, nil, nil, nil
		end
		if var and (#var == 0) or not var then
			msg = string.gsub(msg, "@", i18n["errors"]["var-not-passed"])
			return false, msg, nil, nil, nil, nil, nil
		end
	else
		local qid = frame.args.qid or frame.args[1]
		if not qid then
			msg = string.gsub(msg, "@", i18n["errors"]["nothing-passed"])
			return false, msg, nil, nil, nil, nil, nil
		end
		if qid and (#qid == 0) then
			msg = string.gsub(msg, "@", i18n["errors"]["qid-not-passed"])
			return false, msg, nil, nil, nil, nil, nil
		end
	end
	return true, nil, pid, qid, text, var, name
end

--------------------------------------------------------------------------------
-- _get executes the Mbabel functionallity by taking the arguments, verifying
-- if the information exists on Wikidata and substituting in the text (phrases,
-- titles or references) passed.
-- frame object frame,
-- string _type
--
local function _get(frame, _type)
	-- Do the validation to check if the obligatory parameters were passed
	local success, msg, pid, qid, text, var, name = validation(frame, _type)
	
	-- If the validation didn't passed, show message
	if not success then
		return msg
	end
	
	-- The validation passing, it's time to check if there is any value in
	-- Wikidata to be shown
	local value = get_value(frame, _type)
	
	-- If there is a value, if it is a title request, return the value found,
	-- else, substitute the value into the phrase passed or, if a "name"
	-- parameter were passed, a reference and return it
	if value and (#tostring(value)~=0) then
		if _type == 'title' then
			return value
		end
		
		local out = subst(text, var, value)
		
		if name and (#value~=0) then
			return '<ref name = "' .. name .. '">' .. out .. '</ref>'
		end
		
		return out
	end
	
	-- In case there is no value in Wikidata (accordingly with the module and
	-- parameters of its functions), return an empty string.
	return ""
end

--------------------------------------------------------------------------------
-- PUBLIC FUNCTIONS
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
-- title gets the label of a Wikidata item
--
function p.title(frame)
	return _get(frame, 'title')
end

--------------------------------------------------------------------------------
-- phrase gets the value of a property of a Wikidata item and substitutes into
-- a phrase passed.
--
function p.phrase(frame)
	return _get(frame, 'phrase')
end

--------------------------------------------------------------------------------
-- reference gets the value of a property of a Wikidata item and substitutes
-- into a named reference tag.
--
function p.reference(frame)
	return _get(frame, 'reference')
end

return p