Modul:CargoUtil

Module documentation

[view] [edit] [history] [purge]

This module provides serveral useful function that can be used in other module to store or retrive data operating a cargo store.

Usage

local _CARGO = require('Module:CargoUtil')
if dataStore == 'cargo' and mw.title.getCurrentTitle().namespace == 10 then
	-- create table declaration, then call
	_CARGO.declare('tablename', declaration)
end
if stash then
	_CARGO.store('tablename', stash)
end
local query = {
	tables = {'table1'}
	fields = {'_pageName', '_ID', 'field1'}
	where = {'field1="hello world"', '_ID > 1'}
	order = {'_ID ASC', '_pageName DESC'}
}
local attributes = {
	limit = 1
}
local result = _CARGO.query(query, attributes)

Functions

Provided functions are as follow:

declare(dbtable, declaration)

Calls #cargo_declare with the provided parameter. Note that this parser function must be called (and therefore placed) on the template page, that later fills the table via store(dbtable, stash). See Usage-example above. Please refer to the Cargo documentation page fore more information about declaration options.

dbtable

string, mandatory

takes the name of the database table that should be declared

declaration

table or string, mandatory

holds the declaration. if provided a table, it must be formatted {fieldName : 'declaration' }

return

string, return values of the declaration call

query(query, attributes, retainBlanks)

Runs a query on the cargo store according to the parameters provided and returns the result as a lua-table. The first parameter (query) has the following mandatory fields:

tables

table or string, mandatory

the name(s) of the table(s) to query data from

fields

table or string, mandatory

the fields, you want to get data from. format is fieldname or fieldname=headline. In case of more than one table, please use tablename.fieldname or tablealias.fieldname

joins

table or string, mandatory if you have more than one table. you need one join statement for each table after the first

the list of join statements

Also, there are several optional fields:

where

table or string, optional

you can filter the results with where clauses

group

table or string, optional

the group statements

having

table or string, optional

filter your query, similar to WHERE, but applies to values computed for "groups"

order

table or string, optional

the fields, you wish to sort the result for. please use tablename.fieldname or tablealias.fieldname

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 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, see the following printout as example

The result has the following format: <-- cut 1: 1 = 'Extension:Cargo' 2 = '7' 3 = '901' 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: 1 = 'Extension:SyntaxHighlight GeSHi' 2 = '6' 3 = '911' 4 = 'The SyntaxHighlight GeSHi extension provides rich formatting of source code using the "syntaxhighlight"-tag. ...' -->

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

rawquery(query, attributes)

Calls the parser function #cargo_query 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:

tables

table or string, mandatory

the name(s) of the table(s) to query data from

fields

table or string, mandatory

the fields, you want to get data from. format is fieldname or fieldname=headline. In case of more than one table, please use tablename.fieldname or tablealias.fieldname

joins

table or string, mandatory if you have more than one table. you need one join statement for each table after the first

the list of join statements

Also, there are several optional fields:

where

table or string, optional

you can filter the results with where clauses

group

table or string, optional

the group statements

having

table or string, optional

filter your query, similar to WHERE, but applies to values computed for "groups"

order

table or string, optional

the fields, you wish to sort the result for. please use tablename.fieldname or tablealias.fieldname

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 query (like limit, for instance)

return

string, the renderd output

store(dbtable, stash)

Calls #cargo_store with the provided parameters. Note that the table must be declared and created before you can actually store anything.

dbtable

string, mandatory

takes the name of the database table to be filled

stash

table (!), mandatory

holds the data to store. it must be formatted {fieldName : data of type string or integer }

return

string, return values of the store call

The above documentation is transcluded from Modul:CargoUtil/doc. (edit | history)
Editors can experiment in this module's sandbox (create | mirror) and testcases (create) pages.
Please add categories to the /doc subpage. Subpages of this module.

local p = {}
local getArgs = require('Module:Arguments').getArgs
local classDebug = require('Module:Debug/class')
local _TT = require('Module:TableTools')
local cargo
if mw.ext and mw.ext.cargo then
	cargo = mw.ext.cargo
else
	cargo = {}
end

function prepareQueryParam(query)
	classDebug:log(21, 'entering CargoUtil.prepareQueryParam', 'CargoUtil')
	if query.tables and #query.tables > 0 and query.fields and #query.fields > 0 then
		if type(query.tables) == 'table' then
			query.tables = table.concat(query.tables, ', ')
		end
		if not query.joins then
			query.joins = query.join
		end
		if query.joins and type(query.joins) == 'table' then
			query.joins = table.concat(query.joins, ', ')
		end
		if type(query.fields) == 'table' then
			query.fields = table.concat(query.fields, ', ')
		end
		if query.where and type(query.where) == 'table' then
			if query.where[1] then	-- sequence assumed
				query.where = table.concat(query.where, ' AND ')
			else
				local where = ''
				for k, v in pairs(query.where) do
					where = where .. k .. '=' .. v .. ' AND '
				end
				query.where = where .. '1 '
			end
		end
		if query.group and type(query.group) == 'table' then
			query.group = table.concat(query.group, ', ')
		end
		if query.having and type(query.having) == 'table' then
			if query.having[1] then	-- sequence assumed
					query.having = table.concat(query.having, ', ')
			else
				local having = ''
				for k, v in pairs(query.having) do
					having = having .. k .. '=' .. v .. ', '
				end
				query.having = mw.ustring.sub(having, 1, -3)
			end
		end
		if query.order and type(query.order) == 'table' then
			query.order = table.concat(query.order, ', ')
		end
		return query
	else
		if tables and #tables > 0 then
			error('Argument query.tables is missing or empty! (calling from ' .. tostring(self) .. ')', 2)
		else
			error('Argument query.fields is missing or empty! (calling from ' .. tostring(self) .. ')', 2)
		end
		return nil
	end	
