Editing Module:Buffer/doc (section)

====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}}