Editing Module:Buffer/doc (section)

==HTML library extension==
Upon the first call to {{luaself|:_inHTML}}, Module:Buffer clones the {{luaref|HTML library|mw.html object metatable|y}}, adding Module:Buffer's __eq and __concat metamethods along with a few additional functions.

Objects with this modified metatable are referred to as '''Buffer-HTML objects'''. Yet, though dressed in bells and whistles, they are only named with ''Buffer'' as an adverb since they lack most Buffer object functions.

In contrast, the '''Element-Buffer''' (returned by [[#Buffer-HTML|the function call on a Buffer-HTML object]]) is a true Buffer object with specialized "tricks" allowing complex structures to be built via both mw.html and Buffer object methods as well as through a [[#Element-Buffer:_add|builder that perhaps marries the best of both worlds]].

===Buffer functions for HTML===

====Buffer:_inHTML====
{{luaself|:_inHTML|args=tagName, args|args2={ args{{ndash}}list } }}

Accepts the same parameters as {{luaref|mw.html.create||y}} to create and return a [[#Buffer-HTML|modified mw.html object]]. As with {{luaself|:_in}}, this does ''not'' append the child object to the parent Buffer and instead sets a Buffer-style parent reference.

An exception to the above is when chaining this to an [[#Element-Buffer|''Element-''Buffer]] and such produces a ''selfClosing'' tag; when both conditions are met, this appends the tag and returns to the same Buffer.<ref group="note">That is, Element-Buffer{{code|lang=lua|:_inHTML'br'}} may be shorthand for {{code|lang=lua|:tag'br':done()()}} when planning to continue using Buffer object functions. This "auto-done and back" for selfClosing tags does not apply to non-element Buffers in order not to encourage the use of Buffer:_inHTML for simple tags as per [[#Tips and style recommendations]].</ref>

Unlike mw.html.create, if {{code|args}} has keys other than <code>args.parent</code> and <code>args.selfClosing</code>, it will pass for further processing through {{luaself|pre=Element-Buffer|:_add|plain=y}} (a cousin of {{luaself|:_all|plain=y}} that handles mw.html functions). Moreover, if passed a table where mw.html.create expects ''tagName'', this treats it as ''args'' instead.

Finally, this does not automatically set the <code>mw.html.parent</code> reference, making this an alternative to mw.html:tag

====Buffer:getHTML====
{{luaself|:getHTML|args=value|args2=functionName, ...}}

Available only after {{luaself|:_inHTML}} is used the first time.
{{anchor|lastHTML}}

Accepts the same arguments as {{luaself|:getParent}}, however this instead return the last Buffer-HTML object ("lastHTML") created, or, if available, the lastHTML passed to any of the following functions:
* {{luaself|\-HTML:getParent|plain=y}}
* {{luaself|\-HTML:getBuffer|plain=y}}
* {{luaself|\-HTML:_out|plain=y}} (except when passed {{code|lang=lua|0}})

====Buffer:_html====
{{luaself|:_html|args = at, raw|args2 = raw}}

Available only after {{luaself|:_inHTML}} is used the first time.

This (re-)appends the [[#lastHTML|last Buffer-HTML object]] to the current Buffer object. The <code>raw</code> and <code>pos</code> args are generally the same as those in {{luaself|:_}}.

When called with no arguments on an ''Element-''Buffer, this appends lastHTML without [[#raw|string coercion]]. Be warned however that if the Element-Buffer belongs to lastHTML or one of its tags, such will cause an [[infinite loop]], which can be avoided by passing an explicit nil to append lastHTML as a string.<ref group="note">{{luaself|\-HTML:_parent}} serves a similar role, but appends Buffer objects rather than HTML objects. Also Buffer-HTML:_parent only appends the string form of its ancestor object(s).</ref>

===HTML object functions===
Buffer-HTML objects may be used like any mw.html object. (In fact, merely replacing {{code|mw.html.create}} with {{code|require'Module:Buffer':_inHTML}} in an existing Module should produce the same output.)

{{anchor|wrapper}}
Most mw.html functions are unchanged, except {{luaref|mw.html:tag|:tag}}, {{luaref|mw.html:done|:done}}, and {{luaref|mw.html:allDone|:allDone}} are embedded in a wrapper function that checks whether they return a normal mw.html object. If so, switches the metatable to convert it to a Buffer-HTML object and sets a parent reference. <ref group="note">Buffer(-HTML) objects reference their parent differently from mw.html objects. Passing a normal mw.html object to Buffer:_inHTML as {{code|args.parent}} and then calling {{luaref|mw.html:done|:done}} the object created, followed by {{luaself|:getParent}} on the adopted parent, may return the "child." This is a feature rather than a bug.</ref>

As a side bonus, the {{code|..}} may be used on Buffer-mw.html objects directly (no {{luaref|tostring}} needed).

{{anchor|Buffer-HTML}}
====Buffer-HTML object====
{{luaself|\-HTML|args='string'|args2={ args{{ndash}}list } }}

Call this object as a function to return its {{code|lang=lua|.nodes}} index<ref group="note">{{--}}the internal table which holds elements appended via {{luaref|mw.html:wikitext||y}}, {{luaref|mw.html:tag||y}}, and {{luaref|mw.html:node||y}}</ref>, which this converts to an {{luaself|pre=Element-|\|plain=y}} object, granting it the same metatable as regular Module:Buffer objects (as well as several additional "tricks") and assigning the Buffer-HTML as its parent Buffer.<ref group="note">Passing arguments for {{luaself|pre=Element-|:_add}} via the ''args'' parameter of {{luaself|:_inHTML}} and {{luaself|\-HTML:tag}} during the creation of a new Buffer-HTML object is the only way to use most Buffer object functions on the new HTML object without converting its <code>.nodes</code> into an Element-Buffer.</ref>

This takes one argument which is forwarded to its Element-Buffer. Tables pass to the specialized HTML builder {{luaself|pre=Element-|:_add}}. All other [[#valid]] values are appended to its Element-Buffer via {{luaself|:_}}.

{|style='float:right'
|{{TOC tab|{{TOC tab|{{TOC tab|{{TOC tab|{{TOC tab||Buffer-HTML:_parent|depth=2}}|Buffer-HTML:_str|depth=2}}|Buffer-HTML:_out|depth=2}}|Buffer-HTML:killParent|depth=2}}|Buffer-HTML:getParent|depth=2}}
|}{{anchor|HTML version}}
You cannot chain call regular Buffer functions on a Buffer-HTML object; however, since mw.html functions cannot read Buffer-style parent references, modified versions of methods that return [[#Buffer:_inHTML|the parent Buffer]] are available to Buffer-HTML without having to call into the Element-Buffer. For convenience, {{luaref|mw.html:allDone}} is called automatically prior to the op, though after the <code>lastHTML</code> reference has been set for {{luaself|:getHTML}}.<ref group="note">That is, Buffer:getHTML may be used to return to the child node, though the trade off is that you may still need to call mw.html:allDone before using these methods in order to append the full HTML tree via [[#Buffer:_html|Buffer:_html]].</ref>
:{|
|-
|<div style="margin:0; column-width: 15em; -moz-column-width: 15em; -webkit-column-width: 15em; width:49em;">
*{{replace|'''[[#Buffer:${{!}}:$]]'''|$|getParent}}
*{{replace|'''[[#Buffer:${{!}}:$]]'''|$|killParent}}
*{{replace|'''[[#Buffer:${{!}}:$]]'''|$|_out}} {{ref label|html-0-out|0}}{{ref label|html-ops-out|$}}
*{{replace|'''[[#Buffer:${{!}}:$]]'''|$|_str}} {{ref label|html-0-str|0}}{{ref label|html-ops-str|$}}
*{{replace|'''[[#Buffer:${{!}}:$]]'''|$|_parent}} {{ref label|html-parent|^}}
</div>

<div style='font-size:smaller'>
{{note label|html-0-out|||{{note label|html-0-str|0||&nbsp;if passed {{code|lang=lua|0}} as the first argument, these do not redirect the self-action via <code>:allDone()</code>, however, these always return a Buffer-HTML object (think <code>{{luaself|pre=Element-|:done|args=(0)|plain=y}}</code>). {{note label|html-0-out-perm|||For :_out only, the "magic" number zero ''permanently'' consolidates <code>Buffer-HTML.nodes</code> (whether or not converted)}} just like <code>:_out(0)</code> on a normal Buffer except it would not unset raw mode on an Element-Buffer.}}}}

{{note label|html-ops-out|||{{note label|html-ops-str|$||&nbsp;When passed a [[#valid|valid]] sep for the first op, these temporarily{{ref label||0|html-0-out-perm}} switch the Element-Buffer (or unconverted .nodes) with a table containing only the concatenated string before stringing the Buffer-HTML in the first op. As with the non-HTML versions, only :_out appends the string to the parent Buffer.}}}}

{{note label|html-parent|^||&nbsp;This takes arguments for {{luaself|:_str}} and calls it on the [[#Buffer:_inHTML|parent Buffer of the HTML tree]], returning and appending the result to the same Buffer-HTML object. In other words, the "auto-allDone" doesn't really apply here, or at least not in the same sense as with the other functions. (As a reminder, Buffer:_inHTML does not append to the parent Buffer those Buffer-HTML objects which it returns.)}}
</div>
|}

In addition to the above, [[#gfuncs|global functions]] may be available to Buffer-HTML if enabled; these functions are the same for all Module:Buffer objects{{--}}i.e. the self action is never redirected.

===Element-Buffer functions===
{{anchor|Element-Buffer}}
====Element-Buffer object====
{{luaself|pre=Element-|\|args=sep, i , j}}

Sharing the same metatable as with regular Buffer objects, Element-Buffers concatenate the same way when [[#Buffer object|called]] to produce a string analogous to the [[JavaScript]] DOM [http://www.w3schools.com/jsref/prop_html_innerhtml.asp "innerHTML"] property. In other words, when strung, it is generally the contents of the Buffer-HTML object without the "outerHTML" or tag.

There are exceptions to this "innerHTML" behavior. For instance, as appended to another object via {{luaref|mw.html:node}}, an Element-Buffer and its Buffer-HTML are interchangeable (though appending the former via {{luaself|:_}} only includes the inner result).

Also, using the concatenation operator {{code|lang=lua|..}} on an Element-Buffer includes its tag in a manner depending on if it is selfClosing:
*For most tags, the conjoined string is placed inside the tag, e.g. {{code|lang=lua|Buffer:_inHTML'p' 'inner text' .. 1}} returns {{code|lang=lua|'<p>inner text1</p>'}}.
*For selfClosers, the {{code|lang=lua|..}} op redirects to its Buffer-HTML, e.g. insert [[#Element-Buffer:_add|{{code|lang=lua|1=:_add{selfClosing=true} }}]] in the above example before {{code|lang=lua|.. 1}} to produce {{code|lang=lua|'<p />1'}}.
:{{see|#Modified .. operator}}

You may use most Buffer object functions normally, however if there is a [[#HTML version|Buffer-HTML version]], it instead behaves as though chained on the [[#Buffer-HTML|outer HTML object]].<ref group="note">While Buffer-HTML objects may use [[#global functions]], there is no separate Buffer-HTML version. In other words, the self-action of a global function on an Element-Buffer is <u>not</u> redirected.</ref> You may also chain any mw.html object function. Unless otherwise indicated, such returns a [[#wrapper|wrapper]] method that merely redirects the self-action to the outside Buffer-HTML.<ref group="note">{{luaref|mw.html:allDone}} is doubly wrapped for Element-Buffers, with the other wrapper setting a Buffer parent reference as described at {{luaself|:_inHTML}}. Furthermore, {{luaself|pre=Element-|:tag}} and {{luaself|pre=Element-|:done}} do not call their mw.html namesakes at all, as detailed in their respective sections.</ref>

As a final note, Element-Buffers are in permanent [[#raw|raw mode]] since it is expected that some mw.html method (e.g. :tag and :node) may or will append non-string elements.

====Element-Buffer:done====
{{luaself|pre=Element-|\|args=ops}}

When passed nothing, this should behave just like {{luaref|mw.html:done}} as called the "outer" HTML object{{--}}returning <code>Buffer-HTML.parent</code>, if available, or Buffer-HTML if not.

However, this has been re-designed to accept {{code|ops}}, the number of :done() operations to perform. Thus, {{code|Element{{ndash}}Buffer:done(4)|lang=lua}} is equivalent to {{code|Buffer{{ndash}}HTML:done():done():done():done()|lang=lua}}.

Pass {{code|lang=lua|0}} (zero) as ''dones'' to return to the Element-Buffer's direct HTML container.

Finally, keep in mind that Buffer-HTML objects use the original mw.html:done (albeit in a light [[#wrapper|wrapper]]).

====Element-Buffer:tag====
{{luaself|pre=Element-|:tag|args=tagName, args|args2={ args{{ndash}}list } }}

This uses the same helper method as {{luaself|:_inHTML|plain=y}} to handle arguments and produce new Buffer-HTML objects, selectively passing ''args'' to {{luaself|:_add|plain=y}} when it contains keys not used by {{luaref|mw.html.create||y}}.

As may be expected, this differs from Buffer:_inHTML in that this actually appends the tag and will set a mw.html-style parent reference. This also lacks the other function's "auto-done" feature for selfClosing tags.

As with the other Element-Buffer remake of an mw.html method, the features described here do not apply to the version used by Buffer-HTML objects.

====Element-Buffer:_add====
{{luaself|pre=Element-|:_add|args=args|args2={ wikitext{{ndash}}list, { args{{ndash}}list }, ..., arg {{=}} value, functionName {{=}} args } }}

Takes a table as its only argument. This then thoroughly iterates all number keys from lowest<sup>[[#endnote_skip1|†]]</sup> to highest using [[#MBpairs|this module's custom __pairs]] method. Most values append as wikitext if [[#valid|valid]]. If a table is indexed at a number key, this [[Recursion (computer science)|recursively]] iterates the table before moving on to the next key.

After processing all number key-value pairs, this then iterates the other (non-number) keys. For those naming a [[#Basic functions|core Buffer object function]], this selectively unpacks {{code|args}} in a manner described at {{luaself|:_all}} when that function is passed the ''nanKey'' parameter (excepting that this does not read numbers as ''pos'', i.e. treats them the same way as strings).

This also accepts keys naming [[#HTML object functions|HTML]] and [[#Global functions|global functions]] as well as mw.html arguments. Thus, {{code|lang=lua|Element{{ndash}}Buffer:_add{ tag {{=}} 'br', 'text'} }} appends a BR tag ''after'' the text and {{code|lang=lua|Element{{ndash}}Buffer:_add{ {tag {{=}} 'br' }, 'text'} }} appends the BR before the text. Note however that how this handles ''args'' for such keys depends on the particular function or argument named:
:{|
|
======args.''argName''======
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ arg = value } }}<br />
The effect of passing ''args'' with keys such as <code>args.selfClosing</code> and <code>args.parent</code> is the same as though ''args'' were passed to {{luaref|mw.html.create}}. This also takes one additional ''arg'', i.e. <code>args.tagName</code>, which value replaces the original ''tagName'' of the HTML object (or, if false, removes the tag).

Note that these are the only keys for which a boolean ''arg'' would result in an op. (For Buffer object functions that do not no-op when passed only a boolean, place the boolean in an ''args'' table for unpacking.)

======args.''cssName''======
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ cssName = cssValue } }}<br />
A non-number ''key'' and ''value'' pair may default as the <code>cssName</code> and <code>cssValue</code> parameters for {{luaref|mw.html:css}} when the key matches none of the three [[#args.argsName|argName]] keys nor the name of any available function for Buffer and mw.html objects.

This sends non-boolean ''cssValue'' though {{luaref|tostring||y}} prior to forwarding it to mw.html:css. Because this is the default, any typoed key goes to mw.html:css as ''cssName''. Names of functions not yet [[#loadable|loaded]] also end up there.

For convenience, any <code>_</code> character in the key string is automatically substituted with the <code>-</code> character; thus {{code|lang=lua|1=border_bottom_style =}} is equivalent to {{code|lang=lua|1=['border-bottom-style'] =}}.

The form {{code|lang=lua|1=Element-Buffer:_add{ css = { cssName = cssValue } } }} also works (or to clear a previously set value; see example at [[#args.htmlFunction|args.htmlFunction]] for more details).

{{anchor|args.tag}}
======args.tag<sup>[[#endnote_skip1|†]]</sup>======
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ tag = tagName } }}<br />
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ tag = { tagName, args{{ndash}}list } } }}<br />
Set the key <code>args.tag</code> to a string and this calls {{luaref|mw.html.create||y}} with it as the ''tagName'' argument. This then raw inserts the returned mw.html object ("tag"), emulating the effect of {{luaref|mw.html:tag||y}} minus parent references, which are unnecessary.

Pair the ''args.tag'' key with a table value and this calls mw.html.create with {{code|lang=lua|table[1]}} as ''tagName'' (or nil if [[#invalid]]), appending it as described above for string values, but also pointing <code>tag.parent</code> to the [[#Buffer-HTML|Element-Buffer's parent]] as well as temporarily setting the tag as the parent Buffer of <code>tag.nodes</code>. This then treats tag.nodes as a ''[[pseudo]]-''Element-Buffer, [[Recursion (computer science)|recursing]] tag.nodes as "self" and the table as ''args'', though only iterating keys not equal to {{code|lang=lua|1}} (or less).[[#endnote_skip1-tag|<sup>[*]</sup>]]

Note this appends normal mw.html objects. That said, most Buffer functions named in ''args-list'' should still work as though the tag and <code>tag.nodes</code> were Buffer objects.<ref group="note">However, some Buffer methods may not work properly after appending objects via mw.html functions to the pseudo-Buffer.<br />
For example, {{code|lang=lua|1={ tag = {'div', 'List:', foo1, foo2, foo3, _out = { 0, '\n*' } } } }} could produce a div with each ''foo'' as [[Bullet_(typography)|bulleted]] item. But, if ''foo1'' were {{code|lang=lua|1={ tag = { 'b', 'text' } } }}, then {{luaself|:_out|plain=y}} may fail when appending {{luaref|table.concat||y}} with the non-string/number element. A workaround is to add the pair {{code|lang=lua|1=_ = {true, true} }} to set [[#raw|raw mode]] on the div's tag.nodes; another is to replace ''foo1'' with {{code|lang=lua|mw.html.create'b':wikitext'text'}}, which appends in string form.</ref>

Upon completing a recursive iteration for args.tag, this checks if the tag is selfClosing, in which case, this sets tag.nodes to nil. Likewise, if its tagName property evaluates false, this nils tag.styles and tag.attributes. Such presumes those properties will not be modified afterwards, so use mw.html:tag outside of Element-Buffer:_add if such is not the case.

{{anchor|args.done}}
======args.done<sup>[[#endnote_skip1|†]]</sup>======
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ done = wikitext } }}<br />
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ done = { ops, args{{ndash}}list } } }}<br />
Similar to args.tag, this treats the first index of the table as the ''ops'' argument of {{luaself|pre=Element-|:done}}. After calling that function, this then iterates all subsequent keys in a recursive call on the Element-Buffer of the Buffer-HTML object returned.

======args.allDone======
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ allDone = wikitext } }}<br />
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ allDone = { args{{ndash}}list } } }}<br />
Similar to the previous two, except that the first index is not used as an argument; thus, the entire table is iterated.

{{anchor|args.globalFunction}}
======args.''globalFunction''<sup>[[#endnote_skip2|‡]]</sup>======
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ globalFunction = name } }}<br />
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ globalFunction = { name, save, args{{ndash}}list } } }}<br />
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ _B = { var, args{{ndash}}list } } }}<br />
If the [[#gfuncs|global functions]] have been loaded and a key matches one, this calls the function with the first two arguments {{luaref|unpack||y}}ed from the paired ''args-list'' table. This then recursively iterates the list, excluding keys less than or equal to {{code|lang=lua|2}}, with whatever object is returned as ''self''. However, if the returned object has a metatable and <code>object.nodes</code> exists, the ''self'' will be object.nodes instead.

Because {{luaself|:_B}} takes only one argument, args._B only unpacks the first index and starts the iteration after that key.

If neither of the first two keys evaluate true, this assumes the paired value is a string for use as the ''name'' argument for the function matching its key.<ref group="note">A caveat of this unconventional type checking is that pairing an args.globalFunction with a number value will throw an error (which shouldn't be a problem since numbers make poor names for global variables).</ref> In that case, the current call stack's ''self'' (an Element-Buffer or [[#args.tag|tag.nodes]] if this was called indirectly) is ''self'' for the global function.

======args.''htmlFunction''======
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ htmlFunction = object } }}<br />
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ htmlFunction = { arg-list, name = value } } }}<br />
If args.''key'' matches an {{luaref|HTML library|mw.html object function|y}} that does not have its own args section, this checks if the associated ''object'' is table. If not a table, or if <code>object.nodes</code> evaluates true, this calls the mw.html function with the object as the only argument.

For table objects without an object.nodes, this iterates the table (non-recursively), repeatedly calling the named mw.html function with one or two arguments depending on key's type in each loop. Non-number key-value pairs are both passed as arguments. For numeric indices, only the value is passed. Boolean values are a no-op.

Unlike with most implementions of [[#MBpairs|Module:Buffer's __pairs]], this first loops through ''non-''number keys, followed by number keys (still ordered from lowest to highest). Thus, something like {{code|lang=lua|1=Element{{ndash}}Buffer:_add{ attr = { 'width', width = 20 } } }} is equivalent to {{code|lang=lua|Element{{ndash}}Buffer:attr( 'width', 20 ):attr( 'width' )()}}, setting then unsetting the width attribute and returning the Element-Buffer for a net no-op (though the practical purpose of such is a mystery for this developer).

For <code>args.css</code> only, this auto-replaces underscores with hypens for string keys{{--}}i.e., you may save four keystrokes/pair by typing <code>css_property =</code> instead of <code>["css-property"] =</code>. This does not apply to strings indexed at number keys.

<!--//redundant?
======args.''bufferFunction''======
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ bufferFunction = object } }}<br />
{{code|lang=lua|1=Element{{ndash}}Buffer:_add{ bufferFunction = { expression{{ndash}}list } } }}<br />

If passed a table object that has no metatable such that {{code|lang=lua|object[1]}} exists, this {{luaref|unpack}}s the table from {{code|lang=lua|1}} and {{luaref|table.maxn|args=table}} for use as arguments for the Buffer object function named. Other objects are passed as the only argument to the designated function.
//!-->

<div style='font-size:smaller;'>
----
{{note label|skip1|†||&nbsp;Unlike with tables passed directly, [[Recursion (computer science)|recursive]] iterations for functions marked with <sup>†</sup> start at the smallest number greater than {{code|lang=lua|1}} instead of negative infinity.}}

{{note label|skip2|‡||&nbsp;The iteration may start after {{code|lang=lua|2}} for some global functions.}}
</div>
|}

{{anchor|loadable}}