Module:Buffer/doc: Difference between revisions

Revision as of 23:22, 20 February 2015

Revision as of 19:01, 21 February 2015

Line 31:

====Buffer:_====

{{luaself|:_|args='string'|args2=value, pos, raw|args2args3=value, raw}}

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}}<u>No-op values</u><br />
If passed {{code|value}} that is any of the following, then {{code|:_}} will be a no-op:

* {{luaref|nil|plain=y}}

* {{luaref|boolean|plain=y}}

* an empty {{luaref|string (<nowiki>''</nowiki> or "")|plain=y}}

* a {{luaref|table|plain=y}} 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}}. NoteAn that{{luaref|error}} themay onlybe way for :_ to throw an error isthrown 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 data values, the result of {{luaref|tostring|args=value}} would be inserted asso long as thatit 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)

You may set optionalSet {{code|raw}} argument to true to insert a value without tostring coercion (e.g., an unfinished mw.html objector while retaining the ability to change the mw.htmlBuffer 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 inincurring 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

When passed {{code|pos}} of type {{luaref|number|plain=y}}, the argument is the same as for {{luaref|table.insert|args=table, '''pos''', value}}. (In fact, assuming a [[#valid]] value, {{luaself|:_|args=''value'', 1}} is exactly the same as {{luaref|table.insert|args=Buffer, 1, ''value''}}.)

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

The treatment of {{code|pos}} of type {{luaref|string|plain=y}} is unconventional in that the length of the Buffer is added to {{code|pos}}. In other words, {{luaself|:_|args='string', '-1'}} is the same as {{luaself|:_|args='string', #Buffer - 1}} (obviating the need to store Buffer as a local variable just to use the {{luaref|Length operator|length operator|plain=y}}).

====Buffer:_all====

{{luaself|:_all|args={ ''value'', ... }|args2={ ''value'', ''value'' {{=}} ''pos'', ... }, ''value-key''}}

====Buffer:_in====