MediaWiki:Scribunto/Central modules reference manual

La bibliothèque libre.
Aller à : navigation, rechercher
THIS MANUAL IS ONLY IN DRAFT STATE
Some parts are empty or missing
- - -
THIS DOCUMENT CAN DISPLAY ONLY 10 DROPBOXES IN LIVE UNTIL CENTRAL LIBRARIES BECOME PART OF SCRIBUNTO
- - -
In this document, Library: is not a namespace, only a way to shortly express that an object is understood as a library.

This manual documents the Lua part of central modules support for any central modules in w:Lua as they are used in MediaWiki with the Scribunto extension.

See also the guidelines Manual:Developing libraries.

Sommaire

Introduction

The central system permits to convert any module as central. It is build on Mediawiki, Scribunto and Wikibase.

Documentations

Tests pages

Central libraries: Module:Central.

Simple examples of uses: Module:Central/Documentation

Full example: User:Rical/Victor_Hugo.

Central libraries in brief

In this document, Library: is not a namespace, only a way to shortly express that an object is understood as a library.

The central system permits to convert any module as central.

The Lua part of central modules support contains some libraries used by central modules.

The Module:Central installs central libraries (waiting a stable Scribunto central repository).

Central libraries are intimately dependent of each others. Examples: the Library:versions installs others and the Library:viewers is usefull anywhere.

Stability

Central modules specially must be stable. Some supports for stability:

  • Central modules must follow S.O.L.I.D recommendations. Lua-coders can ask help from their pairs if necessary, see https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)
  • Which kind and level of stability do we need to begin to use central modules?
  • Which kind and level of stability do we need to really centralize?
  • How to insure a hight level of stability?
    • Run many tests for key functions.
    • Display groups of tests for Lua-coders. Then they can detect errors or missing tests cases.
    • Notify and alert central Lua-coders using errors and categories.
    • Document all functions supporting stability and listing all actual fonctions to not miss some ones.
    • Save and restore main configurations for each group of tests to better avoid mutual perturbations between them.
    • Display tests in any documentations pages, in live.
    • Search other means to increase the stability and report them.

Stability guideline

Some questions are especially important for all developers in the early phase of the deployment of central modules.

Libraries and functions names must be stable before a large deployment to reduce the renaming of them. That could imply heavy corrections after the begin phase.

Stability questions:

  • How to name central libraries ?
  • How to name functions in these libraries ?
  • How to distribute the functions in one or some libraries ?

Some examples:

  • The Library:lua_table enhances the previous table library, to avoid ambiguities.
To enhance Scribunto table, we could write: lua_table = table.
  • Too diversity in the styles of variables names result in difficulties to remember their names for Lua-coders. They are sources of errors and of losts of time.
  • How to distribute the functions in one or some libraries ?
Do we want a library args separed from the existing library modes, to easier identity the main job of each function?

Stability tasks

  • Same tests of functions are available for Mediawiki testframework and for Lua-coders in tests mode.
  • The versions library installs sought sub-modules using versions support.
  • Drop boxes and tables views help to easy format new tests.
  • The activity library help to manage sub-tasks and phabricator tasks, between Lua-coders, projects and languages.
  • The tracker object supports parametrable track objects to help to debug the Lua code.
  • The events library formats events as errors, warnings and categories.
  • In many functions in the Lua code, strict type checks of values reduce errors risks.
  • The initial development in the same text file enhance the cohesion in values, variables and functions.
  • The function save_configs() saves global configuration before eventual changes in tests. And restore_configs() restore it.

Central supports

The central system permit some new supports.

Languages support

Central modules support translations in many languages, using i18n tables.
They support also the content, page and user languages, depending of complex reasons in each case.
The system can also suggest a default local language depending where the module is used.
For these goals, central modules get these languages from the system, modes, options, arguments and tests cases.

Translations support

The langs library supports i18n translations.

  • It also detects missing translations between languages.
  • It merges translations together from libraries, sub-modules and the main module.
  • It also detects the translations changes in the main module compared to more inner other translations.

In i18n tables, each translation key begin with the module or library name, to not disturb other and future translations.
An alternative version can modify any translation of the normal version.
A main module can modify any translation from any submodule to adapt it to a new context.

A /I18N submodule can adapt any translation from a normal or new version.

  • Each module or sub-module has its own /I18N submodule.

Then the versions.bind_modules(p)function follows these rules:

  • Starts with the libraries translations,
  • starts with the internal translations,
  • then add or mix translations from normal /I18N,
  • then add or mix translations from the /I18N alternative versions,
  • Continue with the modules translations,
  • starts with the internal translations,
  • then add or mix translations from normal /I18N,
  • then add or mix translations from the /I18N alternative versions.
  • In doc and tests modes, a report display missing or modified translations.

Versions support

To activate the versions support of a module, start it with a definition of alternative versions of its sub-modules, like this:

p.version = { -- Modules dependencies. Dependencias del módulo. Dépendances du module.
	sought = "Central-s-fr;Central;DropBox;Mathroman22;TestRequire", -- Sought module and submodules versions
	known = "Central-s-fr;Central;Central-14 * DropBox;DropBox-2 * Mathroman22;Mathroman34", -- Known module and submodules versions
}

Proposed guideline for versions numbers: They follow the format major.minor.release.
The major number is incremented when there's a big change in functionality.
Template or invoke arguments can replace soughtversions and knownversions.
In known versions, the first of each group of versions is the normal one and can replace any other if not available.
The versions support require() adequate versions of submodules, following known and sought versions, like Module:Box 2.
The versions support reports: versions used, errors, missing or replaced by normal ones.
Then Lua-coders can better understand what happens.
Any Lua-coder of main module can select versions of its submodules from internal arguments or from template arguments.
Each module or sub-module must document its version and date-time.
The typical version description lookalikes to:

p.version = { -- Modules dependencies. Dependencias del módulo. Dépendances du module.
	versionName = "Central-s-fr", versionNumber = "1.0.0(180521:04:56)", versionDate = "2018-05-21T04:56:00",
	-- UTC version structure :		  main.fonction.task(yymmdd:hh:mm)
	mainDescription = "Begin to use", functionDescription = "first functional support", taskDescription = "Update to 'Begin' on T20180527 approximately",
}

Initialize a module

As a fisrt step, define the options to select which part to format or to discard.
Each option like "box1" have an oposite like "nobox1" and the oposite has the priority if the two are present.

p.options_for_modes = { -- default options<!--Doc 20171103 DocTodo DocOK -->
	read	= " noerr ",
	doc		= " noerr nobox1 nocatview ",
	edit	= " : catview docview docdef docline docsrc docdata ",
	tests	= " : catview docview docdef docline docsrc docdata tests ",
	-- Option nocatview means "Do not categorize and do not show categories."
}

Modes and options

Modes are modifiable in any way in the main module, even making new ones or masking them.
Default modes are 4 ways to display the result of a central module:

  • The read mode is for simple readers of wikipedia, the default mode.
  • The doc mode is to display, in live, one dropbox to include in a technical documentations about the module.
  • The edit mode serves to help wikipedia users when they edit a page containing a module which is bad used.
  • The tests mode is to support Lua-coders who change a module and who need to see the results of several tests.

Modes are adaptable using options to adjust what and how to display the result:

  • Arguments can change default options and modes like in {{Central|doc|dockey=versions_support_desk_title|docitem=Q535}}.
  • Default modes and options come from p.options_for_modes:
p.options_for_modes = { -- default options
	read	= " box1 noerr ", -- For simple readers of a page.
	doc		= " noerr nobox1 nocatview ", -- To display a live example in a documentation page.
	edit	= " box1 docdef docline docsrc docdata catview docview ", -- To support the user who edit a page.
	tests	= " box1 catview docdef docline docsrc docdata docview tests docGroup ", -- To report several tests cases for each function.
	-- Option nocatview means "Do not show categories."
}

Default options permit to adapt modes:

  • Each option has its canceller, as for catview and nocatview, and the canceller has the priority over the option.
  • The box1 option asks to display the box 1.
  • The nobox1 option asks to mask the box 1.
  • The err option asks to enforce errors and warnings.
  • The noerr option asks to mask errors and warnings.
  • The catview option asks to display the categories to activate.
  • The nocatview option asks to mask the categories to activate.
  • The docdef option asks to display origin of arguments and others details...
  • The nodocdef option asks to mask these details.
  • The docline option asks to display these details in a single line.
  • The nodocline option asks to display these details in a list of line.
  • The docsrc option asks to display the origins of arguments.
  • The nodocsrc option asks to mask the origins of arguments.
  • The docdata option asks to display datas coming from the Wikibase.
  • The nodocdata option asks to mask datas coming from the Wikibase.
  • The tests option asks to display the tests part of the result, after boxes to view.
  • The notests option asks to mask the tests part of the result, after boxes to view.
  • The docGroup option asks to display all technical documentations about the module.
  • The nodocGroup option asks to mask all technical documentations about the module.

Arguments: their process and translations

