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:

• 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.

See also

• jsonDebug@PerfektesChaos – User JavaScript for detailed analysis of fatal JSON errors