Modul:SmwUtil

Permanently protected module
ZIM HilfeWiki - das Wiki
Documentation icon Module documentation

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


{
	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
Cookies helfen uns bei der Bereitstellung des ZIM HilfeWikis. Bei der Nutzung vom ZIM HilfeWiki werden die in der Datenschutzerklärung beschriebenen Cookies gespeichert.