Wikipedia:Lua/Modul/JSONutil/en

Vorlagenprogrammierung Diskussionen Lua Test Unterseiten
Modul Deutsch English Modul: Dokumentation

JSONutil – Module with functions for preparation, analysis and generation of JSON code strings.

Line breaks and tabulators within string values will be accepted and converted.

Rather than a global “Invalid” message it will be tried to detect some typical errors and communicate them together with context.

Another functionality is generating JSON source code from template syntax.

Functions for templates

General purpose

failsafe
Version management

The Failsafe interface is heading for version management of globally distributed Lua modules. It enables modules equipped with this interface to

  • ensure, that a library module required by a template or another module available as local copy does support certain functionality, or complain if not.
  • administrate global updating and linking of module codes via Wikidata.

The Failsafe interface is present both at template level and for direct Lua access.

The functions in detail are (not all supported yet completely by every library):

Parameter
Value Result current
nothing
false		 local version ID »2020-11-08«
Minimal version version ID required at least
date in ISO format

It will be compared whether the current local implementation matches this version or later.

  • empty, if minimal version not achieved
  • 2001-01-01 → »2020-11-08«
  • 2099-01-01 → »«
wikidata version ID of global upstream
  • version ID at Wikidata
  • local, if not found there
 »2020-11-08«
item ID of the Wikidata item
  • empty if not defined
 Q63869449
~ Corresponding version ID locally and registered at Wikidata
  • empty, if up to date
  • version ID at Wikidata, if not equal
 »«
@ Is the current (module) page linked correctly with Wikidata item?
  • empty, if linked to the item which is supposed
  • Iitem ID, if not
The return value is in template programming empty or under Lua false, otherwis a non-empty string as described.

Encode

These functions generate JSON source code from template syntax.

encodeArray
Create an Array with non-empty elements.
Parameters of template transclusion (all optional):
1
First element of the Array
2
Second element of the Array
3 4 5 6 7 8 9 …
Any number of further Array elements.
Parameters of #invoke:
type
data type of all elements; boolean / number / string (optional)
encodeComponent
Create a component within a mapping object.
Parameters of #invoke:
sign
name of component
value
value of component
type
data type; boolean / number / string (optional)
indent
JSON source indent level (optional number)
encodeHash
Create a mapping object.
Parameters of template transclusion (all optional):
Name1
Value1
Name2
Value2
Name3 Name4 Name5 Name6 … (any number of further components)
Value3 Value4 Value5 Value6 …
encodeI18N
Create a multilingual text.
en
text in English (recommended)
de
text in German (optional)
fr es pt zh … (any number of further languages)
text
indent
JSON source indent level (optional number)
encodeObject
Wrap components into brackets.
1
string, with components, may end with comma
indent
JSON source indent level (optional number)
encodePolyglott
Create a local or multilingual text.
1
JSON code of a multilingual text object, or plain string
indent
JSON source indent level (optional number)

Functions for Lua modules (API)

All functions described above can be used by other modules:

local lucky, JSONutil = pcall( require, "Module:JSONutil" )
if type( JSONutil ) == "table" then
    JSONutil = JSONutil.JSONutil()
else
    -- failure; JSONutil is the error message
    return "<span class=\"error\">" .. JSONutil .. "</span>"
end

Subsequently there are available:

JSONutil.failsafe( atleast )
Version ID
  • atleast
    optional
    nil or required version or "wikidata"
returns: string or false
JSONutil.fair( apply )
Reduce enhanced JSON data to strict JSON and analyse for errors.
  • apply
    string with JSON code
returns: string or false
  1. string with error keyword, or false if no complaints.
  2. string with error context, or clean JSON code if no complaints.
JSONutil.fault( alert, add, adapt )
Retrieve formatted message in best language
  • alert
    string with error keyword
  • add
    optional
    string with error context
  • adapt
    optional – language preferences
returns: string with HTML error message.
JSONutil.fetch( apply, always, adapt )
Convert JSON robust into Lua
  • apply
    string with JSON code
  • always
    optional
    true, if always preemptive test for free line format and strict JSON code being performed
    Meaningful for migration HHVM→PHP7 2019 to discover problems also in HHVM mode.
  • adapt
    optional – language preferences
returns: string or table
  • string with HTML error message in best language.
  • table with JSON data.

Language preferences

The argument adapt provides adaption of message language and might be one of these types:

Encoder

JSONutil.Encoder.Array( apply, adapt, alert )
Convert table to JSON Array.
  • apply
    table with sequence of raw elements
    string with formatted Array, or empty
  • adapt
    string with requested type, or not
  • alert
    true, if non-numeric elements shall trigger errors
returns: string with JSON Array
JSONutil.Encoder.boolean( apply )
Convert string to JSON boolean.
  • apply
    string with value
    empty null false 0 - will result in false, else true
returns: string with JSON value
JSONutil.Encoder.Component( access, apply, adapt, align )
Create a component within a mapping object.
  • access
    string with component name
  • apply
    component value
  • adapt
    string with value type, or not
  • align
    number of indentation level, or not
returns: string with JSON fragment, and comma
JSONutil.Encoder.Hash( apply, adapt, alert )
Create entries for mapping object.
  • apply
    table with element value assignments
  • adapt
    table with value types assignment, or not
returns: string with JSON fragment, and comma
JSONutil.Encoder.I18N( apply, align )
Create a multilingual text.
  • apply
    table with object, mapping codes to texts
  • align
    number of indentation level, or not
returns: string with JSON object
JSONutil.Encoder.number( apply )
Convert string to JSON number (parsing).
  • apply
    string with presumable number
    typographic minus sign permitted
returns: number, or "NaN"
JSONutil.Encoder.object( apply, align )
Wrap object components into brackets.
  • apply
    string with components, may end with comma
  • align
    number of indentation level, or not
returns: string with JSON fragment
JSONutil.Encoder.Polyglott( apply, align )
Create a local or multilingual text.
  • apply
    string with JSON string or object
  • align
    number of indentation level, or not
returns: string with JSON fragment
JSONutil.Encoder.string( apply )
Convert plain string to strict JSON string.
  • apply
    string with plain string
returns: string with quoted trimmed JSON string

Dependencies

None.

Usage

General library.

Internationalisation

See also