Module:Sandbox/AbstractWikipedia/Renderers

Module documentation

This module contains some generic renderer code of the template-renderer prototype.

The specific renderers for each language should live in a language-specific sub-module identified by the language code. Currently there are two such sub-modules:

Module:Sandbox/AbstractWikipedia/Renderers/en for English
Module:Sandbox/AbstractWikipedia/Renderers/fi for Finnish
Module:Sandbox/AbstractWikipedia/Renderers/he for Hebrew

General structure of renderers

Renderers are tables, containing the templates needed for each constructor. They should be named after the _predicate field of the constructor type they serve to realize. For each constructor type we have a main template and possible sub-templates, which will become accessible for its realization.

However, each template identifier corresponds in fact to a list of templates, gated by various conditions. These different templates are conditioned on the validity field, which lists the arguments which must be present for it to realize.

Another type of condition is given by the roles field: this lists the possible grammatical roles (as given by dependency labels), which the given template variant can fulfill. If this list is given, the invocation of the template must use one of the given labels to trigger this variant. However, an empty role "" can be given to match for the absence of a label.

If none of the conditions holds, an empty template is returned.

In the future we may want to add a conditions field, which would allow template variants to be gated on more elaborate conditions.

Thus, the general structure of a renderer (in a language-specific sub-module) is the following:

p.RendererName = { main = { -- list of conditioned templates

{ -- template 1

validity = { ... }, -- list of mandatory arguments


         roles = { ... }, -- list of possible grammatical roles

		  template = "..."   -- the actual template
		 },
		{ -- template 2}, -- etc.
	}
	some_sub_template = { } -- list of conditioned templates
	another_sub_template = { } -- etc.

}

Functions exposed by the module

The current module exposes two functions:

1. selectMainTemplate: Given a collection of conditioned template-lists corresponding to a constructor, select the main one to be realized.

2. selectTemplate: Select from a list of conditioned templates the first template which fulfills its conditions.

local p = {}

-- This is the repository of renderers-related code
-- The specific renderers should live in submodules identified by their 
-- languae code, e.g. Module:Sandbox/AbstractWikipedia/Renderers/he

-- Structure of renderers
-- For each constructor type (identified by its _predicate field) we have
-- a *main* template and possible sub-templates.

-- Each template can be realized as one of several variants. These variants
-- are conditioned on the "validity" field, which lists the arguments which must
-- be present. 

-- Another type of condition is given by the "roles" field: this lists the 
-- possible grammtical roles (as given by dependency labels), which the given
-- template variant can fulfil. If this list is given, the invocation of the 
-- template *must* use one of the given labels to triger this variant.

-- If none of the variants can be evaluated, the template is 
-- considered empty.

-- General structure of renderer:
--[[
p.RendererName = {
	main = { -- list of template variatns	
		{ -- variant 1
		  validity = { ... } -- list of mandatory arguments
		  roles = { ... } -- list of possible roles
		  template = "..."   -- the actual template
		 },
		{ -- variant 2}, - etc.
	}
	some_sub_template = { } -- list of variants
	another_sub_template = { } -- etc.
}	
]]--

local function conditionsHold(template_with_conditions, args, role)
	-- Currently the only conditions are the presence of required arugments
	-- and a possible grammatical role
	if template_with_conditions.validity then
		for _, needed_arg in ipairs(template_with_conditions.validity) do
			if args[needed_arg] == nil then
				return false
			end
		end
	end
	if template_with_conditions.roles then
		if not role then -- absence of role is considered as empty role
			role = ""
		end
		-- Check whether the template matches provided role
		for _, possible_role in ipairs(template_with_conditions.roles) do
			if role == possible_role then
				return true
			end
		end
		return false -- no match found
	end
	return true
end

-- Selects a single template from a list of templates, according to given
-- preconditions, and a possible grammatical role. 
-- The constructor provides the arguments
function p.selectTemplate(template_list, args, role)
	for _, template_with_conditions in ipairs(template_list) do
		if conditionsHold(template_with_conditions, args, role) then
			return template_with_conditions.template
		end
	end
	-- Otherwise, return empty template
	return ''
end

-- Selects the main template of a template list
function p.selectMainTemplate(template_list)
	return template_list.main
end

return p