Editing Module:Repr/doc (section)

=== repr ===

This function generates a string representation of any given Lua object. The idea is that if you copy the string this function produces it, and paste it back into a Lua program, then you should be able to reproduce the original object. This doesn't work for all values, but it should hold for simple cases.

For example, <syntaxhighlight lang="lua" inline>mRepr.repr({bool = true, number = 6, str = "hello world"})</syntaxhighlight> will output the string <code>{bool = true, number = 6, str = "hello world"}</code>.

Basic syntax:

<syntaxhighlight lang="lua">
mRepr.repr(value)
</syntaxhighlight>

Full syntax:

<syntaxhighlight lang="lua">
mRepr.repr(value, options)
</syntaxhighlight>

Parameters:
* <code>value</code>: The value to convert to a string. This can be any Lua value. This parameter is optional, and defaults to <code>nil</code>.
* <code>options</code>: A table of options. This parameter is optional.

The following options can be specified in the options table:
* <code>pretty</code>: If true, output the string in "pretty" format (as in [[prettyprint|pretty-printing]]). This will add new lines and indentation between table items. If false, format everything on one line. The default is false.
* <code>tabs</code>: If true, indent with tabs; otherwise, indent with spaces. The default is true. This only has an effect if <code>pretty</code> is true.
* <code>spaces</code>: The number of spaces to indent with, if <code>tabs</code> is false. The default is 4. This only has an effect if <code>pretty</code> is true.
* <code>semicolons</code>: If true, table items are separated with semicolons. If false, they are separated with spaces. The default is false.
* <code>sortKeys</code>: If true, sort table keys in lexical order, after other table key formatting has been applied (such as adding square brackets). If false, table keys are output in arbitrary order (the order they are processed by the [[mw:LUAREF#pairs|pairs]] function). The default is true.
* <code>depth</code>: The indentation depth to output the top-level object at. The default is 0. This only has an effect if <code>pretty</code> is true.

Features:
* The function handles cyclic tables gracefully; when it detects a cycle, the inner table is rendered as <code>{CYCLIC}</code>.
* <code>__tostring</code> metamethods are automatically called if they are available.
* The sequence part of a table is always rendered as a sequence. If there are also key-value pairs, they will be rendered after the sequence part.

Here is an example that shows off all the bells and whistles:

<syntaxhighlight lang="lua">
local myTable = {
	hello = "repr",
	usefulness = 100,
	isEasyToUse = true,
	sequence = {"a", "sequence", "table"},
	mixed = {"a", "sequence", with = "key-value pairs"},
	subTables = {
		moreInfo = "Calls itself recursively on sub-tables"
	},
	usesToString = setmetatable({}, {__tostring = function () return "__tostring functions are called automatically" end}),
	["$YMBOL$"] = "Keys that aren't Lua identifiers are quoted";
	[{also = "Tables as keys work too";}] = "in case you need that",
	cyclic = {note = "cyclical tables are printed as just {CYCLIC}"}
}
myTable.cyclic.cyclic = myTable.cyclic  -- Create a cycle
 
local options = {
	pretty = true,      -- print with \n and indentation?
	semicolons = false, -- when printing tables, use semicolons (;) instead of commas (,)?
	sortKeys = true,    -- when printing dictionary tables, sort keys alphabetically?
	spaces = 3,         -- when pretty printing, use how many spaces to indent?
	tabs = false,       -- when pretty printing, use tabs instead of spaces?
	depth = 0,          -- when pretty pretty printing, what level to start indenting at?
}
mw.log(mRepr.repr(myTable, options))
</syntaxhighlight>

This logs the following:

<pre>
{
   ["$YMBOL$"] = "Keys that aren't Lua identifiers are quoted",
   [{
      also = "Tables as keys work too"
   }] = "in case you need that",
   cyclic = {
      cyclic = {CYCLIC},
      note = "cyclical tables are printed as just {CYCLIC}"
   },
   hello = "repr",
   isEasyToUse = true,
   mixed = {
      "a",
      "sequence",
      with = "key-value pairs"
   },
   sequence = {
      "a",
      "sequence",
      "table"
   },
   subTables = {
      moreInfo = "Calls itself recursively on sub-tables"
   },
   usefulness = 100,
   usesToString = __tostring functions are called automatically
}
</pre>