Bruker:Jeblad/Module:JSONstat
Dokumentasjon
The purpose of this module is to demonstrate handling of JSON-stat in Lua with closure-based instances modelled as lazy facades. The instances will not be created before boundraries are passed, that is a method returns a value that is wrapped in a closure. This makes a fairly efficient implementation for simple access.
The library can be used as simple calls through the invoke parser function, or as a support library. A main purpose for the lib is to provide Vega-formatted data, often constrained or adapted somehow to fit better with other available data.
Primary access point is the load-method, which will parse one of several sources and return an instance according to the provided data. In Lua-code the instance can be navigated by using provided methods, while in wikitext it is possible to use layout (format) parameters. One such predefined layout could be to create data for Vega, which is nothing more than the dataset values as an expanded table.
Usage
In wikicode the module will typically be called like one of the following
{{#invoke:JSONstat | load | updated }}
{{#invoke:JSONstat | load | Q123456 | label }}
{{#invoke:JSONstat | load | Bruker:Jeblad/SSB01222.json | ${source:%.10s} }}
{{#invoke:JSONstat | load | { ... } | expanded }}
The first call use the connected item to identify the external JSON-stat dataset (not implemented). The layout updated reports the datestamp when the dataset was last updated.
The second call identifies an item to use for further identification of a JSON-dataset (not implemented). The layout label reports the label for the dataset.
The third call identifies a page that contain the dataset. This use an inline format for layout, and reports a truncated source string.
The fourth call use an inline definition of the dataset. This use a layout that reports the values from the expanded form, that is a form that can be used in Vega.
Similar calls in Lua-code would be like the following
local jsonstat = require('Module:JSONstat')
jsonstat.load().updated()
jsonstat.load( 'updated' )
jsonstat.load( 'Q123456' ).label()
jsonstat.load( 'Q123456', 'label' )
jsonstat.load( 'Bruker:Jeblad/SSB01222.json' ).layout( '${source:%.10s}' )
jsonstat.load( 'Bruker:Jeblad/SSB01222.json', '${source:%.10s}' )
jsonstat.load( '{ ... }' ).expanded()
jsonstat.load( '{ ... }', 'expanded' )
-- module for processing JSON-stat
-- © John Erling Blad, Creative Commons by Attribution 3.0
-- dump provided structure
-- @param any out structure to dump
-- @return string representing the structure
function dump( out )
if type( out ) == 'table' then
local s = '{ '
for k,v in pairs( out ) do
if type( k ) ~= 'number' then k = '"'..k..'"' end
s = s .. '['..k..'] = ' .. dump( v ) .. ','
end
return s .. '} '
else
return tostring( out )
end
end
-- @var forward declaration
local JSONstat
-- Constructor for axis'
-- Note that this has no explicit structure in JSON-stat
-- @param table init structure kept for later
-- @return self
local function JsAxis( init )
local self = {}
local data = init
-- constructure signature
-- @return string
function self.signature()
return 'JsAxis'
end
-- provide a valid table structure
-- @return table
function self.toTable()
return data
end
-- this is our instance
return self
end
local function JsCollection( init )
local self = {}
local data = init
-- constructure signature
-- @return string
function self.signature()
return 'JsCollection'
end
-- provide a valid table structure
-- @return table
function self.toTable()
return data
end
-- get the class value
-- note that this may not exist
-- @return string
function self.class()
return data['class']
end
-- this is our instance
return self
end
local function JsDimension( init )
local self = {}
local data = init
-- constructure signature
-- @return string
function self.signature()
return 'JsDimension'
end
-- provide a valid table structure
-- @return table
function self.toTable()
return data
end
-- get the class value
-- note that this may not exist
-- @return string
function self.class()
return data['class']
end
-- get the time of the update
-- note that this may not exist
-- @return string formatted according to ISO8601
function self.updated()
return data['updated']
end
-- get the id of all axis'
-- should always exist
-- @return table
function self.id()
return data['id']
end
-- get the size of all axis'
-- should always exist
-- @return table
function self.size()
return data['size']
end
-- @todo
function self.role()
return data['role']
end
-- evaluate provided function for each id, supplying the axis'
-- @param function f callback to be evaluated
function self.each( f )
for k,v in data['id'] do
f( k, v, JsAxis(data[v]) )
end
end
-- this is our instance
return self
end
local function JsDataset( init )
local self = {}
local data = init
-- constructure signature
-- @return string
function self.signature()
return 'JsDataset'
end
-- provide a valid table structure
-- @return table
function self.toTable()
return data
end
-- get the class value
-- note that this may not exist
-- @return string
function self.class()
return data['class']
end
-- this has no children
-- this will change type if sparse
function self.value(...)
local indexes = arg
return data['value']
end
-- this has no children
-- this can be a table
function self.status()
return data['status']
end
-- at this level it should be a string
function self.label()
return data['label']
end
-- a language dependant string
-- note that there are no language marker
function self.source()
return data['source']
end
-- get the time of the update
-- note that this may not exist
-- @return string formatted according to ISO8601
function self.updated()
return data['updated']
end
--
-- @return JsDimension
function self.dimension()
return JsDimension( data['dimension'] )
end
-- evaluate the provided function for each table cell
-- @todo this only uses the linear index
-- @param function f the callback to be evaluated for each data value
-- @return none
function self.each( f )
local size = data['dimension']['size']
for k,v in ipairs( data['value'] ) do
local idx = {}
local remainder = k
for k2,v2 in ipair( size ) do
remainder = remainder % k2
insert(idx, remainder)
end
f( idx, v )
end
end
-- reformat a table by slicng through it
-- @param varargs
-- @return JsDataset
function self.slice(...)
end
-- this is our instance
return self
end
local function JsBundle( init )
local self = {}
local data = init
-- constructure signature
-- @return string
function self.signature()
return 'JsBundle'
end
-- provide a valid table structure
-- @return table
function self.toTable()
return data
end
function self.get(...)
local ids = {}
for _,v in ipairs( arg ) do
ids[v] = true
end
local items = {}
for k,v in ipairs( data ) do
if ids[k] then
table.insert( items, JSONstat( v ) )
end
end
return items
end
-- this is our instance
return self
end
-- helper to do all the clean typecasts
-- @param table init data structure to recast as instances
-- @return function closures representing instances
local function JSONstat( init )
local class = init['class']
if not class then
if init['dataset'] then
return JsDataset( init['dataset'] )
elseif init['dimension'] then
return JsDimension( init['dimension'] )
elseif init['collection'] then
return JsCollection( init['collection'] )
end
return JsBundle( init ) -- this seems to be correct
elseif class == 'dataset' then
return JsDataset( init )
elseif class == 'dimension' then
return JsDimension( init )
elseif class == 'collection' then
return JsCollection( init )
end
return JsBundle( init ) -- not sure if this is correct
end
-- helper to do all the dirty parsing
-- @todo make a better description
-- @param vararg
-- - nil is assumed to imply indirection
-- - table is assumed to be a frame
-- @return function closures representing instances
local function js(...)
local anon = arg[1]
local frame
if type( anon ) == 'table' then
frame = anon
anon = frame.args[1]
end
local instance
if type(anon) == 'nil' then
-- @todo follow wikidata to stat description
elseif type(anon) == 'string' then
if string.match(anon, '^\s+\{') then
-- inline definition of data
local data = mw.text.jsonDecode( anon )
if data then
instance = JSONstat( data )
end
elseif string.match(anon, '^\s*[QP]%d+\s*$') then
-- @todo go to defined page at wikidata to get a stat description
elseif string.match(anon, '\.json\s*$') then
-- go to defined page to get a stat description
if frame then
local raw = frame:expandTemplate{ title = anon }
if raw then
local data = mw.text.jsonDecode( raw )
if data then
instance = JSONstat( data )
end
end
end
end
elseif type(anon) == 'function' then
instance = JSONstat( anon() )
end
return instance
end
-- @var exported table
local p = {}
-- load function for public access
-- note that this is only for trivial testing
-- @param table frame arguments passed from Mediawiki
-- @return string representing the result
function p.load( frame )
local instance = js( frame )
return dump(instance.dimension().id())
end
-- export the accesspoint
return p