Module:Buffer/doc: Difference between revisions

Revision as of 20:54, 19 February 2015

Revision as of 23:22, 20 February 2015

Line 4:

This module was originally developed to optimize string concatenation in [[Module:Asbox]] but can be used in any module.

The interface for Module:Buffer objects is similar to that of {{Luaref|HTML_library|mw.html}} objects in that you may build complex strings with independent child nodes. In most cases, you may use Buffer objects like a normal string, including using {{code|..}} operator (though better to use {{luaself|:_}} sincehas the concatenationsame operatorrole, isbut potentially [[#performance|over 10 times slower]]). It can also be insertedfaster intothan {{luarefcode|HTML library|mw.html}} objects via {{luaref|mw.html:node}} (though not mw.html:wikitext because of type checking). (See also [[#usage with string/mw.text libraries]]).

Buffers can also be appended to {{luaref|HTML library|mw.html}} objects via {{luaref|mw.html:node}} (though not mw.html:wikitext because of type checking). (See also [[#usage with string/mw.text libraries]])

{{anchor|module}}

===require('Module:Buffer')===

{{luaself|Buffer|subpage= |\|require('Module:***')||subpage= |args=...|args2=_G, ...}}

UseCall the module directly as a function to create a new Module:Buffer object ({{--}}i.e., there is no 'main').

{{luaself|Buffer|subpage= |\|require('Module:***')|args=...|args2=_G, ...}}

Some functions are available only if Module:Buffer is initialized with the global variable {{luaref|_G}} prior to the creation of any Buffer objects (see [[#advanced functions]] for more detail). If initialized with _G then any {{luaref|varargs}} will be passed to {{luaref|self=Buffer/doc|:_G|args=\}}. If initialized without then any varargs will by passed to {{luaref|self=Buffer/doc|:_|args=...}}.

Use the module directly as a function to create a new Module:Buffer object (i.e. there is no 'main').

If initialized with _G then any {{luaref|varargs}} will be passed to {{luaref|self=Buffer/doc|:_G|args=\}}. If initialized without then any varargs will by passed to {{luaref|self=Buffer/doc|:_|args=...}}. You may also omit initialization and use any Buffer object function directly on the module{{--}}i.e <code style='white-space:nowrap'>require('Module:Buffer'):''function''{...}</code> is equivalent to <code style='white-space:nowrap'>require('Module:Buffer')():''function''{...}</code>.

Some functions are available only if Module:Buffer is initialized with the global variable {{luaref|_G}} prior to the creation of any Buffer objects (see [[#advanced functions]] for more detail).

If initialized with _G then any {{luaref|varargs}} will be passed to {{luaref|self=Buffer/doc|:_G|args=\}}. If initialized without then any varargs will by passed to {{luaref|self=Buffer/doc|:_|args=...}}. You may also omit initialization and use any Buffer object function directly on the module{{--}}i.e <code style='white-space:nowrap'>require('Module:Buffer'):''function''{...}</code> is equivalent to <code style='white-space:nowrap'>require('Module:Buffer')():''function''{...}</code>.

Saving the module locally, e.g. <code>local Buffer = {{luaref|require|args='Module:Buffer'|plain=y}}</code>, though perfectly valid, is often unnecessary since all Buffer objects can create new buffers via {{luaref|self=Buffer/doc|:_in}}

====Buffer====

{{luaref|self=Buffer/docluaself|\|args=...sep, i, j}}

CallingA thefunction Buffercall objecton createda by''Buffer this moduleobject'' (as opposed to the[[#require('Module:Buffer')|calling modulethe itselfModule]]) is basically shorthand for {{luaref|table.concat|args=Buffer, ...}}, or with no args, {{luaref|tostring|args=Buffer}}.

However, if Buffer contains values inserted via {{luaref|self=Buffer/doc|:_}} that are either raw (see below section) or are out-of-sequence (i.e. numerical keys of type 'number' ignored by {{luaref|ipairs}}), then the resultstring returned would be the same asfrom {{luaref|self=Buffer/doc|:_all|''empty-buffer'':_all|args=Buffer}}{{code|( ... )}}{{--}}which would iterate through all keys in numerical order, converting each item to a string before concatenating.

When called without a separator or used as a string, the concatenated result may be retrieved via {{code|Buffer.last_concat}}. Future calls or tostring operations on the Buffer will return Buffer.last_concat until the Buffer is modified. (See next section for details on caching behavior.)

As a side note, if no args are passed , the the result of the concatenation are cached by the Buffer,

====Buffer:_====

<code>Buffer{{luaself|:_( |args=value, pos, raw|args2=value, )</code><br>raw}}

<code>Buffer:_( value, raw )</code><br>

In rough terms, <code>Buffer:_'string1':_'string2'</code> is the same as <code>Buffer = Buffer..'string1'..'string2'</code>. (If it helps, imagine the {{code|:_}} as a {{code|..}} that has stood up and is now casting a shadow).

{{anchor|valid}}If passed {{value}} that is any of the following, then {{code|:_}} will be a no-op:

* nil

* boolean

* an empty string (<nowiki>''</nowiki> or "")

* a table without a {{luaref|__tostring}} metamethod and which table[1] is nil or false.

Tables lacking a __string metamethod are converted to string via {{luaref|table.concat}}. Note that the only way for :_ to throw an error is if the table passed is one that would cause table.concat to throw an error. (Use {{luaself|:_all}} instead for such cases)

For all other values, the result of {{luaref|tostring|args=value}} would be inserted as long as that is not an empty string.

You may set optional {{code|raw}} argument to true to insert a value without tostring coercion (e.g. an mw.html object while retaining the ability to change the mw.html object at that position). Note however that raw insertion will cause all future conversions of the Buffer to be handled by {{luaself|:_all}} instead of table.concat, which could result in a small [[#performance|performance]] penalty that may be undesirable for highly transcluded modules. (See [[#Tips]] for ways to avoid using raw)

When passed a {{code|pos}} of type 'number',

Using {{code|When given only {{code|value}} as an argument, this is essentially the same as the {{code|..}} operator

Inserts a {{code|value}} if it is [[#valid values|valid]]. The {{code|pos}} argument is similar to that of {{luaref|table.insert|args=table, pos, value}}, except in two cases: 1) the first

Line 37 ⟶ 54:

=====valid values=====

===require('Module:Buffer')():_

Each time you call <code>buffer()</code> it will return a new buffer object of type table, which you may save like so:

====Buffer:_in====

<pre>

Saving the moduleModule:Buffer locally, e.g. <code>local Buffer = {{luaref|require|args='Module:Buffer'|plain=y}}</code>, though perfectly validfine, is often unnecessary since all Buffer objects can create new buffers via {{luaref|self=Buffer/doc|:_in}}.

local buffer = require('Module:Buffer')

local string1, string2 =

</pre>

====Buffer:_inHTML====

Line 51 ⟶ 66:

==usage with string/mw.text libraries==

==Tips==

* To insert an empty string without setting {{code|raw}} as a placeholder for a {{luaref|table.concat|concat separator}}, use {{luaself|:_|args={<nowiki>''}</nowiki>}} (i.e. a table containing only a empty string.)

==Example==