Editing Template:Data to Table/doc

{{Documentation/Header}}
{{Lua}}
Lua module to allow users to create "copy-pastable" data tables based on custom DPL queries, as well as JSON data from DPL queries.

==Syntax==
* {{F|info}} &mdash; The raw output of a DPL query (see usage examples).
* {{F|keys}} &mdash; A {{F|;;}}-separated list of keys to extract from the info. You can use nested levels with {{F|//}} and {{F|@@}}.
** Note that although the page itself must be included in your DPL include statement, it is used as the table's key by default, so there is no need to specify it.
* {{F|unquoted}} ''(optional)'' &mdash; A {{F|;;}}-separated list of keys whose values should be output as raw Lua values instead of strings.
* {{F|value}} ''(optional)'' &mdash; Sets the same value for every entry when no {{F|keys}} are specified.
* {{F|sortkey}} ''(optional)'' &mdash; Specifies which key to sort the data by, using the page name by default. Use {{F|INPUT}} to preserve the original order.
* {{F|subtable}} ''(optional)'' &mdash; Splits values into subtables.
* {{F|block}} ''(optional)'' &mdash; Display the results using block formatting.
* {{F|copy}} ''(optional)'' &mdash; Enter your header here. Adds a button to copy the generated Lua table to your clipboard at the top.
* {{F|cleanTT}} ''(optional)'' &mdash; Auto-parse out any {{T|tt}} format in the output.

===JSON Mode===
* {{F|json}} &mdash; Set to {{F|1}} to output JSON instead of a Lua table.
* {{F|group1}}, {{F|group2}}, etc. &mdash; The name of a JSON group.
* {{F|group1_info}}, {{F|group2_info}}, etc. &mdash; The DPL output used to populate the corresponding group.
** Groups may be numbered sequentially up to {{F|group10}}.
** Empty groups are automatically omitted from the generated JSON.
** JSON mode uses the built-in copy button provided by the syntax highlighting extension.

When {{F|json}} is set to {{F|1}}, the module supports both simple JSON arrays and grouped JSON objects.

==Examples==

===Lua Table===
A basic DPL query can be converted into a Lua data table:

<pre>
{{Data to Table
|keys=number;;quality;;galaxy
|unquoted=number
|info={{#DPL:
|namespace=
|category=Fish
|uses=Template:Creature Infobox
|include={Creature Infobox}:%PAGE%,{Creature Infobox}:number,{Creature Infobox}:quality,{Creature Infobox}:distribution
|format=,,,
|secseparators=page==,;;number==,,;;quality==,,;;galaxy==,,$$$
}}
}}
</pre>

This produces output in the following format:
{{sh|<nowiki>return {
	['Anchovy'] = {
		['number'] = 074,
		['quality'] = 'Gray',
		['galaxy'] = 'Taffeh',
	},
	['Barred Spinefoot'] = {
		['number'] = 085,
		['quality'] = 'Purple',
		['galaxy'] = 'All Regions',
	},
}</nowiki>|lua}}

===Constant Values===
{{F|value}} can be used when every entry should have the same value:

<pre>
{{Data to Table
|value=day
|info={{#DPL:
|namespace=File
|category=Icons to Invert
|format=,page==%PAGE%$$$,,
}}
}}
</pre>

This produces:
{{sh|<nowiki>return {
	['Crab Icon.png'] = 'day',
	['Crayfish Icon.png'] = 'day',
	['Fish Icon.png'] = 'day',
}</nowiki>|lua}}

If the value should be output as a raw Lua value rather than a string, include {{F|value}} in {{F|unquoted}}.

===Simple JSON Array===
JSON mode can also be used without groups:

<pre>
{{Data to Table
|json=1
|info={{#DPL:
|namespace=File
|category=Icons to Invert
|format=,page==%PAGE%$$$,,
}}
}}
</pre>

This produces:
{{sh|<nowiki>[
	"Crab Icon.png",
	"Crayfish Icon.png",
	"Fish Icon.png"
]</nowiki>|json}}

===Grouped JSON===
Multiple DPL queries can be combined into a single JSON object using groups:

<pre>
{{Data to Table
|json=1

|group1=day
|group1_info={{#DPL:
|namespace=File
|category=Icons to Invert
|format=,page==%PAGE%$$$,,
}}

|group2=night
|group2_info={{#DPL:
|namespace=File
|category=Icons to Invert Night
|format=,page==%PAGE%$$$,,
}}
}}
</pre>

This produces:

{{sh|<nowiki>{
	"day": [
		"Crab Icon.png",
		"Crayfish Icon.png",
		"Fish Icon.png"
	],
	"night": [
		"Special Icon.png"
	]
}</nowiki>|json}}

Groups with no results are automatically omitted. For example, if the night category is empty, the output will simply be:

{{sh|<nowiki>{
	"day": [
		"Crab Icon.png",
		"Crayfish Icon.png",
		"Fish Icon.png"
	]
}</nowiki>|json}}

===Multiple Groups===
Additional groups can be added by continuing the numbering:

<pre>
|group1=day
|group1_info=...

|group2=night
|group2_info=...

|group3=special
|group3_info=...
</pre>

Up to {{F|group10}} / {{F|group10_info}} are supported.

==DPL Formatting for JSON==
When using JSON mode, each DPL query should output an entry using the {{F|1=page==...$$$}} format.

For example:

<pre>
|format=,page==%PAGE%$$$,,
</pre>

The {{F|page}} value is used as the value in the JSON array.

For file categories, the resulting JSON can therefore contain the full filename, such as:

{{sh|<nowiki>"Crab Icon.png"</nowiki>|json}}

rather than only the page title or the filename without its extension.

==Notes==
* JSON output is sorted alphabetically by page name.
* Lua output is sorted according to {{F|sortkey}}, which defaults to the page name.
* JSON mode does not use {{M|CopyText}}; it uses the copy button provided by the syntax highlighting extension.
* Normal Lua output can still use {{F|copy}} to add the custom copy button.
* The module automatically omits empty JSON groups.
* The module is intended to be used with DPL output, rather than being tied to any particular data source.

==Template Data==
<templatedata>
{
	"params": {
		"info": {
			"label": "DPL output",
			"description": "The raw output of a DPL query.",
			"type": "string",
			"required": true
		},
		"keys": {
			"label": "Keys",
			"description": "A ;;-separated list of keys to extract from the DPL output. Nested levels can be created with // and @@.",
			"type": "string"
		},
		"unquoted": {
			"label": "Unquoted keys",
			"description": "A ;;-separated list of keys whose values should be output as raw Lua values instead of strings.",
			"type": "string"
		},
		"value": {
			"label": "Constant value",
			"description": "Sets the same value for every entry when no keys are specified.",
			"type": "string"
		},
		"sortkey": {
			"label": "Sort key",
			"description": "The key used to sort the Lua output. Defaults to the page name. Use INPUT to preserve the original order.",
			"type": "string"
		},
		"subtable": {
			"label": "Subtable separator",
			"description": "Splits values into subtables using the specified separator.",
			"type": "string"
		},
		"block": {
			"label": "Block formatting",
			"description": "Display the generated Lua table using block formatting.",
			"type": "boolean"
		},
		"copy": {
			"label": "Copy button",
			"description": "Adds a copy button to the generated Lua table using the supplied header text.",
			"type": "string"
		},
		"cleanTT": {
			"label": "Clean Template:Tt",
			"description": "Automatically parses Template:Tt formatting from the DPL output.",
			"type": "boolean"
		},
		"json": {
			"label": "JSON mode",
			"description": "Set to 1 to output JSON instead of a Lua table.",
			"type": "boolean"
		},
		"group1": {
			"label": "JSON group 1",
			"description": "The name of the first JSON group.",
			"type": "string"
		},
		"group1_info": {
			"label": "JSON group 1 data",
			"description": "The DPL output used to populate JSON group 1.",
			"type": "string"
		},
		"group2": {
			"label": "JSON group 2",
			"description": "The name of the second JSON group.",
			"type": "string"
		},
		"group2_info": {
			"label": "JSON group 2 data",
			"description": "The DPL output used to populate JSON group 2.",
			"type": "string"
		},
		"group3": {
			"label": "JSON group 3",
			"description": "The name of the third JSON group.",
			"type": "string"
		},
		"group3_info": {
			"label": "JSON group 3 data",
			"description": "The DPL output used to populate JSON group 3.",
			"type": "string"
		},
		"group4": {
			"label": "JSON group 4",
			"description": "The name of the fourth JSON group.",
			"type": "string"
		},
		"group4_info": {
			"label": "JSON group 4 data",
			"description": "The DPL output used to populate JSON group 4.",
			"type": "string"
		},
		"group5": {
			"label": "JSON group 5",
			"description": "The name of the fifth JSON group.",
			"type": "string"
		},
		"group5_info": {
			"label": "JSON group 5 data",
			"description": "The DPL output used to populate JSON group 5.",
			"type": "string"
		},
		"group6": {
			"label": "JSON group 6",
			"description": "The name of the sixth JSON group.",
			"type": "string"
		},
		"group6_info": {
			"label": "JSON group 6 data",
			"description": "The DPL output used to populate JSON group 6.",
			"type": "string"
		},
		"group7": {
			"label": "JSON group 7",
			"description": "The name of the seventh JSON group.",
			"type": "string"
		},
		"group7_info": {
			"label": "JSON group 7 data",
			"description": "The DPL output used to populate JSON group 7.",
			"type": "string"
		},
		"group8": {
			"label": "JSON group 8",
			"description": "The name of the eighth JSON group.",
			"type": "string"
		},
		"group8_info": {
			"label": "JSON group 8 data",
			"description": "The DPL output used to populate JSON group 8.",
			"type": "string"
		},
		"group9": {
			"label": "JSON group 9",
			"description": "The name of the ninth JSON group.",
			"type": "string"
		},
		"group9_info": {
			"label": "JSON group 9 data",
			"description": "The DPL output used to populate JSON group 9.",
			"type": "string"
		},
		"group10": {
			"label": "JSON group 10",
			"description": "The name of the tenth JSON group.",
			"type": "string"
		},
		"group10_info": {
			"label": "JSON group 10 data",
			"description": "The DPL output used to populate JSON group 10.",
			"type": "string"
		}
	},
	"description": "Converts custom DPL output into copy-pastable Lua tables or JSON data.",
	"format": "{{_\n|_ = _\n}}"
}
</templatedata>