Modul:SmwUtil

Module documentation

This module is subject to page protection. It is a highly visible module in use by a very large number of pages, or is substituted very frequently. Because vandalism or mistakes would affect many pages, and even trivial editing might cause substantial load on the servers, it is protected from editing.

This module provides serveral useful function that can be used in other module to store or retrive data using semantic annotations.

Usage[Quelltext bearbeiten]

local _SMW= require('Module:SmwUtil')
if dataStore == 'smw' and stash then
	_SMW.set(stash)
end
local query = {
	select = {'[[is public::yes]]', '[[is of type::datasheet]]', '[[has id::>>10]]'}
	fields = {'_CDAT=Create date', 'bears name=nickname', 'works as=occupation', 'has siblings'}
}
local attributes = {
	limit = 10,
	mainlabel ='-'
}
local result = _SMW.ask(query, attributes)

Functions[Quelltext bearbeiten]

Provided functions are as follow:

ask(query, attributes, retainBlanks)[Quelltext bearbeiten]

Runs an ask query on the semantic mediawiki triple store according to the parameters provided and returns the result as a lua table. The first parameter (query) has the following fields:

select: table or string, mandatory; the condition the query filters for. can be of string and arbitrarily complex or a table being either of format { propertyname = 'value' }, { '[[propertyname::value]]' } or a mix of both
fields: table or string, optional; the fields, you want to get data from. format of values is fieldname or fieldname=headline (you can skip the preceeding ?). DO NOT USE AN ARRAY! All keys will be discarded! Please uses string only if you have just one field to display. If you want to format the fields and add a headline, please do it before the =, e.g. fieldname#km2=area

Please keep in mind:

attributes may contain any attribute you find in the documentation, but intro and outro will be NILed, default and more results text will be set to the empty string, and format will be overwritten
per default, does only return fields that contain a value. that can result in an "unbalanced" result, where one row contains more elements than others. if you want to get all fields, set retainBlanks to true

query: table, mandatory; the arguments to construct the query. see above for details
attributes: table, optional; more attributes, you want to pass on to the ask query (like limit, for instance)
retainBlanks: boolean, optional; if set to true, result can contain entries with empty values. per default, these entries will be deleted
return: table, query result as a lua table. see the following printout as example

In contrast to Module:CargoUtil, SmwUtil's ask recognizes when a property holds a list of values and returns this as a lua table (see example below on property references). CargoUtils would treat this as a comma separated list.

{
	1 = {
		1 = 'Extension:Cargo'
		has id = '7'
		references = { '901', '821' }
		description = 'Cargo provides a lightweight way to store and query the data contained within the calls to templates, such as infoboxes in mysql tables.'
		MainLabel = 'Extension:Cargo'
	}
	2 = {
		1 = 'Extension:SyntaxHighlight GeSHi'
		has id = '6'
		references = '911'
		description = 'The SyntaxHighlight GeSHi extension provides rich formatting of source code using the "syntaxhighlight"-tag. ...'
		MainLabel = 'Extension:SyntaxHighlight GeSHi'
	}
}

