Editing Module:Sandbox/Nihiltres/Category manager/doc

{{Module rating |beta}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->

This module implements a simple tool for managing category output in modules.

==Usage==
The module cannot be used from wikitext. It can be imported to another module using code similar to the following:

<code>local catMan = require("Module:Category manager")</code>

===Category-list table format===
Each function in the module takes a table as its first parameter, and that table is used as the list of categories. These tables are assumed to only be manipulated by this module's functions, but there is no protection against external manipulation; there's just basic type/value validation. Each item in a category-list table has its category name (without prefix) as its key; duplicate categories are therefore impossible. Values for each key can either be <code>true</code> (no sort key) or a string containing that sort key. A <code>false</code> value or any other type of value will cause errors. There are three functions for manipulating a category list table, and their individual documentation follows.

==Functions==

===addCategory===
Usage:
* <code>catMan.addCategory(catList, name)</code>
* <code>catMan.addCategory(catList, name, sortKey)</code>

The <code>addCategory</code> function adds a category by setting the key from <code>name</code> in the <code>catList</code> table to either <code>true</code> or the provided <code>sortKey</code> value if present.

If an existing category is added a second time, its value will be overwritten with the new value; for this reason the module does not include a separate function for setting sort keys.

The <code>catList</code> parameter must be a table, the <code>name</code> parameter must be a non-empty, non-whitespace string, and <code>sortKey</code> must be either a string or nil.

===removeCategory===
Usage:
* <code>catMan.removeCategory(catList, name)</code>

The <code>removeCategory</code> function removes a category by setting the key from <code>name</code> to nil in the <code>catList</code> table.

The <code>catList</code> parameter must be a table, and the <code>name</code> parameter must be a non-empty, non-whitespace string.

===writeCategoryList===
Usage:
* <code>catMan.writeCategoryList(catList)</code>
* <code>catMan.writeCategoryList(catList, nullify)</code>

The <code>writeCategoryList</code> function produces a string containing all the categories in the table formatted as wikitext. Optionally, a boolean <code>nullify</code> parameter may be provided, and if true, it will cause the function to output an empty string. This is useful as it makes it easy to disable category output through a parameter, probably in conjunction with [[Module:Yesno]].

The <code>catList</code> parameter must be a table formatted according to the category-list table format, and the <code>nullify</code> parameter must be either a boolean or nil.

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox ||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Lua metamodules]]
}}</includeonly>