end

function p.attach(dbtable)
	classDebug:log(21, 'entering CargoUtil.attach', 'CargoUtil.attach')
	classDebug:log(22, ' with table "' .. dbtable .. '"')
	local frame = mw.getCurrentFrame()
	local ret = false
	ret = frame:callParserFunction('#cargo_attach:_table=' .. dbtable)
	return ret
end

function p.declare(dbtable, dbfields)
	classDebug:log(21, 'entering CargoUtil.declare', 'CargoUtil.declare')
	classDebug:log(22, ' with table "' .. dbtable .. '" and fields ' ..
		(type(dbfields) == "string" and '"' .. dbfields .. '"' or 'of type ' .. type(dbfields)), 'CargoUtil.declare')
	if type(dbfields) == "table" then
		classDebug:log(23, ' datatable: ' .. _TT.printTable(dbfields), 'CargoUtil.declare')
	end
	local frame = mw.getCurrentFrame()
	local ret = false
	if type(dbfields) == "string" then
		ret = frame:callParserFunction('#cargo_declare:_table=' .. dbtable, dbfields)
	elseif type(dbfields) == "table" then
		ret = frame:callParserFunction{name = '#cargo_declare:_table=' .. dbtable, args = dbfields}
	end
	return ret
end

function p.query(query, attributes, retainBlanks)
	classDebug:log(21, 'entering CargoUtil.query', 'CargoUtil.query')
	classDebug:log(23, ' with query: ' .. (query and _TT.printTable(query) or 'NONE'), 'CargoUtil.query')
	classDebug:log(23, ' with attributes: ' .. (attributes and _TT.printTable(attributes) or 'NONE'), 'CargoUtil.query')
	local attributes = attributes or {}
	if type(attributes) ~= 'table' then
		attributes = {attributes}
	end
	-- CargoUtil.query() allows for query.paramters (like table, where, etc) to be tables. cargo.query only takes strings. remedy this here
	local query = prepareQueryParam(query)
	local args = {
		where = query.where,
		join = query.joins,
		groupBy = query.group,
		having = query.having,
		orderBy = query.order,
		limit = attributes.limit
	}
	local result = cargo.query(query.tables, query.fields, args)

	local ret = {}
	for num, row in pairs(result) do
		local newRow = {}
		for key, value in pairs(row) do
			if mw.ustring.len(mw.text.trim(value)) > 0 or retainBlanks then
				newRow[key] = value
				-- cargo interprets underscored (_) as spaces in fieldnames (keys). so copy the entry
				if mw.ustring.find(key, ' ') then
					local newKey = mw.ustring.gsub(key, ' ', '_')
					if not newRow[newKey] then
						newRow[newKey] = newRow[key]
					end
				end
			end
		end
		ret[num] = newRow
	end

	return ret
end

function p.rawquery(query, attributes)
	classDebug:log(21, 'entering CargoUtil.rawquery', 'CargoUtil.rawquery')
	classDebug:log(23, ' with query: ' .. (query and _TT.printTable(query) or 'NONE'), 'CargoUtil.rawquery')
	classDebug:log(23, ' with attributes: ' .. (attributes and _TT.printTable(attributes) or 'NONE'), 'CargoUtil.rawquery')
	local query = prepareQueryParam(query)
	local frame = mw.getCurrentFrame()
	local tables = query.tables
	local arguments = attributes or {}
	arguments.fields = query.fields
	arguments['join on'] = query.joins
	arguments.where = query.where
	arguments['group by'] = query.group
	arguments.having = query.having
	arguments['order by'] = query.order
	classDebug:log(24, ' calling parser function with tables: ' .. tables .. ' and arguments: ' .. _TT.printTable(arguments))
	return frame:callParserFunction{ name='#cargo_query:tables=' .. tables, args = arguments }
end

function p.store(dbtable, data)
	classDebug:log(21, 'entering CargoUtil.store')
	classDebug:log(22, ' with table "' .. dbtable .. '" and data ' ..
		(type(data) == "string" and '"' .. data .. '"' or 'of type ' .. type(data)))
	if type(data) == "table" then
		classDebug:log(23, ' datatable: ' .. _TT.printTable(data))
	end
	local ret = false
	if type(data) == "table" then
		for k, v in pairs(data) do
			if type(v) == 'boolean' then
				data[k] = v and 1 or 0
			end
		end
		local frame = mw.getCurrentFrame()
		ret = frame:callParserFunction{name = '#cargo_store:_table=' .. dbtable, args = data}
	end
	return ret
end

return p