As you can see, the data fields can be indexed either by number or by the provided headline in table fields. (The headline is either the fieldname or a special string you provided via fieldname=headline. The mainlabel always has number 1 and whatever you passed on to attribute mainlabel (if nothing, default is MainLabel).

get(page, field)[Quelltext bearbeiten]

A shortcut for show(page, field).

lua(query, attributes, retainBlanks)[Quelltext bearbeiten]

A shortcut for ask(query, attributes, retainBlanks).

rawask(query, attributes)[Quelltext bearbeiten]

Calls the parser function #ask according to the provided parameters and passes the result on directly. The format of the output is depending on attributes.format. The first parameter (query) has the following mandatory fields:

select: table or string, mandatory; the condition the query filters for. can be of string and arbitrarily complex or a table being either of format { propertyname : 'value' }, { '[[propertyname::value]]' } or a mix of both
fields: table or string, optional; the fields, you want to get data from. format is fieldname or fieldname=headline (you can skip the preceeding ?). Please uses string only if you have just one field to display. If you want to format the fields and add a headline, please do it before the =, e.g. fieldname#km2=area

Please keep in mind:

attributes may contain any attribute you find in the documentation, but intro and outro will be NILed, default and more results text will be set to the empty string, and format will be overwritten
per default, does only return fields that contain a value. that can result in an "unbalanced" result, where one row contains more elements than others. if you want to get all fields, set retainBlanks to true

query: table, mandatory; the arguments to construct the query. see above for details
attributes: table, optional; more attributes, you want to pass on to the ask query (like limit, for instance)
return: string, the renderd output

set(stash)[Quelltext bearbeiten]

Stores provided stash in semantic triple stores.

stash: string or table, mandatory; data to store. if provided as string 'has property=value', one triple can be stores. if provided as table, you can either use { has property = 'value' }, { 'has propert=value' }, or a mix thereof. Even { has property = {'value1', 'value2', 'value3' } is possible.
return: string, hopefully empty, result of set parser function

show(page, field)[Quelltext bearbeiten]

Returns contents of field stored on page

page: string, mandatory; name of page, to get the property contents from (please include namespace but explude brackets), e.g. 'Meta:Mail'
field: string, mandatory; name of property, to get the contents from. You can skip the '?'
return: string, contents of property 'field' on page

subobject(stash, uid)[Quelltext bearbeiten]

Stores provided stash as a subject. Contrary to set(stash) the data is not stored directly on the page but in a separate entity called subobject. These objects can be queried for separately.

stash: string or table, mandatory; data to store. if provided as string 'has property=value', one triple can be stores. if provided as table, you can either use { has property = 'value' }, { 'has propert=value' }, or a mix thereof. Even { has property = {'value1', 'value2', 'value3' } is possible.
uid: string, optional; You can supply a uid to identify the object by. Just make sure, it is unique. :)
return: string, hopefully empty, result of set parser function

local p = {}
local getArgs = require('Module:Arguments').getArgs
local classDebug = require('Module:Debug/class')
local _TT = require('Module:TableTools')

local cfg = {
	fieldSeparator = '###~~~@@@~~~###',
	helperTemplate = 'SmwUtilQueryParserHelper',
	nameMainLabel = 'MainLabel',
	resultSeparator = '#####~~~****~~~#####',
	userParamAsEndMarker = '######~~~!!~~~######',	-- the query somehow sends more information than needed. as to not confuse the user and dump overhaed, we define a userparam that functions as end marker
	valueSeparator = '##~~,,,,~~##', -- this is used in multivalue properties
}

function p.ask(query, attributes, retainBlanks)
	classDebug:log(21, 'entering SmwUtil.ask', 'SmwUtil.ask')
	classDebug:log(23, ' with query: ' .. (query and _TT.printTable(query) or 'NONE'), 'SmwUtil.ask')
	classDebug:log(23, ' with attributes: ' .. (attributes and _TT.printTable(attributes) or 'NONE'), 'SmwUtil.ask')
	local frame = mw.getCurrentFrame()
	local select = query.select and query.select or (query.where and query.where or nil)
	local fields = query.fields
	local attributes = attributes
	if not select or (type(select) == 'table' and _TT.size(select) == 0) or (#select == 0) then
		error('SmwUtil.ask: Argument query.select is missing or empty!', 2)
	end
	if type(attributes) == 'string' then
		attributes = { attributes }
	elseif type(attributes) ~= 'table' then
		error('SmwUtil.ask: Argument attributes has wrong parameter type (' .. type(attributes) .. '); must be table or string', 2)
	end
	attributes.default = ''
	attributes.intro = nil
	attributes.format = 'template'
	attributes.headers = 'hide'
	if not attributes.limit then
		attributes.limit = 1000
	end
	attributes.link = 'none'
	attributes.outro = nil
	attributes.sep = cfg.valueSeparator
	attributes.searchlabel = ''
	attributes.template = cfg.helperTemplate
	attributes.userparam = cfg.userParamAsEndMarker
	if not attributes.mainlabel or attributes.mainlabel == '-' then
		attributes.mainlabel = cfg.nameMainLabel
	end
	-- now try to ascertain the headlines
	local tmpfields = {attributes.mainlabel}
	local headlines = {}
	if type(fields) == 'string' then
		tmpfields[2] = fields:match('^%??(.+)$')
	elseif type(fields) == 'table' then
		for k, v in pairs(fields) do
			tmpfields[k + 1] = v:match('^%??(.+)$')
		end
	end
	for num, hl in pairs(tmpfields) do
		if hl:find('=', 1, true) then
			hl = hl:match('^.+=([^=]*)$')
		elseif hl:find('#', 1, true) then
			hl = hl:match('^([^#]*)#.*$')
		end
		headlines[num] = hl
	end
	local ret = nil
	local result = mw.text.trim(p.rawask(query, attributes))
	if result and mw.ustring.len(result) > 0 then
		classDebug:log(24, ' result is: ' .. result, 'SmwUtil.ask')
		ret = {}
		for row in mw.text.gsplit(result, cfg.resultSeparator, true) do
			if mw.ustring.len(row) > 0 then
				local sequence = {}
				local array = {}
				local num = 1
				for v in mw.text.gsplit(row, cfg.fieldSeparator, true) do
					if mw.text.decode(mw.text.decode(v)) == cfg.userParamAsEndMarker then
						break
					end
					if mw.ustring.match(v, '^[0-9]+$') then
						v = tonumber(v)
					elseif v:find(cfg.valueSeparator, 1, true) then
						-- we have a multivalue field
						local tmp = {}
						for vv in mw.text.gsplit(v, cfg.valueSeparator, true) do
							-- we have to decode twice. first for the encoding happening through format=template encapsulation and second because of queryParserHelper's nowiki
							vv = mw.text.decode(mw.text.decode(vv))
							vv = mw.text.trim(mw.ustring.gsub(vv, '%[%[SMW::o[nf]f?%]%]', ''))	-- smw sometimes throws around its magic tags SMW::[on|off]. we have to remove that
							if not vv or #vv == 0 then
								vv = nil
							end
							table.insert(tmp, vv)
						end
						v = tmp
					else
						-- we have to decode twice. first for the encoding happening through format=template encapsulation and second because of queryParserHelper's nowiki
						v = mw.text.decode(mw.text.decode(v))
						v = mw.ustring.gsub(v, '%[%[SMW::o[nf]f?%]%]', '')	-- smw sometimes throws around its magic tags SMW::[on|off]. we have to remove that
						if not v or #v == 0 then
							v = nil
						end
					end
					table.insert(sequence, v)
					if headlines[num] then
						array[headlines[num]] = v
					else
						array[num] = v
					end
					num = num + 1
				end
--				for k, v in pairs(sequence) do
--					array[k] = v
--				end
				if not array[1] then
					array[1] = sequence[1]
				end
				if  _TT.size(array) > 0 then
					if not retainBlanks then
						-- now delete all entries with an empty value
						for k, v in pairs(array) do
							if mw.ustring.len(tostring(v)) == 0 then
								array[k] = nil
							end
						end
					end
					table.insert(ret, array)
				end
			end
		end
	end
	return ret
end

function p.queryParserHelper(frame)
	local args = getArgs(frame, { trim = false, removeBlanks = false })
	local ret = ''
	for _, val in pairs(args) do
		ret = ret .. mw.text.nowiki(val) .. cfg.fieldSeparator
		-- we need the nowiki, otherwise some the result could produce some unwanted parser results (mw's parser for instance would apply a hrefs to external links)
	end
	return ret:sub(1, -1 - mw.ustring.len(cfg.fieldSeparator)) .. cfg.resultSeparator
end

function p.rawask(query, attributes)
	classDebug:log(21, 'entering SmwUtil.rawask', 'SmwUtil.rawask')
	classDebug:log(23, ' with query: ' .. (query and _TT.printTable(query) or 'NONE'), 'SmwUtil.rawask')
	classDebug:log(23, ' with attributes: ' .. (attributes and _TT.printTable(attributes) or 'NONE'), 'SmwUtil.rawask')
	local frame = mw.getCurrentFrame()
	local select = query.select and query.select or (query.where and query.where or nil)
	local fields = query.fields
	local selection = ''
	if type(select) == 'string' then
		selection = select
	elseif type(select) == 'table' then
		for k, v in pairs(select) do
			if type(k) == 'number' then
				selection = selection .. ' ' .. v
			else
				selection = selection .. ' [[' .. k .. '::' .. v .. ']]'
			end
		end
	else
		error('SmwUtil.rawask: Argument query.select has wrong parameter type (' .. type(select) .. '); must be table or string', 2)
	end
	local args = {}
	if type(fields) == 'string' then
		args[1] = mw.ustring.sub( fields, 1, 1 ) ~= '?' and '?' .. fields or fields
	elseif type(fields) == 'table' then
		for k, v in pairs(fields) do
			args[k] = mw.ustring.sub( v, 1, 1 ) ~= '?' and '?' .. v or v
		end
	end
	if attributes then
		if type(attributes) == 'string' then
			table.insert(args, attributes)
		elseif type(attributes) == 'table' then
			for k, v in pairs(attributes) do
				args[k] = v
			end
		else
			error('SmwUtil.rawask: Argument attributes has wrong parameter type (' .. type(attributes) .. '); must be table or string', 2)
		end
	end
	return frame:callParserFunction{ name = '#ask:' .. selection, args = args}
end

function p.set(stash)
	classDebug:log(21, 'entering SmwUtil.set', 'SmwUtil.set')
	classDebug:log(23, ' with stash: ' .. (stash and _TT.printTable(stash) or 'NONE'), 'SmwUtil.set')
	local frame = mw.getCurrentFrame()
	local query = {}
	if type(stash) == 'string' then
		query[1] = stash
	elseif type(stash) == 'table' then
		for k, v in pairs(stash) do
			if type(v) == 'table' then
				for _, vv in pairs(v) do
					if type(vv) == 'boolean' then
						vv = vv and 'wahr' or 'falsch'
					end
					table.insert(query, k .. '=' .. vv)
				end
			else
				if type(v) == 'boolean' then
					v = v and 'wahr' or 'falsch'
				end
				table.insert(query, k .. '=' .. v)
			end
		end
	else
		error('SmwUtil.set: Argument stash has wrong parameter type (' .. type(stash) .. '); must be table or string', 2)
	end
	return frame:callParserFunction{name = '#set:', args = query}
end

function p.show(page, field)
	classDebug:log(21, 'entering SmwUtil.show', 'SmwUtil.show')
	classDebug:log(23, ' with page: ' .. (page and page or 'NONE'), 'SmwUtil.show')
	classDebug:log(23, ' with field: ' .. (field and field or 'NONE'), 'SmwUtil.show')
	local frame = mw.getCurrentFrame()
	local page = page:match('^[%[]*([^%[%]]+)[%]]*$')
	local field = mw.ustring.sub( field, 1, 1 ) ~= '?' and '?' .. field or field
	return frame:callParserFunction('#show:' .. page, field)
end

function p.subobject(stash, uid)
	classDebug:log(21, 'entering SmwUtil.subobject', 'SmwUtil.subobject')
	classDebug:log(23, ' with stash: ' .. (stash and _TT.printTable(stash) or 'NONE'), 'SmwUtil.subobject')
	classDebug:log(23, ' with uid: ' .. (uid and uid or 'NONE'), 'SmwUtil.subobject')
	local frame = mw.getCurrentFrame()
	local uid = uid or ''
	local query = {}
	if type(stash) == 'string' then
		query[1] = stash
	elseif type(stash) == 'table' then
		for k, v in pairs(stash) do
			if type(v) == 'table' then
				for _, vv in pairs(v) do
					if type(vv) == 'boolean' then
						vv = vv and 'wahr' or 'falsch'
					end
					table.insert(query, k .. '=' .. vv)
				end
			else
				if type(v) == 'boolean' then
					v = v and 'wahr' or 'falsch'
				end
				table.insert(query, k .. '=' .. v)
			end
		end
	else
		error('SmwUtil.set: Argument stash has wrong parameter type (' .. type(stash) .. '); must be table or string', 2)
	end
	return frame:callParserFunction{name = '#subobject:' .. uid, args = query}
end 
-- ************************************
-- alias definition
-- ************************************

p.get = p.show
p.lua = p.ask

return p