Module:JSONutil/doc

Usage

General library module with functions for preparation, analysis and generation of JSON code strings.

{{#invoke:JSONutil|function_name}}

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.

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

number JSON source indent level (optional)

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 es fr pt zh … (any number of further languages)

text

indent

number JSON source indent level (optional)

encodeObject

Wrap components into brackets.

1

string with components, may end with comma

indent

number JSON source indent level (optional)

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|failsafe]](atleast)

Version ID

• atleast

  nil or required version or wikidata (optional)

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

  string with error context (optional)

• adapt

  language preferences (optional)

Returns: string with HTML error message.

JSONutil.fetch(apply, always, adapt)

Convert JSON robust into Lua.

• apply

  string with JSON code

• always

  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. (optional)

• adapt

  language preferences (optional)

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 with message text if table fails (optional)
  • 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.

Internationalization

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

See also

• jsonDebug by User:PerfektesChaos – User JavaScript for detailed analysis of fatal JSON errors.