Main tables of arguments:
modes.args_known:
The main module defines all arguments, and they all must have translations in all availables languages.
modes.args_source: The source arguments come from template, else from #invoke, for each argument.
modes.args_config : Memorizes direct configuration arguments.
modes.args_wikidata : An argument can come from wikidata if its definition have a wikidata property like prop = "P21".
The priority in origin of an argument is always: first the template, else the { {#invoke:module, else the internal interaction between arguments in the module, else the internal default value in the module.
modes.args_config: The config arguments come from source arguments and translations are identical in all languages.
Rough summary of the process of integration of arguments and translations:

	modes.args_known = {} -- Known arguments, at main module level
	modes.args_template = {} -- Template arguments, at {{Template| ...}} level
	modes.args_invoke = {} -- Invoke arguments, at {{#invoke: ...}} level
	modes.args_source = {} -- Source arguments = args_template + args_invoke
	modes.args_unknown = {} -- Unknown arguments
	modes.args_wikidata = {} -- Wikidata arguments, from Wikibase
	modes.args_import = {} -- Import arguments
	modes.args_final = p.interact_args_final() -- Final arguments, after interactions between them
	modes.args_selected = {} -- Selected arguments, in some modules
	langs.wiki_translations = {} -- Wiki translations
	langs.user_translations = {} -- User translations
	langs.page_translations = {} -- Page translations
	events.errors_list = {} -- Errors list to collect, display or activate arguments errors and warnings
	events.categories_list = {} -- Categories lists to collect, display or activate arguments errors and warnings
	langs.init_content_page_user_lang(modes.args_source.contentlang, modes.args_source.pagelang, modes.args_source.userlang)

Available options to define one argument:

	birthyear = {				-- Key of the argument.
		--
		keyword = "birthyear",	-- The keyword is the same as Key to identify the argument in some cases.
		syn = 1,				-- A synonym of an argument defined in the args_known table.
		keyword = "birthyear2",	-- For a synonym, the keyword identify the referral argument.
		-- A synonym can be another argument. Then interact_args_final(args_import) mixes them.
		--
		typ = "dat",			-- The type "dat" is the basic type of arguments.
		typ = "config",			-- The type "config" groups direct arguments from modes.args_source, without translation.
		--
		need = 1,				-- If need == 1 the argument can be automatic.
		need = 2,				-- If need == 2 the argument must come from the template or wikidata.
		--
		prop = "P569",			-- Wikidata property to automatic import an argument, if available.
		format = "year",		-- Extract the year from a Wikidata property.
	},
}


Arguments properties

They can be needed, synonym, limited to some values ... typical examples:

	language =	{keyword = "language", typ = "dat", need = 0, prop = "P103", }, -- Simple argument, with wikidata property.
	[1] =		{keyword = "mode", typ = "sys", need = 0, syn = 2, }, -- Synonym or alias of an argument defined by position.
	c =			{keyword = "c", typ = "dat", need = 0, syn = 1, }, -- Synonym or alias arguments.
	options =	{keyword = "c", typ = "dat", need = 0, syn = 2, }, -- Synonym or alias arguments.
	-- Argument limited to some values.
	region =	{keyword = "region", typ = "dat", need = 0, -- like Simple argument
		arg_values = "region_values", key_values = "other,china,india,century" }, -- arg_values translation key for
	region_values	= "autre,chine,inde,siècle", -- i18n french translations for region argument.
	region_values	= 'otros,china,india,siglo', -- i18n spanish translations for region argument.
	-- Argument and its description.
	options			= 'options', -- Arguments can be described for documentation in tests or in doc mode.
	options_descr	= 'Options to add with mode options.',

Arguments from template to configure supports

They drive directly supports aspects, without translations, examples:

	contentlang = "en", -- content language for i18n translations.
	pagelang = "fr", -- page language for i18n translations.
	userlang = "fr", -- user language for i18n translations.
	mode = "read", -- default mode
	options =	"", -- to change options for modes
	c =	"", -- for the catview option, to really categorise
	c =	":", -- for the catview option, to display categories
	soughtversions = "", -- Lua-coders can change sought versions when they change a module.
	knownversions =	"", -- Lua-coders can change known versions when they change a module.
	-- for datas from the Wikibase
	dockey =	"tools_args_known_structure_title", -- key to select a dropbox to display in doc mode.
	docitem = "Q535", -- wikidata element to display in doc mode.

Translations keys

They follow the guideline below. There suffix have a functional role.

  • Translations keys are always formated with only underlines names like in begin_central_modules_support.
  • The structure of keys must respect this rules:
  • They begin with the library name like in langs_lang_table_err_cat
  • They finish with _cat to translate a category name.
  • They finish with _err to translate an error string.
  • They finish with _headers to translate headers for a table in lines and colums.
  • They finish with _msg to translate a message like: "Verify the automatic argument: %1 = %2.".
  • They finish with _report to translate a title for a documentation, in or out of a dropbox.
  • They finish with _title to translate a title for a documentation in a dropbox.
  • They can finish with _i_cat to generate a second category for internal errors
  • They can finish with _u_cat to generate a second category for user errors
  • Some examples of keys:
langs.i18n = {}
langs.i18n.en = { -- English translations, begin
	modes_auto_val_warning_msg		= "Verify the automatic argument: %1 = <b>%2</b>.", -- Example of message
	langs_lang_not_exist_err		= "Error: The language <b>%1</b> is not available.", -- Example of error
	langs_lang_table_err_cat		= "Module with internal error", -- Example of category
	tests_page_tests_h3_title		= "Tests of this page",	-- Example of title of DropBox, or anywhere.
	versions_loaded_modules_headers	= "Title, Version, Date, I18N, Translations / Languages", -- Example of headers in a tableview
	versions_versionsmanagement_report	= "Versions support report", -- Example of title of report
	--
	options							= 'options', -- Argument to describe.
	options_descr					= 'Options to add to mode options.', -- Description for an argument. The key ends with "_descr".
} -- langs.i18n.en -- English translations, end
langs.i18n.es = { -- Spanish translations, begin

Convert a module as central or centralisable

The support of central modules needs some dedicated functions and descriptions of arguments, translations, modes, options, versions...
Rough example of code:

--	The Module:Example define its version and sub-modules:
p.version = { -- Modules dependencies. Dependencias del módulo. Dépendances du module.
	versionName = "Example", versionNumber = "180313.10:31", versionDate = "2018-03-13 10:31", -- UTC
	versionDescription = "central_description",
	sought = "Example;Mathroman22;TestRequire", -- Sought module and submodules versions
	known = "Example;Example-14 * Mathroman22;Mathroman34 * TestBug;TestBug4", -- Known module and submodules versions
}
--	The Module:Example define arguments:
p.args_known = { -- Table of the definitions of all known arguments at module level. -- ric (p.box1)
	["mode"]			= { ["typ"] = "config",	["need"] = 0,	["keyword"] = "mode"},
	["userlang"]		= { ["typ"] = "config",	["need"] = 0,	["keyword"] = "userlang"},
	["image"]			= { ["typ"] = "dat",	["need"] = 2,	["image"]	= "description",["prop"] = "P18", },
	["country"]			= { ["typ"] = "dat",	["need"] = 0,	["keyword"] = "country",	["prop"] = "P27", },
	["birthyear"]		= { ["typ"] = "dat",	["need"] = 2,	["keyword"] = "birthyear",	["prop"] = "P569", ["format"] = "year", },
	["lastname"]		= { ["typ"] = "dat",	["need"] = 0,	["keyword"] = "lastname",	["prop"] = "P734", },
	["itemid"]			= { ["typ"] = "dat",	["need"] = 2,	["keyword"] = "QITEM",		["prop"] = "Q16222597", ["syn"] = 2, },
}
--	The Module:Example initialise languages, including arguments names:
p.i18n = {} -- translations tables known in the module
p.i18n.en = {
	["mode"]							= 'mode',
	["userlang"]						= 'userlang',
	["itemid"]							= 'itemid',
	["example_user_sentence"]			= 'Vous parlez français.',
	["example_user_mode"]				= 'You are in mode: %1', -- where %1 will be replaced
} -- p.i18n.en
p.i18n.es = {
	["mode"]							= 'mode',
	["userlang"]						= 'userlang',
	["itemid"]							= 'itemid',
	["example_user_sentence"]			= 'Usted habla francés.',
	["example_user_mode"]				= 'Estás en modo: %1', -- donde %1 será reemplazado
} -- p.i18n.es
p.i18n.fr = {
	["mode"]							= 'mode',
	["userlang"]						= 'userlang',
	["itemid"]							= 'itemid',
	["example_user_sentence"]			= 'Vous parlez français.',
	["example_user_mode"]				= 'Vous êtes en mode : %1', -- où %1 sera remplacé
} -- p.i18n.fr

--	The Module:Example define options for modes...
p.options_for_modes = { -- module options_for_modes
	read	= " box1 catview ",
	edit	= " box1 docdef docline docsrc docdata catview docview : ",
	doc		= " nobox1 noerr nocatview ",
	tests	= " box1 catview docdef docline docsrc docdata docview : tests docGroup ",
}
--	The Module:Example formats a result wikicode to return to the page.
function Central.read(frame) -- The read mode generates the normal result for read only users.
	local txt = Central.init(frame, Central.Central_version, "read", p.args_known, p.options_for_modes)
	local itemid = p.args_known["itemid"].val
	local res = viewers.form9user( "example_user_mode", itemid )
	return res
end -- function Central.read(frame)
return p --	The Module:Example returns the wikicode to the page.

Translate arguments, errors, categories...

To add a new language, only do add dedicated i18n tables in the main module or the sub-module /I18N.
The recognition of mediawiki languages is automatic, the others are not available.
For an easier support of translations, the Lua-coders group them in Module:Library/langs/I18N.

Examples of translated arguments names, their descriptions, errors, categories, titles...
p.i18n.en = { -- English
	mode 							= "mode", -- All arguments must be translated in all languages to operate.
	mode_descr						= "Type of use of the module or template: read, edit, doc, tests...", -- Describe the argument for documentation.
	options 						= "options",
	options_descr					= "Options to format the module or template result.",
	firstname						= 'firstname', -- Other argument and description
	firstname_descr					= "First name. Please, specify it to help to compute the sort key.",
	mathroman_J_before_end_err		= "character J before the end", -- Example of error.
	mathroman_roman2int_test_title	= "Test from digital to roman numbers", -- Example of title of a group of tests.
	modes_language_cat				= 'Speaking %1', -- Example of category.
	modes_date_to_part_call_cat		= "Module with internal error", -- Several errors are grouped in a same category, defined at translation level.
	modes_needed_to_verify			= "(required, to be checked)", -- In the list of arguments, an argument is needed
}

Define arguments

  • All arguments must be translated in all needed languages to operate.
  • And all known arguments must be defined to operate. Even if they are not used at template or invoke level.
p.args_known = { -- Too small example of definitions of all known arguments at the main module level.
	birthyear	= {typ = "dat", need = 0, keyword = "birthyear", prop = "P569", format = "year"},
	country		= {typ = "dat", need = 0, keyword = "country", prop = "P27", },
	mode		= {typ = "sys", need = 0, keyword = "mode"},
}

Available parameters to define an argument:

  • typ: type of the argument.
  • typ = "dat" ; type of the argument in: dat for data values.
  • typ = "sys" ; type of the argument in: dat for data values.
  • typ = "autority" ; type of the argument in: dat for data values.
  • need: type of the argument in: dat for data values.
  • need = 0 ; type of the argument in: dat for data values.
  • need = 1 ; type of the argument in: dat for data values.
  • need = 2 ; type of the argument in: dat for data values.
  • keyword: type of the argument in: dat for data values.
  • keyword = 1 ; type of the argument in: dat for data values.
  • prop: defines the property to import from Wikidata like P569 for birthyear.
  • format: selects the sought format for the prop parameter.
  • syn: the argument is it a synonym?
  • syn = 0 ; this value is the default and means: the argument is not a synonym.
  • syn = 1 ; this value means: the argument is a synonym.
  • syn = 1 ; this option can be used several times.
  • syn = 2 ; this value is the same as syn = 1. It permit to remember that an argument have several synonyms.
	lastname = { typ = dat , keyword = lastname , syn = 1 , need = 0 }
	itemid = { typ = dat , keyword = itemid , syn = 1 , need = 2 , prop = itemid }
	sortkey_txt =	{keyword = "sortkey_txt", typ = "sys", need = 0, },

	rights =		{keyword = "rights", typ = "dat", need = 2,
		arg_values = "rights_values", key_values = "no,none,ONU,none,cn,50,us,70,mpf", -- wiki_selectors
		delay_values = "0,0,0,0,50,50,70,70,95", arg_uses = "none,none,none,none,cn,cn,us,us,mpf" }, -- wiki_selectors

	IA =			{typ = "not", need = 0,
		keyword = "IA", base_base = "IA", base_id = "IA", not_type = "Author",
		base_test = "1234",
		base_name = "Internet Archive",
		not_link = "http://www.archive.org/REF_1", },

	ARCHIVE =		{typ = "not", need = 0, deprecated = 1, --	deprecated database
		keyword = "ARCHIVE", base_base = "ARC", base_id = "ARCHIVE", not_type = "Author",
		base_test = "1234",
		base_name = "National Archives and Records Administration",
		not_link = "http://www.archive.org/details/REF_1", },

options = { typ = config , keyword = options , need = 0 }
  • config: defines the property to import from Wikidata like P569 for birthyear.

soughtversions = { typ = config , keyword = soughtversions , need = 0 }
example of use: soughtversions = { typ = config , keyword = soughtversions , need = 0 }

  • format: selects the sought format for the prop parameter.
  • opt: defines the property to import from Wikidata like P569 for birthyear.
  • format: selects the sought format for the prop parameter.


example of use: debug = { typ = opt , keyword = debug , need = 0 }

Central.doc

Formats the result of the doc mode.
Extract from the code of Module:Central:

function Central.doc(frame) -- Forms a dropbox for technical documentations about the module.
	Central.init(frame, p.Module_Central_version, "doc", p.args_known, p.options_for_modes, "Q535") -- QITEM
	modes.args_final = p.interact_args_final(modes.args_import) -- Interactions between argumensts
	local dockey = modes.args_final.dockey or modes.args_final[1]
	if dockey then
		local selector = mw.text.trim(dockey)
		res = res .. viewers.docGroup(selector, QITEM)
	end
	return res
end

Central.edit

Begins to format the result of the edit mode.
Typical code from Module:Central:

function p.edit(frame) -- Normal use for simple readers of pages
	local res = ""
	Central.init(frame, p.args_known, "edit", p.options_for_modes) -- Default init from the versions library.
	res = res .. p.form_result() -- Formats the resulting wikitext
end

p.interact_args_final

This function is the last step in the arguments values acquisition.
It tries to find values for all missing needed arguments.
Some extracts from the initial Module:Central:

	-- if absent, synonym of basic arguments, syn = 2
	if not a.firstname then i.firstname = (i.firstname2 or a.firstname2) end
	if not a.initial then -- If initial is undefined, enforce it.
		if a.lastname then
			i.initial = string.sub( a.lastname, 1, 1 ) -- selects the first letter
			i.initial = string.upper( i.initial or "*" ) -- in upercase
		end
	end

Central.read

Formats the result for the read mode.
Typical code from Module:Central:

function Central.read(frame) -- Normal use for simple readers of pages
	local res = ""
	Central.init(frame, p.args_known, "read", p.options_for_modes) -- Default init from the versions library.
	res = res .. p.form_result() -- Formats the resulting wikitext
end

Central.tests

Begins to format the result of the tests mode.
Typical code from Module:Central:

function Central.tests(frame) -- To support the user to modify arguments in case of errors. To light support of helpers in their own laguages.
	Central.init(frame, p.args_known, "tests", p.options_for_modes) -- Default init from the versions library.
	-- With a dropbox for helpers, displaying availables languages, versions used, number of admins in a wiki...
	res = res .. viewers.formDocBox() -- A box to help users when they tests/change the use of a template or a module.
	res = res .. p.form_result() -- Formats the resulting wikitext
end

Minimal centalisable module

A module without interface can format translated errors or categories in any function.
It can also use translated arguments and/or format reports.
For most details see Arguments: their process and translations.

Any module using central library can contain, or none, internal translations in english and some other languages.

p.i18n.en = { -- Define translations of arguments names, categories names, and errors messages to produce.
	birthyear = "birthyear", -- for an argument name
	centre_luatable_counts = "%1 variables, %2 functions, %3 subtables", -- for a report about available translations
} -- p.i18n.en

p.args_known = { -- Define all known arguments at the main module level.
	birthyear = {typ = "dat", need = 0, keyword = "birthyear", prop = "P569", format = "year"},
} -- p.args_known

p.options_for_modes = { -- default options. Very simple modules do not need this part of the interface.
	read	= " noerr ",
}

function p.read(frame) -- Formats the text to read for users. Very simple modules do not need this interface function.
	local res = ""
	Central.init(frame, p.args_known, "read", p.options_for_modes) -- Default init from the versions library.
	res = res .. "Hello world !" -- Formats the resulting wikitext
	return res
end -- function p.read(frame)

Central.init

The Central.init really installs the Library:versions.

The Central.init function is roughly equivalent to:

function Central.init(frame, Central_version, mode_name, args_known, options_for_modes)
	function versions.init(frame, Central_version, mode_name, args_known, options_for_modes, QITEM)
		versions.bind_the_main_module() -- Bind the main module, all sub-modules and all their i18n translations.
		versions.setup_central_libraries(versions.bindable_libraries) -- Actual installation of central bindable libraries in package.loaded.
		versions.bind_all_sub_modules() -- Bind all sub-modules of the main module.
		versions.bind_reverse_i18n_translations(main_versions, loaded_pack) -- Bind all i18n translations from modules and their /I18N translations sub-modules.
		versions.detect_mediawiki_changes() -- Detects to display versions of MediaWiki for 3 months.
	end
	modes.init_modes_translate_events(frame, Central_version, mode_name, modes.args_known, options_for_modes, QITEM or itemid)
	datas.get_item(args_known, QITEM) -- Get datas from mw.Wikibase for the page.
	modes.init_args_mode_options(mix, mode_name, modes.args_template) -- Import and mix args mode and options from template and invoke
	modes.import_arguments(args_known, args_source, content_translations, args_wikidata)
	p.interact_args_final(modes.args_import)
	modes.get_args(args_known)
	langs.init_content_page_user_lang()
end

Central libraries descriptions

Descriptions of the Central libraries:

  • The Library:activity supports the support of Lua coders sub-tasks and inter-wikis central modules.", },
  • The Library:datas gets datas from the Wikibase.
  • The Library:events formats events like erros, warnings and categories.
  • The Library:langs supports i18n translations.
  • The Library:lua_table enhances previous table library, to avoid ambiguities. To enhance, we could write here : lua_table = table.
  • The Library:mathroman convert roman numbers and detect errors. It is here as an example of very small central library.
  • The Library:modes support modes and their options, like p.read(frame).
  • The Library:tests_groups, initialises, runs and formats groups of tests for Mediawiki and users.
  • The Library:viewers formats tableviews as objects inside the Library:viewers
  • The Library:versions installs all central libraries, modules and their i18n translations. It also support versions support.

Objects have a function object.new() to format several objects:

  • The Object:boxview, in the Library:viewers, formats boxes, their styles and structures.
  • The Object:dropbox, in the Library:viewers, formats dropboxes and their styles.
  • The Object:central_library, in the Library:versions, formats the basis of libraries and their properties.
  • The Object:tableview, in the Library:viewers, formats some viewers for tables, in lines and columns.
  • The Object:tracker, in the Library:activity, formats parametrables tracks to help to debug the code.

activity

The activity library help Lua-coders to cooperate in begin phase.

  • activity Import all Wikidatas from Wikibase.

activity.begin_central_modules_support

To support the first uses of Central modules:

  • Report the sub-tasks support from inside central modules.
  • For each, it reports: Projet, Language, Admins count, Actives count, Used from, by which Lua-coder.
  • For all, it counts: Projects, Versions, Languages and Lua-coders.


activity.central_libraries_report

Lists actual functions for documentations:

  • To help to format this Central modules reference manual.
  • Also to know in live actual availabe functions.
  • It sorts and lists them, in bold for functions to document, from a dedicated list.
  • It also counts all and to document functions.


The dedicated dedicated list lookalikes:

activity.functions_to_doc = "viewers.form9user;viewers.styles_color_usual;viewers.form_image;viewers.docInternal;viewers.rough_view_test;"

activity.central_subtasks_report

Reports the current state of sub-tasks, inside a Phabricatoc task and defined by Lua-coders.
"todo" tasks are automatic shift in time, after the last "NOW" sub-task.
Each sub-tasks description contains:

  • bug.start is the begin date.
  • bug.end is the end date.
  • bug.plan is "todo" when the sub-task is to do.
  • bug.plan is "NOW" when the sub-task is change by a Lua-coder.
  • bug.plan is "done" when the sub-task is closed.
  • bug.user is the Lua-coder driving the sub-task.
  • bug.subid is the unique identifier of the sub-task.
  • bug.description describes it.
  • bug.duration is the diffrence between bug.end and bug.start.
activity.report_subtasks_list = { -- Examples of descriptors:
	-- Automatic shift of below "todo" subtasks.
	{ "20180425", "20180427", "todo", "Rical", "S171210arg", "Check all arguments: known_args/unknow_args missing/levenstein description", },
	{ "20180423", "20180424", "todo", "Rical", "S180128lit", "Show details link to internal error cat ending _i_cat, _u_cat in events.add_record()", },
	-- NOW, in change.
	{ "20180421", "20180422", "NOW", "Rical", "S180421upa", "For 'Begin' Update all phabtask in activity.phabricator_tasks_report()", },
	{ "20180417", "20180420", "NOW", "Rical", "S170705ust", "For 'Begin' Update all important tasks to support central modules", },
	-- Already done.
	{ "20180329", "20180407", "done", "Rical", "S180329uma", "For 'Begin' Update ModuleAuthor3.lua.", },
	{ "20180322", "20180323", "done", "Rical", "S180322crm", "For 'Begin' Update Stability in Central modules reference manual", },
}

activity.MW_Versions_report

Reports the Mediawiki versions for the last 3 months.
It helps Lua-coders to better report detected bugs and t o link them to the adequate Mediawiki version.
Each Mediawiki version description contains:

  • version.site like "www.mediawiki" or "fr.wikisource".
  • version.verstime is the UTC time-stamp of the version itself, like "2018-03-27T21:01:26".
  • version.versid is the referral version number, like "1.31.0-wmf.27 (06af291)".
  • version.seen_time is the UTC time when the Lua-coder has seen the new version in the site, like "2018-03-28T21:01:00".

Examples of descriptors:

versions.Mediawiki_Versions = { -- Examples of descriptors:
	{ site = "www.mediawiki", verstime = "2018-03-27T21:01:26", versid = "1.31.0-wmf.27 (06af291)", seen_time = "2018-03-28T21:01:00", },
	{ site = "fr.wikisource", verstime = "2018-03-27T21:01:26", versid = "1.31.0-wmf.27 (06af291)", seen_time = "2018-04-02T21:10:00", },
}

activity.phabricator_tasks_report

Reports the Phabricator tasks linked with central modules.
It helps Lua-coders to interact with Mediawiki developers.
Each Phabricator task description contains:

  • task.sort only to manual sort.
  • task.importance group. Values: Important, Central, Other, Obsolete.
  • task.date when the Lua-coder reports in the table the state of the task from the referral Phabricator.
  • task.task is the unique key to refer to one Phabricator task.
  • task.state is the step in the development process or rejection. Values: ToCreate, Open, Stalled, Assigned, Resolved, Declined, Invalid, Gerrit.
  • task.title synthetise the description of the task.
activity.phabricator_tasks_Group = { -- Examples of descriptors:
--	Importance: Important
	{ 114, "Important", "20180326", "T135845", 0, "Assigned", "Convert any module as central or centralisable", "Convert as central", },
	{ 126, "Important", "20170522", "T68051", 1, "Open", "Central modules need the user language to display errors and category names", "user language for errors", },
--	Importance: Central
	{ 192, "Central", "20180408", "T20180410", 0, "ToCreate", "Begin to use central modules in 7 wikis S180408btu", "Begin use central", },
	{ 204, "Central", "20180321", "T52329", 0, "Stalled", "We need a common repository for Scribunto modules and templates", "common repository", },
--	Importance: Other
	{ 302, "Other", "20170526", "T104109", 0, "Close", "No syntax highlight for large JavaScript/CSS/Lua/API pages", "loadTemplateData", },
	{ 320, "Other", "20170213", "T20170213", 0, "ToCreate", "Some languages have not French names in French language", "languages in stranger names", },
--	Importance: Obsolete: Already closed or Do not create.
	{ 442, "Obsolete", "20160813", "T75460", 0, "Resolved", "[Story] Make Lua functions default to the user's language on multilingual wikis", "multilingual wikis", },
}

central_library

  • The Object:central_library, in the Library:versions, installs one library.

central_library.binded_in

Detect if the object is binded in _G space or in package.loaded.

central_library.new

Install a library in package.loaded. The new library must be a table.
Each library must be install only once to not disturb subsequent processes.

  • name is the referral name of the library in package.loaded.
  • library is the table containing the library.
  • options could optimize the installation of the library.


options could be the installation of the library.
Some extracts of the code:

function central_library.new(name, library, options)
	if (type(options.library) == "table") then
		options.library.libname = options.name
	end
	function object.setupInterface(options) -- key instruction to install
		...
	end
	object = object.setupInterface(options)
	options.binded_in = central_library.binded_in(object, options.name)
	return package.loaded[options.name], options.err
end
}

datas

The Library:datas gets datas from the mw.Wikibase.

datas.get_image

Gets the sought image for one page.

  • The argument prop is the code for an image, "P18" as default.
  • The argument QITEM asks an image from another item.
  • The result is the name of the image.


Some extracts of the code:

function datas.get_image(prop, QITEM)
	if (prop == "image") then prop = "P18" end
	...
	return image_name
end

datas.get_item

Gets datas from mw.Wikibase for one page from one item, in a simple way for developers.
It bases mainly its datas upon the argument prop of p.args_known = {...}.
It gets properties on the function datas.property(pp) which gets datas from the Wikibase available properties for the page.
It returns and memorizes:

  • All collected datas from all properties in datas.props.
  • All collected values for properties in prop.


Some extracts of the code:
Usually the QITEM argument is not necessary.

function datas.get_item(args_known, QITEM)
	datas.QITEM = QITEM or mw.Wikibase.getEntityIdForCurrentPage()
	datas.item = mw.Wikibase.getEntity(datas.QITEM)
	for key, pp in pairs(args_known) do -- For all known parameters
		pp = datas.property(pp) -- Get datas from the mw.Wikibase for one property of the page.
		if pp.prop then -- If a known argument ask a data value.
			props[pp.keyword] = mw.clone(pp)
			prop[pp.keyword] = pp.val -- get the data value for the known argument.
		end
	end
	datas.prop = prop
	datas.props = props
	return prop, props
end
local prop, props = datas.get_item(p.args_known, QITEM)
}

datas.get_item_report

Reports the mw.Wikibase available properties for one page.
Some extracts of the result:

function datas.get_item_report(t)
	for key, val in pairs(props) do
		t = t .. "\n* get_item: " .. key .. "=" .. val
	end
	return t
end

datas.property

function datas.property(prop) -- Get datas from mwwikibase for one property of the page.
Gets datas from the mw.Wikibase for one property of the page.
It is called once for each sought property.

  • The argument QITEM asks an image from another eventual item.
  • The result is the name of the image.


Some extracts of the code:

function datas.property(pp) -- Get datas from mwwikibase for one property of the page.
	if pp.prop == "QITEM"		then val = mw.Wikibase.getEntityIdForCurrentPage()
	if pp.prop == "label"		then val = datas.item:getLabel(QITEM) -- default label
	if pp.prop == "description"	then val = mw.Wikibase.description(QITEM)
	if pp.prop == "labeluser"	then val = mw.Wikibase.getLabelByLang(QITEM, langs.user_lang or "es") -- user_lang label
	if pp.prop == "labelbylang"	then val = mw.Wikibase.getLabelByLang(QITEM, langs.user_lang or "it") -- user_lang label
	else
		val = formatPropertyValues.value
	end
	return val
end

Dropbox

The Object:Dropbox, in the Library:viewers, formats Dropboxes and their styles.

Dropbox.new

Returns a new Dropbox for documentation.
It follows these guidelines from these arguments:

  • selector: Mainly checks to format a new dropbox, or not.
  • content: As a string, it is the content of the dropbox. As a function, the content from it.
  • options: permit to customise the result.

Typical use:

	res = res .. Dropbox.new(selector, "modes_get_args_report_title", modes.get_args_report)

events

The Library:events formats events like errors, warnings and categories.
Categories are bilingual. They categorize in the content language and they display in the user language.

events.add_cat

Adds a category in the actual table of events.

  • The argument key is a i18n key to translate in an available language.
  • The arguments v1 to v9 replace %1 to %9 in the translation.


This event is not added if the key and the arguments v1 to v9 are already present in the table of events.
Some extracts of the code:

function events.add_cat(ref, v1, v2, v3, v4, v5, v6, v7, v8, v9)
	return events.add_record("cat", key, ...)
end

events.add_cat_group

Adds some categories in the actual table of events.

  • The argument groupCat is a i18n key to translate in an available language, or a simple string.
  • The arguments groupList is separated by some semicolumns ";" to format some categories based upon groupCat.


These events are not added if the key and the arguments from groupList are already present in the table of events.
Some extracts of the code:

function events.add_cat_group(groupCat, groupList)
	for i, str in mw.text.gsplit(groupList, ";", true) do ...
end

events.add_err

Adds an error in the actual table of events.

  • The argument key is a i18n key to translate in an available language.
  • The arguments v1 to v9 replace %1 to %9 in the translation.


This event is not added if the key and the arguments v1 to v9 are already present in the table of events.
Some extracts of the code:

function events.add_err(ref, v1, v2, v3, v4, v5, v6, v7, v8, v9)
	return events.add_record("err", key, ...)
end

events.add_wng

Adds a warning in the actual table of events.

  • The argument key is a i18n key to translate in an available language.
  • The arguments v1 to v9 replace %1 to %9 in the translation.


This event is not added if the key and the arguments v1 to v9 are already present in the table of events.
Some extracts of the code:

function events.add_wng(ref, v1, v2, v3, v4, v5, v6, v7, v8, v9)
	return events.add_record("wng", key, ...)
end

events.all_kinds_test

Tests all kinds of events (err, wng, cat).

events.categories_lister

Categorizes or display categories, already grouped in events.list_all_events.

  • The argument c permit to choose to categorize or to display. The default is to categorize.

events.gener_categories

Only display categories, as a text line, using categories_lister.

events.errors_lister

Returns the list of errors messages, if any, in the user language.

langs

The Library:langs supports i18n translations.

langs.abnormal_char_in_text

TO DO LATER

langs.dummy_languages

Report the characteristics of some languages

  • isTag: Returns true if a language code is known to MediaWiki.
  • isLang: Returns true if the language is localisable in MediaWiki.
  • isBuilt: Returns true if the language is customisable in MediaWiki.
  • langname: is the English name of the language.
  • native: is the native name of the language.

langs.init_content_page_user_lang

Initialise or update the 3 usual languages: langs.content_lang, langs.page_lang, langs.user_lang.

langs.list_Mediawiki_languages

Reports the list of available languages from mw.language.fetchLanguageName(lang).
For each languages it displays the code, the native name and the english name.
It is used in versions.main_i18n_languages_list and in langs.dummy_languages.

langs.main_i18n_languages_list

Formats a text which list for all available languages in the main module, to include in documentations.

  • For all available languages it reports: the mean number of translations for one language, and the number of languages.
  • For each language, it reports: the available number of translations, the native name of the language, its international code and its English name.
	t = t .. "\n*" .. langs.main_i18n_languages_list() -- List available translations languages

langs.missing_translations

Reports some first misses in translations for one language compared to another.
These changes indicate in which languages update the translations, even many more if necessary.

langs.translations_counts

Formats a table reporting for some or all languages the number of available translations.
That permit to fastly estimate the advancement of translations for them.
In future versions, this function could reports the most and the least translated languages, to fastly alert translators.

lua_table

The Library:lua_table enhances previous table library, to avoid ambiguities. To enhance, we could write: lua_table = table.

lua_table.count_all

Counts all objects, of all types, in a table, including all levels in the table. Examples of uses:

	local max_tab = lua_table.count_all(tab)

lua_table.count_tests

Reports some examples of available types of counts.

  • Tested counts:
	{ "count_all", { "name", 111, "other", function() end, true, false, { 33 }, function() end }, },
	{ "count_types", { "name", 111, "other", function() end, true, false, { 33 }, function() end }, },
	{ "count_values", { "name", 111, "other", function() end, true, false, { 33 }, function() end }, },
	{ "count_all", { a = "abc", 11, z = "xyz", t = true, false, n = nil, min = 11, 33, nil, 33, max = 55, "abc", }, },
	{ "count_types", { a = "abc", 11, z = "xyz", t = true, false, n = nil, min = 11, 33, nil, 33, max = 55, "abc", }, },
	{ "count_values", { "abc", 11, "xyz", true, false, nil, 11, 33, nil, 33, 55, "abc", }, },
	{ "level_list", { "abc", 11, "xyz", true, false, nil, 11, 33, nil, 33, 55, "abc", }, "key", "3", },

lua_table.count_types

Counts in a table, for each type, the number of objects of the this type.

lua_table.count_values

Counts in a table, for each value, the number of objects of the this value.

lua_table.from_subnames_object

Counts in a table, for each value, the number of objects of the this value.

ftd = ftd .. "lua_table.from_subnames_object;lua_table.from_subnames_table;"


function lua_table.from_subnames_object(sub_names, base_table) -- Get the last sub-object from its sub-names, but not a table. local sub_obj = nil if (type(base_table) ~= "table")then base_table = package.loaded end local sub_names = mw.text.split(sub_names, '%.') -- table of words local sub_tab, sub_obj = base_table, nil for i, sub_name in ipairs(sub_names) do sub_obj = sub_tab[sub_name] if (type(sub_obj) == "table") -- the search continue in sub tables and cannot search a table then sub_tab = sub_obj else break end -- get the last object which is not a table end return sub_obj end

lua_table.from_subnames_table

Counts in a table, for each value, the number of objects of the this value.

function lua_table.from_subnames_table(sub_names, base_table) -- Get the last sub-table from its sub-names. -- S170625ste sub_tab is bad, but it run if (type(base_table) ~= "table")then base_table = package.loaded end local sub_names = mw.text.split(sub_names, '%.') -- table of words local sub_tab = base_table for i, sub_name in ipairs(sub_names) do if (type(sub_tab) == "table") and (type(sub_tab[sub_name]) == "table") then sub_tab = sub_tab[sub_name] else sub_tab = nil end end return sub_tab end

lua_table.level_count

Counts all types of objects in the table, only in the first level of the table.
It could be used in any subtable in a table.
It returns 0 if the sole argument tab is not a table. Example of call:

	local count_in_one_level = lua_table.level_count(tab)

lua_table.level_list

Lists all keys, or selected one's, in the first level of the table.
It could be used in any subtable in a table.

  • tab: is the part of a table to list.
  • typ: is the type selector of values to restrict the list.
  • select: selects the field as key if defined.
  • field: selects a value only if the field is defined, and if the value in the table is equal to the value of field.
  • typ, select, and field: restrict the list in conjonction.

The selection to list in this function is roughly equivalent to:

	if ((type(keyval) == typ) and (viewers.is_in(select, keyval)) and (field) and (keyval == field) then
		list = list .. ", the field " .. field .. " = " .. keyval
	end
	list = list .. "."

lua_table.named_sub_counts

This function, first, select a subtable from its sub-name.
Then it counts inside all objects of all types in all levels.
It can be used in any subtable in a table.
It returns 0 if the subtable do not exist.

  • subnames_in is the part of a table to list, selected by a string.
  • base_table is the table in which search the subtable. The default value is package.loaded.

This function, first, select a subtable from its sub-name.

lua_table.obj_from_subnames

Gets the last sub-object from its sub-names.
It returns nil if the sub-object do not exist.

  • subnames_in is the last sub-object to get, selected by a string.
  • base_table is the table in which search the subtable. The default value is package.loaded.

lua_table.sort_onkey

Sorts a table based upon any type of keys.
It converts the table in another sortable table. Then it sorts the sortable table on the base of the keys in the 2 records compared in the sortable table.

  • tab is the table to sort.
  • key: the keys in 2 records compared must be of the same type. Other comparisons are not in the resulting sortable table.

lua_table.sort_types

Sorts a table, with any types of fields, even of differents types as strings.
It converts the table in another sortable table. Then it sorts the sortable table on the base of the keys in the 2 records compared in the sortable table.

  • tab is the table to sort.
  • key: if the keys in 2 records are of the same type the comparison uses their values.
  • key: else the comparison uses the conversion of their values in strings .

Other comparisons are not in the resulting sortable table.

  • decrease: if decrease == ">" then the sort is in decreasing order, else increasing.

lua_table.structure

Reports the structure of a table.
Arguments of the function lua_table.structure(table, tablename, opt):

  • table is the table to report.
  • tablename is the name of this table.
  • opt are the options transmitted for subtables.


For each value inside the table, a string displays the branch of the subtable where is the value, its type and its value.
For each branch of the subtable, the function formats 3 lines for variables, functions and subtables.
Each line reports:

  • The number of variables, functions or subtables.
  • The structure of each line is the same for variables, functions or subtables.
  • For variables, the number of variables, the type of line: "vars".
  • Then for each variable: its type and its key = its value.
  • For subtables, the names of these subtables.


Example of results:

Table .lua_table.tablim, 5 vars: string - 1 = one , string - 2 = two , string - max1 = MAX1 , string - max2 = MAX2 , string - max3 = MAX3 ,
Table .lua_table.tablim, 0 functions:
Table .lua_table.tablim, 3 tables: life, comfort, house,

Can also limits the results in number of levels: level_maxi and in number of resulting lines: max_n.
Example of results:

Table .lua_table.tablim.life Limite de longueur max_n = 2
Table .lua_table.tablim.comfort.sub2, 1 tables: sub3, Limite de niveau recursiveLimit = 4

lua_table.tab_from_subnames

Gets the last subtable from its sub-names.
It returns the last subtable, else nil.
Arguments of the function lua_table.tab_from_subnames(sub_names, base_table):

  • sub_names is the last subtable to get, selected by a string.
  • base_table is the table in which search the subtable. The default value is package.loaded.

lua_table.toList

From any Lua table, this function returns a list of variables names with their values.
Argument:

  • tab is the table to list.

Example of results:

	{ [1] = 123, [2] = abc, ["key"] = txt, } -- this table
 	[1] = 123 , [2] = abc , -- results in this string

lua_table.toList_tests

Reports some tests to check the lua_table.toList function.
Example of results:

lua_table.toTable

From a table of words, this function formats a Lua table.
See: lua_table.toTable_test.

lua_table.toTable_test

Reports some tests to check the lua_table.toTable function.
Example of results:

mathroman

The Library:mathroman convert roman numbers and detect errors. It is here as an example of very small central library.

mathroman.int2roman

Converts an integer to a roman number, also if int is a string.
It returns the roman number first, then the eventual text of error(s).
Argument:

  • int is the integer to convert.

mathroman.int2roman_test

Reports some unitary tests of mathroman.int2roman function.
Example of results:

	{ ["int"] = 0,		["roman"] = 0,			["error"] = "The integer "0" is not a convertible in Roman number", }
	{ ["int"] = 12,		["roman"] = XII,		["error"] = "", }
	{ ["int"] = 17,		["roman"] = XVII,		["error"] = "", }
	{ ["int"] = 3.14,	["roman"] = 0,			["error"] = "The non-integer number 3.14 is not convertible to Roman number", }
	{ ["int"] = 4999,	["roman"] = MMMMCMXCIX, ["error"] = "", }
	{ ["int"] = 5000,	["roman"] = 0,			["error"] = "The integer "5000" is not a convertible in Roman number", }

mathroman.roman2int

Converts a roman number in a string to an integer.
It returns the integer first, then the eventual text of error(s).
Argument:

  • rm is the roman number to convert.

mathroman.roman2int_tests

Reports some unitary tests of mathroman.int2roman function.
Example of results:

	{ ["int"] = 0,		["roman"] = 0,			["error"] = "The integer "0" is not a convertible in Roman number", }
	{ ["int"] = 12,		["roman"] = XII,		["error"] = "", }
	{ ["int"] = 17,		["roman"] = XVII,		["error"] = "", }
	{ ["int"] = 3.14,	["roman"] = 0,			["error"] = "The non-integer number 3.14 is not convertible to Roman number", }
	{ ["int"] = 4999,	["roman"] = MMMMCMXCIX, ["error"] = "", }
	{ ["int"] = 5000,	["roman"] = 0,			["error"] = "The integer "5000" is not a convertible in Roman number", }

modes

The Library:modes support modes and their options, for p.read(frame) and others.

modes.all_categories_list

Reports available categories in the main module.
Their keys in i18n translations contain "_cat".

modes.all_errors_list

Reports available errors in the main module.
Their keys in i18n translations contain "err_".
Example of results:

modes.get_args

Updates arguments values in their default definitions.
It updates the value, in the field val, and the significant origins, in the field src.

  • Origins of arguments are in the increasig priority: known, import, datas, template, final.

Argument:

  • args_known is the default definitions table, to not disturb: p.args_known{ , , , }.

Key points in code:

	local args_known = args_known or modes.args_known or p.args_known or {}
	local arguments_known = mw.clone(args_known) -- Do not disturb original definitions

modes.get_args_report

Reports arguments definitions and values from modes.get_args. See the result:

modes.levenshtein

For arguments names, this function detects small writing errors to suggest replacement.
And even replace them.
It uses the Levenshtein distance.

modes.multiple_selection_tests

Reports examples of multiple selections for some persons, objects or entities, using strings.
Arguments of the function modes.multiple_selection(opt, selector, to_select):

  • Selector asks some signs to get the sought selection.
  • To selector show how selectors signs are understood in the function.
  • Selected displays the resulting selections.

In Selector, options can mix some signs:

  • ; wich meens "keep all selections". ; is the separator of all selections.
  • ;U wich meens " distinguish the lowercases and uppercases".
  • ;= wich meens "recognize only equal string".
  • ;t wich meens "recognize after trim". That is to say delete, before and after all selections, any space, coma...

See the result:

modes.options_from_args_tests

Try some combinaisons of options and display the resulting combinaison.
That permits at Lua-coders to verify these results, and to alert if needed.
See the result:

modes.recursiveNormal

Normalizes a recursiveLevel and a recursiveLimit.
That interact with an internal modes.recursiveLimit which as an initial recursiveLimit.

  • The normalization maintains recursiveLevel from 1 to recursiveLimit.
  • If the recursiveLevel input is higher than recursiveLimit, this function formats an error.

Then the module can alert Lua-coders if needed.

modes.recursiveNormal_tests

Reports some tests cases of the function modes.recursiveNormal. See the result:

modes.similar_args_list

For an unknown argument, this function searches the closest name of the among translated known arguments.
Argument:

  • args_known is the default definitions table.

Results:

  • A list of translated known arguments in the decreasing Levenshtein distance from the given argument.

tableview

The Object:tableview, in the Library:viewers, formats a viewer for tables, in lines and columns.

tableview.form_one_case

Almost all uses of tableview need an adaptation of this function.
For typical use, see:tableview.new.
Typical call:

function tableview.form_one_case(case, tabView) -- Default: Convert a case from testGroup to rowGroup.

tableview.new

Formats a table view with lines and columns.
It easy replaces: table_head, table_row, table_col, table_dat and table_end.
Typical use:

	local tabView = {
		testGroup = modes.central_libraries, -- List of central libraries.
		title_memo = "activity_display_central_libraries_title",
		headers = "activity_monitor_central_libraries_headers",
		headers_class = "wikitable alternative center sortable",
		rowGroup = {},
		form_one_case = function(case) -- Convert a case from testGroup to rowGroup.
			return { case.key, case.val or "-", case.typ, case.need, case.keyword, case.syn, case.prop, case.format, case.src or "-", }
		end,
	--	track_on == "details",
	}
	t = t .. tableview.new(tabView) -- Formats a table view with lines and columns.

versions

The Library:versions installs all central libraries, the main and sub-modules and their i18n translations. It also support the versions support.

version descriptor

Each version of a central module is characterised by these values:

  • versionName: like Central for the main version or like Central-s-fr for a variant.
  • versionNumber: like 1.0.0(180506:07:55) following the UTC version structure : main.fonction.task(yymmdd:hh:mm).
  • versionDate: like 2018-05-06T07:55:00 following the UTC rules.
  • mainDescription: like Begin to use following the main task goal.
  • functionDescription: like first functional support a step inside the main task goal.
  • taskDescription: like Update to 'Begin' at T20180510 approximately unambiguous detailed subtask.
  • sought is the sought module and submodules versions.
  • known are known module and submodules versions.
  • sought and known are inputs for versions.bind_the_main_module and versions.bind_all_sub_modules.

Typical header code:

local Central = {} -- The main central module install central libraries and bind the main and sub modules
local p = Central
p.version = { -- Modules dependencies. Dependencias del módulo. Dépendances du module.
	versionName = "Central-s-fr", versionNumber = "1.0.0(180506:07:55)", versionDate = "2018-05-06T07:55:00",
	-- UTC version structure :		  main.fonction.task(yymmdd:hh:mm)
	mainDescription = "Begin to use", functionDescription = "first functional support", taskDescription = "Update to 'Begin' at T20180510 approximately",
	sought = "Central-s-fr;Central;Mathroman22;TestRequire", -- Sought module and submodules versions
	known = "Central-s-fr;Central;Central-14 * Mathroman22;Mathroman34", -- Known module and submodules versions
}

versions.all_G_and_loaded_list

Lists variables in the _G global space or in package.loaded.
It permits to check if some variable is in the global space _G from a coding error.
Colors used distinguish the kinds of values: central library in bold blue, library in blue, function in red, track in grey or others in black.

versions.get_one_module_or_library

Can require or install a module or a library in package.loaded.
Then it formats and records its descriptor.

There are 2 uses, with changes of types of arguments:

	local get = versions.central_library(given_module, title)
	local get, module = versions.get_one_module_or_library("Module:Central")

Structure of the descriptor:

	get.title = title -- The name of the object, like "Module:Example" for a module.
	get.module = module -- The module or the library itself (compiled).
	get.isNil = not get.module
	get.isLoaded = true if the object is in package.loaded[title].
	get.isFunction = true if the object is a function.
	get.isTable = true if the object is a table.
	get.isModule = true if get.title looklikes to "Module:Example"
	get.isLibrary = true if get.title looklikes to "example"
	get.i18n = true if the object contains i18n translations, like "module.i18n"
	get.hasi18n = true if get.i18n translations are available.
	get.subI18N = get.title .. "/I18N" -- eventual sub-module "/I18N"
	get.isI18N = true if title include "/I18N"
	get.versionI18N = looklikes to "Module:Example/I18N"
	get.lessI18N = title do not looklikes to "Module:Example/I18N"
	get.simplename = title without "Module:" and without "/I18N"
	get.revistamp = looklikes to "20180512150600" -- The compact format of the last update date-time of the module. Example: 12 May 2018 at 15:06:00.
	get.versions = module.versions -- descriptor for the versions support {sought, known...}
	get.versionName = get.title without "Module:", but perhaps with "/I18N" ,,

Examples of use, see versions:

	local get = versions.central_library(given_module, title)
	local get, module = versions.get_one_module_or_library("Module:Central") -- The types of arguments differ to require a module or a library.

versions.setup_central_libraries

Binds libraries in package.loaded.
It is used in Central.init.

viewers

The Library:viewers can formats texts to document in some languages: tableview(in lines and columns), Dropboxes, recursive Lua tables...

viewers.day_to_stamp

Converts a date in a time stamp, limited to the date.
Examples of code for a similar result:

	return "@" .. tostring( jj*86400 + mm*30*86400 + (aaaa-1970)*31556926 )
	return viewers.day_to_stamp(jj, mm, aaaa)

viewers.day_to_UTC

Converts a date in UTC format, limited to the date.
Examples of code for a similar result:

	return aaaa .. "-" .. mm .. "-" .. jj
	return viewers.day_to_UTC(jj, mm, aaaa)

viewers.discreet_main_version

Returns the main version in light grey for attentive readers only.

viewers.docGroup

Displays all Dropbox.new.

viewers.docInternal

Displays only internal tests or reports Dropbox.new.

viewers.docModule

Displays only reports Dropbox.new dedicated to the module.

viewers.docPage

Displays only reports Dropbox.new dedicated to the page.

viewers.doc_section

Formats the title of a group of Dropbox.new, typicaly for each library.
Example of use:

	res = res .. viewers.doc_section(selector, "Library:lua_table", "h3")

viewers.form99content

Similar to viewers.form9user for 99 values in content language.

viewers.form99page

Similar to viewers.form9user for 99 values in page language.

viewers.form99user

Similar to viewers.form9user for 99 values in user language.

viewers.form9content

Similar to viewers.form9user for 9 values in content language.

viewers.form9en

Similar to viewers.form9user for 9 values in user language.
But in English only for tests.

viewers.form9page

Similar to viewers.form9user for 9 values in page language.

viewers.form9user

Formats a parametrable text and is the most used in all central libraries.
If the text is a key in i18n tables, it replaces the key by its translation in the user language.
Then it replaces "%1" to "%9" in the text by v1 to v9 arguments.
Example of use:

	viewers.form9user(ref, v1, v2, v3, v4, v5, v6, v7, v8, v9) -- reference call
	viewers.form9user("Module with internal error") -- example with simple text
	viewers.form9user("luaTable_structure_level_maxi", recursiveLevel) -- example with key.
	viewers.form9user(" %1 variables, %2 functions, %3 subtables.\n", vr, fn, tb) -- example with text and values.

Result in a parametrable string based on ref.

  • If ref is a key of translatable string in a i18n table, it is first translated.
  • If ref is not a translatable key, this function uses it as translated.
  • If the translated string contains %1 to %9 this function replaces them by v1 to v9 respectively.
  • If ref is any other string, the function returns it as is.

This is roughly equivalent to:

function viewers.form9user(ref, v1, v2, v3, v4, v5, v6, v7, v8, v9)
	if translations[ref] then wt = tostring(translations[ref])
	elseif ref then wt = tostring(ref)
	else wt = tostring("noref") end
	v1 = v1 or " 1"
	...
	v9 = v9 or " 9"
	if v1 then wt = string.gsub(wt, "%%1", tostring(v1) ) end
	...
	if v9 then wt = string.gsub(wt, "%%9", tostring(v9) ) end
	return tostring(wt)
end

viewers.form9user_test

Reports some unitary tests of the viewers.form9user function.
Do not translate the i18n translation key and separate the arguments with semicolons.
Example of results:

	"langs_form99user_all_types_values;abc;4;nil;function;55;xyz",
	"replace: abc%1efg%2ijk;<b>D</b>;<b>H</b>",

viewers.main_view

Formats all results of the main module, following main options.
In each mode, options ask to adapt the result to display.


Do not translate the i18n translation key and separate the arguments with semicolons.

function viewers.main_view(args_final, main_module) -- Formats all results of this module, and of others.
	local res = ""
	local memo = viewers.init_configs("viewers.main_view p.box1") -- Initialize global configurations and save them before eventual changes.
	main_module = main_module or versions.main_module
	if type(args_final) ~= "table" then args_final = modes.args_final end -- optional arguments
..	res = res .. viewers.ta("modes.mode_name", modes.mode_name) .. viewers.ta("modes.options", modes.options)
	events.gener_categories(args_final) -- Formats all categories without activate them
--	local label = modes.args_final.label or modes.main_title or datas.allprops.Label or modes.args_final.itemid
	local label = modes.args_final.label or modes.main_title or datas.prot("title") or modes.args_final.itemid
--	local label = modes.args_final.label or modes.main_title or modes.args_final.QITEM or modes.args_final.itemid
	if modes.option("docview") or modes.option(":") or modes.option("tests") or (modes.args_final.mode == "edit") then
--		res = res .. Dropbox.new("allwaysview", "versions_support_desk_title", versions.form_support_desk_report )
		res = res .. p.formDocBox(modes.args_final)
	end
	if modes.option("box1") then res = res .. p.box1(props) end -- ric (p.box1)
	viewers.restore_configs(memo, "viewers.main_view p.box1") -- Restore global configurations after eventual changes.
	local memo = viewers.init_configs("viewers.main_view Tests") -- Initialize global configurations and save them before eventual changes.
	if modes.option("box1") or modes.option("catview")
	then res = res .. " catview = " .. events.categories_lister(":") end -- Display categories
	events.categories_lister("") -- really link to categories
	modes.time3 = os.clock()
	if modes.option("tests") then --   or (modes.args_final.mode == "tests")
		Central.tst = false -- To format documentations of only some tests and reports.
		Central.tst = "tst" -- To format all tests and reports.
		res = res .. viewers.docGroup("allwaysview") -- viewers.docGroup(selector, mask_sections) -- To enforce title of sections
--		res = res .. viewers.docPage("allwaysview")
--		res = res .. viewers.docModule("allwaysview")
--		res = res .. viewers.docInternal("allwaysview")
		res = res .. versions.running_times(false, "")
	end
	viewers.restore_configs(memo, "viewers.main_view Tests") -- Restore global configurations after eventual changes.
	return res
end -- res = res .. viewers.main_view(args_final, main_module) -- Formats all the result of this module


viewers.formatDate

viewers.form_image

Formats an image from its file name, to the size in pixels.

Options are added as string This is roughly equivalent to:

function viewers.form_image(file, size, options) -- Formats an image from its file name, to the size in pixels
	return '[[File:' .. file .. '|' .. size .. 'px|' .. options .. ']]' -- options must begin with "|"
end

viewers.is_in

Returns true if the word is in the text, even inside another word. Else return false.

	function viewers.is_in(word, text) -- return true if the word is in the text. Else return false.

This is roughly equivalent to:

function viewers.is_in(word, text)
	return string.find(text, word)
end

viewers.is_in_sp

Returns true if the word is in the text, beetwen spaces or separators, not inside another word. Else return false.

Is in centre which use it to find versions in list.

This is roughly equivalent to:

function viewers.is_in_sp(word, text, sep)
	sep = sep or " "
	return string.find(sep .. text .. sep, sep .. word .. sep)
end

viewers.parts_of_date_tests

viewers.restore_configs

Restores global configurations, after eventual changes, saved by viewers.save_configs.
If needed, it creates an error which is roughly equivalent to:

	events.add_err("events_close_without_memo_err", versions.main_versions.versionName) -- Add an error in the actual table of events.

viewers.rough_view

Formats a string to describe a value like: true, 123.456, "abcd", func() or table{}.
The string is a rough view of the value, for any of it's type.

viewers.rough_view_test

viewers.save_configs

Saves global configurations, before eventual changes, restored by viewers.restore_configs.

function viewers.save_configs(where) -- Save global configuration before eventual changes.
	local memo = viewers.save_configs() -- Save global configuration before eventual changes.<!--Doc 20171103 DocTodo DocOK -->
	-- Any code which could disturb global configurations
	viewers.restore_configs(memo) -- Restore global configurations after eventual changes.
end

Is roughly equivalent to:

function viewers.save_configs() -- Save global configurations before eventual changes.
	local memo = {}
	memo.memo_group = events.testGroup
	memo.memo_tabOptions = events.tabOptions
	memo.memo_wiki_lang = langs.wiki_lang
	memo.memo_user_lang = langs.user_lang
	memo.memo_categories_list = events.categories_list
	memo.memo_catView = modes.catView
	memo.memo_recursiveLimit = modes.recursiveLimit
	memo.memo_mode_name = modes.mode_name
	memo.memo_mode_options = modes.mode_options
	memo.memo_invoke_options = modes.invoke_options
	memo.memo_options_for_modes = modes.options_for_modes
	memo.memo_report_trackOptions = modes.report_trackOptions
	return memo
end -- function viewers.save_configs()

viewers.save_restore_balance_report

Checks and reports known couples of save and restore global configurations, mainly to protect them against tests which can disturb anything.
It uses the results of viewers.save_configs and viewers.restore_configs.

This function must run after any other tests to be efficient.

Saved and restored options of configurations: base.events.tabView, base.events.catview, base.events.default_group, base.events.DropboxStyle, base.events.testGroup, base.events.headers, base.events.kind,base.events.tableViewStyle, base.events.testsFunction, base.events.typ, base.events.content_lang, base.events.page_lang, base.events.user_lang, base.events.recursiveLevel, base.events.recursiveLimit, base.events.tabView, base.events.tabView, base.events.tabView, base.events.tabView, events.testGroup.

viewers.simpleList

Splits a string in parts limited by 1 to 4 separators. It can also trim and sort these parts.
Arguments:

  • The list is the input string to split...
  • The 4 arguments sep1, sep2, sep2, sep2, have similar roles.
  • Their default role is to split list in parts.
  • The value "sort" asks to sort the resulting parts.
  • The value "trim" asks to delete, before and after each part, any space, coma...

viewers.simpleList_test

Uses the viewers.simpleList function in some cases and reports them. string in parts limited by 1 to 4 separators. It can also trim and sort these parts.
It uses the results of and viewers.restore_configs.
Arguments:

  • The list is the input string to split...
  • The 4 arguments sep1, sep2, sep2, sep2, have similar roles.

See the result:

viewers.styles_small_caps

Changes the style of a displaid text to the functional style "small caps".
Extract from the code:

	return '<span style="font-variant: small-caps">' .. t .. '</span>'

viewers.ta

Formats a variable and its value in a documentation.
Arguments:

  • txt finishes with the name of the variable, and can begin with any complement.
  • val is the value of the variable.
  • sep can replace the equal sign.

You can code for the same result:

	return viewers.ta("\n* pi", 3.14)
	return "* pi = <b>3.14</b>, "

viewers.tam

Uses viewers.ta.
If val is nil then viewers.tam return an empty string.

viewers.table_col

Begins a new column in a table. See also tableview.new.
A column become fix and not triable with the option: class="unsortable".

viewers.table_dat

Displays a string in a column of a table. function viewers.table_dat(t) return "\n| " .. tostring( t or " ") end -- Table data -- or " " Uses viewers.ta.
If val is nil then viewers.tam return en empty string.

viewers.table_end

Finishes a table of rows. function viewers.table_end(t) return "\n|}" end -- Table end Uses viewers.ta.
If val is nil then viewers.tam return en empty string.

viewers.table_head

Begins a row of headers in bold in a table, even between two rows of usual strings.
Is used viewers.ta.
A triable table start with the option: class="wikitable sortable"
Argument:

  • t defines the options values. The default is "wikitable alternative center".

Rough code:

	return '\n{| class="' .. tostring( t or 'wikitable alternative center' ) .. '" | '

viewers.table_row

Begins a row of usual strings.
A row become fix and not triable with the option: class="sortbottom".
See how to use options in viewers.table_end.

viewers.trans99vars

viewers.trans9vars

versions.report_bind_verif_modules_details

function viewers.styles_color_add(t) return viewers.usualColor(t, "add") end function viewers.styles_color_delete(t) return viewers.usualColor(t, "delete") end function viewers.styles_color_discreet(t) return viewers.usualColor(t, "discreet") end function viewers.styles_color_error(t) return viewers.usualColor(t, "error") end function viewers.styles_color_colargs(t) return viewers.usualColor(t, "colargs") end function viewers.styles_color_normal(t) return viewers.usualColor(t, "normal") end function viewers.styles_color_warning(t) return viewers.usualColor(t, "warning") end function viewers.styles_color_wikidata(t) return viewers.usualColor(t, "wikidata") end

viewers.styles_color_colargs

viewers.styles_color_delete

viewers.styles_color_discreet

viewers.styles_color_error

viewers.styles_color_normal

viewers.styles_color_usual

Changes the color of a text to display.
Example of use:

	local t = viewers.styles_color_usual(t, "normal")

Available colors are in viewers.styles_color_XXX.

viewers.styles_color_warning

viewers.wikidataColor

viewers.styles_color_wikidata

Record a library in package.loaded from a table object.

	versions.bind_one_library(name, library, options)

viewers.styles_color_XXX


Available colors for styles:

  • add for add in blue = "blue".
  • delete for delete in yellow = "#C0C000".
  • discreet for discreet in light grey = "#B0B0B0".
  • error for error in red = "red".
  • colargs for invoked args in brown = "#804020".
  • mask to mask in white = "white".
  • normal for other standard in black = "black".
  • warning for warnings in brown = "#804020".
  • wikidata. for wikidata in green = "green".

These corresponding functions change the colors of a displayed text for available functional styles:

  • viewers.styles_color_add(t)
  • viewers.styles_color_delete(t)
  • viewers.styles_color_discreet(t)
  • viewers.styles_color_error(t)
  • viewers.styles_color_colargs(t)
  • viewers.styles_color_colargs(t)
  • viewers.styles_color_normal(t)
  • viewers.styles_color_warning(t)
  • viewers.styles_color_wikidata(t)

versions.tasks_changes_report_normal

versions.tasks_changes_report_short

versions.versions_management_report