Editing Module:Buffer/doc (section)

===String, mw.ustring, and mw.text libraries===

====Basic usage====
{{code|lang=lua|Buffer:functionName( ... )}}

You may directly chain any function from the following libraries on Buffer objects:
:{|
|{{collist|colwidth=15em|style=width:49em|
* {{luaref|String library|string|y}}
* {{luaref|Text library|mw.text|y}}
* {{luaref|Ustring library|mw.ustring|y}} }}
|}

Functions from these libraries added to the Module:Buffer metatable on-demand and placed within a wrapper method that strings the Buffer object for the first argument and then forwards the remaining arguments.

Thus, the following are equivalent: {{code|lang=lua|Buffer:nowiki( ... )}} and {{luaref|mw.text.nowiki|args=tostring(Buffer), ...}}

If a name exists in both the string and mw.ustring libraries, the string version takes precedence. You may [[prefix]] the letter ''u'' on any mw.ustring function{{--}}e.g. Buffer:ulen returns the number of unicode characters and Buffer:len returns the number of bytes.

Buffer:gsub and Buffer:ugsub have a slightly different wrapper which substitutes the <code>repl</code> argument of {{luaref|string.gsub||y}} and {{luaref|mw.ustring.gsub||y}} when it evaluates false or is omitted with an empty string (otherwise the originals would throw an error). This saves a few keystrokes when removing characters via {{code|lang=lua|Buffer:gsub'[pattern]'}} as opposed to {{code|lang=lua|Buffer:gsub( '[pattern]', '' )}}. All other arguments are handled the same as with the other on-demand methods.

Library functions which take a non-string as the first argument are not supported.

====Empty Buffer interface====
{{luaself|:_in|args=():functionName( ... )}}

To obtain the first return value as a Buffer object (as opposed to whatever type the original normally returns), simply chain the imported method immediately after creating the new Buffer via [[#Buffer:_in|Buffer:_in]]. Only empty Buffer objects which have a parent object will append the result of their parent in this manner.

This syntactic sugar allows two things:
* For appending additional objects after the op via Buffer object methods.
* For chaining multiple {{luaref|_|Scribunto|y}} methods not chainable to strings{{--}}e.g., this: {{code|lang=lua|1=Buffer:_in():uformat( ... ):_in():toNFD():encode'[<>#]':match'^(.-)==='}}
: vs. the following which has the same order of operations albeit harder to see: {{code|lang=lua|1=mw.text.encode( mw.ustring.toNFD( Buffer:uformat( ... ) ), '[<>#]' ):match'^(.-)==='}}

:{|
|
=====Special case: Element-Buffer=====
{{code|lang=lua|empty{{ndash}}Element{{ndash}}Buffer:functionName( ... )}}<br />
{{code|lang=lua|Element{{ndash}}Buffer:_in():functionName( ... )}}

The 'empty' behavior is different when chained to empty Element-Buffer or an empty child Buffer of an Element-Buffer.

Library methods chained to an empty Buffer which parent is an [[#Element-Buffer|Element-Buffer object]] will instead string the grandparent [[#Buffer-HTML|Buffer-HTML object]] for use as the first argument before appending the result to the new Buffer. This interface is provided because Buffer-HTML objects, which are not true Buffer objects, are unable to load these functions, making this the only chainable option for Scribunto methods that includes the outer tag of non-empty Element-Buffers.

Chained on an empty Element-Buffer, these methods will string the Buffer object which created its HTML tree via {{luaself|:_inHTML}}<ref group="note">Though this strings the same object returned by {{luaself|\-HTML:getParent}}, that function is not used to avoid setting a "lastHTML" reference.</ref> and append the result to the Element-Buffer.<ref group=example>Compare the comment and source:
:{|
|{{#tag:syntaxhighlight|--[[--= Result: ===>

This is just a quick example to demonstrate a neat concept:
<div>Notice how the same object is strung which allows you to recycle boilerplate text.
<p>3 is 1 added to 2.</p>
<span>Though this is not really realistic to be fair...
Edit: not realistic at all</span>
I hope such is much to your liking.</div>

--]]--= Source: ===>
require'Module:Buffer'
	'%s is %s to %s.'--A
	:_inHTML'div'():format('Notice how the same object', 'strung which allows you', 'recycle boilerplate text')
		:tag'p'():format(3, '1 added', 2)
		:done()
		:tag'span'():format('Though this', 'not really realistic', 'be fair..')
			:_in():sub(21, 29)
				:_('\nEdit:', 1)
				:_'istic at all'
			:_out()
		:done()
		:_parent()--B
	:_out'\n'
	:format('This', 'just a quick example', 'demonstrate a neat trick',--A
		'I hope such', 'much', 'your liking')--B
	:gsub('trick.', 'concept:\n')|lang=lua}}
|}</ref>
|}