Module:Buffer/doc

Usage

This module was originally developed to optimize string concatenation in Module:Asbox but can be used in any module.

The interface for Module:Buffer objects is similar to that of 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 .. operator (though Buffer:_ has the same role, but potentially over 10 times faster than ..).

Buffers can also be appended to mw.html objects via mw.html:node (though not mw.html:wikitext because of type checking). (See also #usage with string/mw.text libraries)

require('Module:Buffer')

require('Module:Buffer')( ... )

require('Module:Buffer')( _G, ... )

Call the module as a function to create a new Module:Buffer object—i.e., there is no 'main'.

Some functions are available only if Module:Buffer is initialized with the global variable _G prior to the creation of any Buffer objects (see #advanced functions for more detail). If initialized with _G then any varargs will be passed to Buffer:_G( \ )


. If initialized without then any varargs will by passed to Buffer:_( ... )


.

You may also use any Buffer object function directly on the module—i.e require('Module:Buffer'):function{...} is equivalent to require('Module:Buffer')():function{...}.

Buffer

Buffer( sep, i, j )




A function call on a Buffer object (as opposed to calling the Module) is basically shorthand for table.concat( Buffer, ... ) , or with no args, tostring( Buffer ) .

However, if Buffer contains values inserted via Buffer:_ that are either raw (see below section) or are out-of-sequence (i.e. keys of type 'number' ignored by ipairs), then the string returned would be from ''empty-buffer'':_all( Buffer )


( ... )

When called without a separator or used as a string, the concatenated result may be retrieved via Buffer.last_concat. Future calls or tostring operations on the Buffer will return Buffer.last_concat until the Buffer is modified. (See next section for details on caching behavior.)

Buffer:_

Buffer:_( value, pos, raw )




Buffer:_( value, raw )




In rough terms, Buffer:_'string1':_'string2' is the same as Buffer = Buffer..'string1'..'string2'. (If it helps, imagine the :_ as a .. that has stood up and is now casting a shadow).

If passed that is any of the following, then :_ will be a no-op:

• nil
• boolean
• an empty string ('' or "")
• a table without a __tostring metamethod and which table[1] is nil or false.

Tables lacking a __string metamethod are converted to string via table.concat. Note that the only way for :_ to throw an error is if the table passed is one that would cause table.concat to throw an error. (Use Buffer:_all instead for such cases)

For all other values, the result of tostring( value ) would be inserted as long as that is not an empty string.

You may set optional 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 Buffer:_all instead of table.concat, which could result in a small performance penalty that may be undesirable for highly transcluded modules. (See #Tips for ways to avoid using raw)

When passed a pos of type 'number', Using {{code|When given only value as an argument, this is essentially the same as the .. operator

Inserts a value if it is valid. The pos argument is similar to that of table.insert( table, pos, value ) , except in two cases: 1) the first

Buffer:_in

Saving Module:Buffer locally, e.g. local Buffer = require'Module:Buffer' , though fine, is often unnecessary since all Buffer objects can create new buffers via Buffer:_in.

Tips

• To insert an empty string without setting raw as a placeholder for a concat separator, use

Buffer:_( {''} )


(i.e. a table containing only a empty string.)

Example

For example, take the following snippet from the p.templatepage() function of Module:Asbox.

content = buffer(page.text ~= 'Stub' and require('Module:Asbox stubtree').subtree{args = {pagename = page.text}})
	:_in'\n== About this template ==\nThis template is used to identify a':_(args.subject):_'stub':_(args.qualifier):_out' '
	:_'. It uses {{[[Template:Asbox|asbox]]}}, which is a meta-template designed to ease the process of creating and maintaining stub templates.\n=== Usage ===\nTyping <code>{{'
	:_(page.text == 'Stub' and 'stub' or page.text)
	:_'}}</code> produces the message shown at the beginning, and adds the article to the following categor'
	:_(#stubCats > 1 and 'ies' or 'y')
	:_':\n'()

That snippet is basically equivalent to:

content = page.text ~= 'Stub' and
	require('Module:Asbox stubtree').subtree{args = {pagename = page.text}}
	or ''
content = content .. '\n== About this template ==\nThis template is used to identify a'
if args.subject then
	content = content .. ' ' .. args.subject
end
content = content .. ' stub'
if args.qualifier then
	content = content .. ' ' .. args.qualifier
end
content = content
	.. '. It uses {{[[Template:Asbox|asbox]]}}, which is a meta-template designed to ease the process of creating and maintaining stub templates.\n=== Usage ===\nTyping <code>{{'
	.. (page.text == 'Stub' and 'stub' or page.text)
	.. '}}</code> produces the message shown at the beginning, and adds the article to the following categor'
	.. (#stubCats > 1 and 'ies' or 'y')
	.. ':\n'