Quelltext der Seite Modul:SmwUtil/doc

{{documentation subpage}}
{{module rating|protected}}
<!-- Categories go at the bottom of this page and interwikis go in Wikidata. -->

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

== Usage ==
{{code|lang=lua|code=
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 ==
Provided functions are as follow:

=== ask(query, attributes, retainBlanks) ===
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 {{code snippet|lang=lua|code={ propertyname = 'value' } }}, {{code snippet|lang=lua|code={ '[[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 <code>retainBlanks</code> 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

{{ombox|type=delete|text=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.}}

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

{{code|lang=lua|code=
{
	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) ===
A shortcut for [[#show(page, field)|show(page, field)]].

=== lua(query, attributes, retainBlanks) ===
A shortcut for [[#ask(query, attributes, retainBlanks)|ask(query, attributes, retainBlanks)]].

=== rawask(query, attributes) ===
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 {{code snippet|lang=lua|code={ propertyname : 'value' } }}, {{code snippet|lang=lua|code={ '[[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 <code>retainBlanks</code> 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) ===
Stores provided ''stash'' in semantic triple stores.

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

=== show(page, field) ===
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) ===
Stores provided ''stash'' as a subject. Contrary to [[#set(stash)|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 {{code snippet|lang=lua|code='has property=value' }}, one triple can be stores. if provided as table, you can either use {{code snippet|lang=lua|code={ has property = 'value' } }}, {{code snippet|lang=lua|code={ 'has propert=value' } }}, or a mix thereof. Even {{code snippet|lang=lua|code={ 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

[[Category:Class engine]]<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
<!-- Categories go here if you wish an additional category to that set in {{module rating}} above automatically. -->
[[Category:Lua metamodules]]
}}</includeonly><!-- null edit comment; remove -->