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:_'string'




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 :_ as a .. that has stood up and is now casting a shadow).

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

• nil
• boolean
• an empty string
• 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. An error may be thrown if the table passed is one that would cause table.concat to error. (Use Buffer:_all instead.)

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

Set raw to true to insert without tostring coercion (e.g., an unfinished mw.html or Buffer object). Note however that raw will cause all future conversions of the Buffer to be handled by Buffer:_all instead of table.concat, incurring a performance penalty that may be undesirable for highly transcluded modules. (See #Tips for ways to avoid using raw)

When passed pos of type number, the argument is the same as for table.insert( table, '''pos''', value ) . (In fact, assuming a #valid value, Buffer:_( ''value'', 1 )


is exactly the same as table.insert( Buffer, 1, ''value'' ) .)

The treatment of pos of type string is unconventional in that the length of the Buffer is added to pos. In other words, Buffer:_( 'string', '-1' )


is the same as Buffer:_( 'string', #Buffer - 1 )


(obviating the need to store Buffer as a local variable just to use the length operator).

Buffer:_all

Buffer:_all{ ''value'', ... }




Buffer:_all( { ''value'', ''value'' = ''pos'', ... }, ''value-key'' )




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'