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

string with error keyword, or false if no complaints.
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:

function – Callback
- Return value is best message text
- Two arguments:
  1. table, with mapping: language code → message text
  2. string, optional, with message text if table fails
- i18n@Multilingual would work
string – space-separated list of preferred language codes
false/nil – project language, else English

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

commons:Data:I18n/Module:JSONutil.tab – Text elements
Error messages will be shown in user or project language, if available.