Content deleted Content added
save |
save |
||
Line 5:
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
{{TOC right}}
This
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 {{luaself|:_}} has the same role, but potentially [[#performance|over 10 times faster than {{code|..}}]]). See also: [[#Calling string, mw.ustring, and mw.text libraries]]
Additionally, there are three specialized modes, described further in their respective sections: {{luaself|:stream|plain=y}}, {{luaself|\-HTML|plain=y}}, and {{luaself|pre=Element{{-}}|\|plain=y}}
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]])▼
Last but not least, this module has an ordered [[#require'Module:Buffer'.__pairs|__pairs]] more thorough than {{luaref|ipairs||y}} and {{luaref|pairs||y}}. (Even reads nil keys!) The <span title='This is a bad Star Trek joke'>logical uniqueness</span> of this iterator may be reason enough to {{luaref|require|assimilate|y}} Module:Buffer.
==Basic usage==
Line 28 ⟶ 30:
:''See also {{luaself|:_str|plain=y}} for advanced string conversion.
Get Buffer as type {{luaref|string||y}} by performing a function call on the Buffer ''object'' (as opposed to [[#require'Module:Buffer'|a call on the ''Module'']]). Calling a Buffer is basically shorthand for {{luaref|table.concat|args=Buffer, ...}}, or, with no args, {{luaref|tostring|args=Buffer}}. However, if your Buffer contains [[#raw|raw]] objects or out-of-sequence values, then the return string would be the result of {{luaself|Buffer|:_all|empty-buffer:_all|args=Buffer )( ...}} instead.<ref group=note name=raw />
▲
===Buffer.last_concat===
Line 127 ⟶ 129:
Unlike :_out, this does not append the child into the parent. As such, even with the same arguments, it may return a different result than would be obtained from stringing the return of :_out since each parents' ''sep'' is not used to join parent and child. Furthermore, the number of ''generations'' counted includes the current Buffer, whereas the number of "''outs''" in Buffer:_out does not.
Nils all keys of the table referenced by {{code|clear}} and unsets its metatable. If
If given a table to {{code|copy}}, this will duplicate all key-value pairs of ''copy'' into ''clear'',
While this may resemble {{luaref|mw.clone}}, there are several differences:
* This sets the metatable of ''clear'' to that of ''copy'' instead of cloning its metatable (or to <code>meta</code>, if given).
* {{luaref|Length operator|Length}} is always conserved (though empty strings may replace some nil keys<ref group=note>
For example, given {{code|lang=lua|{nil, 'string'} }} as ''copy'', {{code|lang=lua|Buffer:_cc(clear, copy)}} makes {{code|lang=lua|#clear}} equal <code>2</code>,
whereas {{code|lang=lua|#mw.clone{nil, 'string'} }} equals <code>0</code> (as of March 2015).
This replicates length by filling clear to copy's length and then setting those keys nil when such would not trigger recalculation.
As a result, any keys which would resize ''clear'' when set nil are left as empty strings. Such should be fairly rare;
given every combination of positions for a single nil key for all lengths between 2 and 32 (inclusive), only 8.39 percent such tables would have a nil copied as empty string instead.
Also note that tables returned by {{code|lang=lua|Buffer:_(0, copy)}} have length declared on creation instead, and thus won't have extra strings attached.
The odds can be estimated using <math>y {{=}} 0.5 / \sqrt{x}</math>, where <math>y</math> is the upper limit that an arbitrary nil key from ''copy'' of length ranging from 1 to <math>x</math> is imaged as an empty string.</ref>)
* All values are set via {{luaself|rawset}} and iterated without invoking any __pairs {{luaref|Metatables|metamethod|y}}.
* Also copies Buffer parent and [[#raw|raw]] settings (which are stored externally)
If ''copy'' is not a table, then it will be inserted as the first index of the ''clear''ed table so long as ''copy'' is not nil or false. Passing {{code|lang=lua|true}} as ''copy'' is equivalent to passing the Buffer itself.▼
To obtain the table of key-value pairs left as empty strings in the previous copy op, simply call this again with any same value passed to both ''clear'' and ''copy'' (as long as they do not evaluate false).
===Buffer:_parent===
Line 153 ⟶ 180:
If passed any args, they will be passed to the current parent via Buffer:getParent as a "parting gift". In either case, returns to current Buffer.
▲===Buffer:_c===
▲{{luaself|:_c|args=clear|args=clear, copy}}
▲Nils all keys of the table referenced by {{code|clear}} and unsets its metatable. If no table as ''clear'', this simply purges the cache at {{luaself|.last_concat}}.
▲If given a table to {{code|copy}}, this will duplicate all key-value pairs of ''copy'' into ''clear'', passing any value of type table through {{luaref|mw.clone}}. Any metatable and Buffer parent and raw references are also copied.
▲If ''copy'' is not a table, then it will be inserted as the first index of the ''clear''ed table so long as ''copy'' is not nil or false.
==Stream mode==
Line 171 ⟶ 188:
Switches the Buffer to stream mode. In this mode, the [[#call Buffer object|Buffer call]] operation, instead of returning a string, now acts as streamlined version of {{luaself|:_}}.
When streaming, you
{{#tag:syntaxhighlight|local A =
'or even tab and line-break characters''and continue to append individually''for use with a joiner'
local B =
:_'or even tab and line-break characters':_'and continue to append individually':_'for use with a joiner'
Line 184 ⟶ 201:
}|lang=lua}}
Aside from saving two keystrokes per
Keep in mind that Lua numbers<ref group=note>It is best practice to pass number ''strings'' instead of
'''Returning to normal mode'''<br/>
No special action is needed to exit this mode. The normal call to string op is restored upon the use of any regular Buffer function or any operation which coerces the Buffer into a string.<ref group=note>No explicit trigger to exit stream mode has been programmed for {{luaself|pre=Element{{ndash}}|\}} functions (including Buffer-HTML redirects). Stringing an Element-Buffer without its outer HTML-Buffer was deemed uncommon enough such that the inconvience of exiting via using <code>:_()</code> on the last item was outweighed by the [[#performance]] penalty that may result from modifying the specialized functions.</ref>
===Buffer:stream:each===
{{luaself|:stream:each|args=...}}
Appends an undetermined number of [[#valid|valid]] values.
While analogous to {{luaref|mw.html:wikitext|plain=y}}, one distinguishing point (other than being [[#performance|twice as fast]] and able to [[#Buffer:_|handle tables and booleans]]) is that this does ''not'' stop at the first ''nil'' value. In short, something like {{code|lang=lua|:wikitext('string1', varName, 'string2')}} can be replaced with {{code|lang=lua|:each('string1', {varName, 'string2'})}} when <code>varName</code> is either a string or nil.
==HTML extension==
Line 230 ⟶ 253:
Element-Buffers have the same metatable as normal Buffer objects, so [[#call Buffer object|calling it]] will string it in the same manner.
The string returned is analogous to
You may use most Buffer object
Additionally, you may chain any mw.html object function directly on an Element-Buffer. With the exception of {{luaself|pre=Element{{ndash}}|:tag}} and {{luaself|pre=Element{{ndash}}|:done}}, the mw.html function has been placed in a wrapper function that merely redirects the self-action to the outside Buffer-HTML.<ref group=note>{{luaref|mw.html:allDone}} is doubly wrapped for Element-Buffers. The inner wrapper sets a Buffer parent reference as described at {{luaself|:_inHTML}}.</ref>
Concatenate an Element-Buffer to another value with the {{code|lang=lua|..}} operator to return the result inside the tag, such that:
{{#tag:syntaxhighlight|
local Buff = require'Module:Buffer':_inHTML'div'{'Section ',color='red'}
return {Buff..1,Buff..2,Buff..3}
|lang=lua}}
Can be a rapid way of generating:
{{#tag:syntaxhighlight|
local section = {}
for k = 1, 3 do
table.insert(section, tostring(mw.html.create'div':css{color='red'}:wikitext('Section ', k)))
end
return section
|lang=lua}}
====Element-Buffer:done====
Line 247 ⟶ 285:
===ipairs with HTML-Buffer===
:''See also [[#Using
<pre>
Line 280 ⟶ 318:
==require'Module:Buffer'.__pairs==
{{anchor|library}}
==
{{anchor|tips|Tips}}
Line 303 ⟶ 341:
::versus: {{code|lang=lua|Buffer:_nil('0', condition and 'replacement' or false):_(condition and 'Front', 1):getParent(condition and 'from child'):_B(child)}}.
'''For {{luaself|:
* If the table reference passed as {{code|clear}} was appended [[#raw|raw]] in multiple positions, this is akin to performing {{luaself|:_nil}} at all positions simultaneously. (May be easier than trying to come up with a {{luaref|string.gsub}} pattern)
| |||