Difference between revisions of "Module:Util"
m (Update link function to remove the dab of the pagename, to use as a label, instead of removing all parenthesized text.) |
(General cleanup. Fix trailing whitespace in the italicNoDab function. Add specialized documentation. Cleanup lazy loads (require takes care of that).) |
||
Line 1: | Line 1: | ||
-- <pre> | -- <pre> | ||
− | -- @ | + | --[=[Doc |
− | + | @module Util | |
− | + | @description Holds commonly used simple functions. | |
− | + | @author [[User:Becasita]] | |
+ | @contact [[User talk:Becasita]] | ||
+ | @todo Remove those last functions to a dedicated module | ||
+ | or simply remove them. | ||
+ | ]=] | ||
------------------- | ------------------- | ||
-- Export variable: | -- Export variable: | ||
------------------- | ------------------- | ||
− | -- @ | + | --[[Doc |
+ | @data U | ||
+ | @description Variable to hold the library to be exported. | ||
+ | @exportable | ||
+ | ]] | ||
local U = {}; | local U = {}; | ||
Line 15: | Line 23: | ||
------------- | ------------- | ||
-- mw functions: | -- mw functions: | ||
− | |||
local mwTextTrim = mw.text.trim; | local mwTextTrim = mw.text.trim; | ||
− | -- @ | + | --[[Doc |
− | + | @function U bold | |
+ | @description Renders bold wikitext markup. | ||
+ | @parameter {string} s String to make bold. | ||
+ | @return {string} Bold formatted `s`. | ||
+ | @todo Escape ' ? | ||
+ | ]] | ||
function U.bold( s ) | function U.bold( s ) | ||
− | return ("'''%s'''"):format( s ) | + | return ("'''%s'''"):format( s ); |
end | end | ||
− | -- @ | + | --[[Doc |
− | + | @function U italic | |
+ | @description Renders italic wikitext markup. | ||
+ | @parameter {string} s String to italicize. | ||
+ | @return {string} Italicized `s`. | ||
+ | @todo Escape ' ? | ||
+ | ]] | ||
function U.italic( s ) | function U.italic( s ) | ||
− | return ("''%s''"):format( s ) | + | return ("''%s''"):format( s ); |
end | end | ||
− | -- @ | + | --[=[Doc |
− | + | @function U italicNoDab | |
− | + | @description Renders italics wikitext markup, except for the dab. | |
+ | Also normalizes the space between the dab and the rest. | ||
+ | @parameter {string} s String to italicize, except its dab. | ||
+ | @return {string} Italicized `s`, except its dab. | ||
+ | @see [[#U.getDab]] | ||
+ | @see [[#U.removeDab]] | ||
+ | ]=] | ||
function U.italicNoDab( s ) | function U.italicNoDab( s ) | ||
local dab = U.getDab( s ); | local dab = U.getDab( s ); | ||
− | local noDab = U.removeDab( s ) | + | local noDab = U.removeDab( s ); |
− | return table.concat( { ("''%s''"):format( noDab ), dab }, ' ' ); | + | return table.concat( { |
+ | ("''%s''"):format( noDab ), | ||
+ | dab ~= '' and dab or nil | ||
+ | }, ' ' ); | ||
end | end | ||
− | -- @ | + | --[=[Doc |
− | + | @function U trim | |
− | + | @description Trims white space from front and tail of string. | |
+ | Returns nil if only whitespace. Also normalizes the space between | ||
+ | the dab and the rest. | ||
+ | @parameter {string|nil} s String to trim. | ||
+ | @return {string|nil} Trimmed `s`. If `s` ends up being only whitespace | ||
+ | or `s` is `nil`, it returns `nil`. | ||
+ | @see [[mw:Extension:Scribunto/Lua reference manual#mw.text.trim]] | ||
+ | ]=] | ||
function U.trim( s ) | function U.trim( s ) | ||
if s and not s:match( '^%s*$' ) then | if s and not s:match( '^%s*$' ) then | ||
Line 48: | Line 81: | ||
end | end | ||
− | -- @ | + | --[[Doc |
− | + | @function U count | |
+ | @description Counts the number of elements in a table. | ||
+ | @parameter {table} t Table to get counted. | ||
+ | @return {number} Number of elements in the table. | ||
+ | ]] | ||
function U.count( t ) | function U.count( t ) | ||
local counter = 0; | local counter = 0; | ||
Line 58: | Line 95: | ||
end | end | ||
− | -- @ | + | --[[Doc |
− | + | @function U link | |
+ | @description Creates a wikitext link. | ||
+ | @parameter {string} page Page name to link. | ||
+ | @parameter {string|nil} label Label for the link. If unspecified, | ||
+ | the label used will be `page` with its dab removed. | ||
+ | @return {string} Wikilink. | ||
+ | ]] | ||
function U.link( page, label ) | function U.link( page, label ) | ||
return ('[[%s|%s]]'):format( | return ('[[%s|%s]]'):format( | ||
Line 67: | Line 110: | ||
end | end | ||
− | -- @ | + | --[[Doc |
− | + | @function U getDab | |
+ | @description Gets the dab text of a title, if it has dab. | ||
+ | @parameter {string} title Page title to get the dab from. | ||
+ | @return {string} Dab for `title`. | ||
+ | ]] | ||
function U.getDab( title ) | function U.getDab( title ) | ||
return title:match( '%(([^%(]*)%)%s*$' ) or ''; | return title:match( '%(([^%(]*)%)%s*$' ) or ''; | ||
end | end | ||
− | -- @ | + | --[[Doc |
− | + | @function U removeDab | |
+ | @description Removes the dab text of a title. | ||
+ | @parameter {string} title Page title to get its dab removed. | ||
+ | @return {string} `title` with its dab removed. | ||
+ | ]] | ||
function U.removeDab( title ) | function U.removeDab( title ) | ||
return title:gsub( '%s*%(([^%(]*)%)%s*$', '' ); | return title:gsub( '%s*%(([^%(]*)%)%s*$', '' ); | ||
end | end | ||
− | -- @ | + | --[[Doc |
− | + | @function isSomething | |
+ | @description Meta-function for type checkers. | ||
+ | @parameter {*} toCompare Anything to type-compare. | ||
+ | @parameter {*} compareTo Specific thing to be type-compared with. | ||
+ | @return {boolean} If `toCompare` and `compareTo` have the same type. | ||
+ | ]] | ||
local function isSomething( toCompare, compareTo ) | local function isSomething( toCompare, compareTo ) | ||
return type( toCompare ) == type( compareTo ); | return type( toCompare ) == type( compareTo ); | ||
end | end | ||
− | -- @ | + | --[=[Doc |
+ | @function U isBoolean | ||
+ | @description Checks if it's a `boolean` type. | ||
+ | @parameter {*} v Any value to check if it's a `boolean`. | ||
+ | @return {boolean} If `v` type is `boolean`. | ||
+ | @see [[#isSomething]] | ||
+ | ]=] | ||
function U.isBoolean( v ) | function U.isBoolean( v ) | ||
return isSomething( v, true ); | return isSomething( v, true ); | ||
end | end | ||
− | -- @ | + | --[=[Doc |
+ | @function U isFunction | ||
+ | @description Checks if it's a `function` type. | ||
+ | @parameter {*} v Any value to check if it's a `function`. | ||
+ | @return {boolean} If `v` type is `function`. | ||
+ | @see [[#isSomething]] | ||
+ | ]=] | ||
function U.isFunction( v ) | function U.isFunction( v ) | ||
return isSomething( v, function() end ); | return isSomething( v, function() end ); | ||
end | end | ||
− | -- @ | + | --[=[Doc |
+ | @function U isNil | ||
+ | @description Checks if it's `nil`. | ||
+ | @parameter {*} v Any value to check if it's `nil`. | ||
+ | @return {boolean} If `v` type `nil`. | ||
+ | @see [[#isSomething]] | ||
+ | ]=] | ||
function U.isNil( v ) | function U.isNil( v ) | ||
return isSomething( v, nil ); | return isSomething( v, nil ); | ||
end | end | ||
− | -- @ | + | --[=[Doc |
+ | @function U isNumber | ||
+ | @description Checks if it's a `number` type. | ||
+ | @parameter {*} v Any value to check if it's a `number`. | ||
+ | @return {boolean} If `v` type is `number`. | ||
+ | @see [[#isSomething]] | ||
+ | ]=] | ||
function U.isNumber( v ) | function U.isNumber( v ) | ||
return isSomething( v, 1 ); | return isSomething( v, 1 ); | ||
end | end | ||
− | -- @ | + | --[=[Doc |
+ | @function U isString | ||
+ | @description Checks if it's a `string` type. | ||
+ | @parameter {*} v Any value to check if it's a `string`. | ||
+ | @return {boolean} If `v` type is `string`. | ||
+ | @see [[#isSomething]] | ||
+ | ]=] | ||
function U.isString( v ) | function U.isString( v ) | ||
return isSomething( v, '' ); | return isSomething( v, '' ); | ||
end | end | ||
− | -- @ | + | --[=[Doc |
+ | @function U isTable | ||
+ | @description Checks if it's a `table` type. | ||
+ | @parameter {*} v Any value to check if it's a `table`. | ||
+ | @return {boolean} If `v` type is `table`. | ||
+ | @see [[#isSomething]] | ||
+ | ]=] | ||
function U.isTable( v ) | function U.isTable( v ) | ||
return isSomething( v, {} ); | return isSomething( v, {} ); | ||
end | end | ||
− | -- @ | + | --[[Doc |
+ | @function U isEmpty | ||
+ | @description Checks if it's a empty. | ||
+ | @parameter {*} v Any value to check if it's empty. | ||
+ | @return {boolean} If `v` type is empty. | ||
+ | @todo Keep this? Check dependencies. | ||
+ | ]] | ||
function U.isEmpty( v ) | function U.isEmpty( v ) | ||
return ( | return ( | ||
Line 137: | Line 235: | ||
end--]] | end--]] | ||
− | -- @ | + | --[[Doc |
− | + | @function U wrapInQuotes | |
+ | @description Wraps a name in quotes, based on the language. | ||
+ | @parameter {string|nil} name A name to wrap in quotes. | ||
+ | @parameter {string} ln A language index. | ||
+ | @return {string} Wrapped `name`. If `name` is `nil`, returns the empty string. | ||
+ | @todo Accept `ln` as a language struct. | ||
+ | ]] | ||
function U.wrapInQuotes( name, ln ) | function U.wrapInQuotes( name, ln ) | ||
if not UTIL.trim( name ) then | if not UTIL.trim( name ) then | ||
Line 156: | Line 260: | ||
-- @description Parses arguments. | -- @description Parses arguments. | ||
-- @see [[Module:Arguments]] | -- @see [[Module:Arguments]] | ||
− | |||
function U.getArgs( ... ) | function U.getArgs( ... ) | ||
− | + | return require( 'Module:Arguments' ).getArgs( ... ); | |
− | |||
end | end | ||
Line 165: | Line 267: | ||
-- @description Gets the localized name of a card, set or character. | -- @description Gets the localized name of a card, set or character. | ||
-- @see [[Module:Name]] | -- @see [[Module:Name]] | ||
− | |||
function U.getName( ... ) | function U.getName( ... ) | ||
− | + | return require( 'Module:Name' ).main( ... ); | |
− | |||
end | end | ||
Line 174: | Line 274: | ||
-- @description Gets the localized name of a card, set or character. | -- @description Gets the localized name of a card, set or character. | ||
-- @see [[Module:Name]] | -- @see [[Module:Name]] | ||
− | |||
function U.getImgName( ... ) | function U.getImgName( ... ) | ||
− | + | return require( 'Module:Card image name' ).main( ... ); | |
− | |||
end | end | ||
Line 183: | Line 281: | ||
-- @description | -- @description | ||
-- @see [[Module:Info class]] | -- @see [[Module:Info class]] | ||
− | |||
function U.newInfoObject( title ) | function U.newInfoObject( title ) | ||
− | + | return require( 'Module:Info class' ).new( title ); | |
− | |||
end | end | ||
Line 192: | Line 288: | ||
-- @description | -- @description | ||
-- @see [[Module:StringBuffer]] | -- @see [[Module:StringBuffer]] | ||
− | |||
function U.newStringBuffer() | function U.newStringBuffer() | ||
− | + | return require( 'Module:StringBuffer' ).new(); | |
− | |||
end | end | ||
Line 201: | Line 295: | ||
-- Return: | -- Return: | ||
---------- | ---------- | ||
+ | --[[Doc | ||
+ | @exports Util library (`U`). | ||
+ | ]] | ||
return U; | return U; | ||
-- </pre> | -- </pre> |
Revision as of 23:36, 12 October 2018
-- <pre>
--[=[Doc
@module Util
@description Holds commonly used simple functions.
@author [[User:Becasita]]
@contact [[User talk:Becasita]]
@todo Remove those last functions to a dedicated module
or simply remove them.
]=]
-------------------
-- Export variable:
-------------------
--[[Doc
@data U
@description Variable to hold the library to be exported.
@exportable
]]
local U = {};
-------------
-- Functions:
-------------
-- mw functions:
local mwTextTrim = mw.text.trim;
--[[Doc
@function U bold
@description Renders bold wikitext markup.
@parameter {string} s String to make bold.
@return {string} Bold formatted `s`.
@todo Escape ' ?
]]
function U.bold( s )
return ("'''%s'''"):format( s );
end
--[[Doc
@function U italic
@description Renders italic wikitext markup.
@parameter {string} s String to italicize.
@return {string} Italicized `s`.
@todo Escape ' ?
]]
function U.italic( s )
return ("''%s''"):format( s );
end
--[=[Doc
@function U italicNoDab
@description Renders italics wikitext markup, except for the dab.
Also normalizes the space between the dab and the rest.
@parameter {string} s String to italicize, except its dab.
@return {string} Italicized `s`, except its dab.
@see [[#U.getDab]]
@see [[#U.removeDab]]
]=]
function U.italicNoDab( s )
local dab = U.getDab( s );
local noDab = U.removeDab( s );
return table.concat( {
("''%s''"):format( noDab ),
dab ~= '' and dab or nil
}, ' ' );
end
--[=[Doc
@function U trim
@description Trims white space from front and tail of string.
Returns nil if only whitespace. Also normalizes the space between
the dab and the rest.
@parameter {string|nil} s String to trim.
@return {string|nil} Trimmed `s`. If `s` ends up being only whitespace
or `s` is `nil`, it returns `nil`.
@see [[mw:Extension:Scribunto/Lua reference manual#mw.text.trim]]
]=]
function U.trim( s )
if s and not s:match( '^%s*$' ) then
return mwTextTrim( s );
end
end
--[[Doc
@function U count
@description Counts the number of elements in a table.
@parameter {table} t Table to get counted.
@return {number} Number of elements in the table.
]]
function U.count( t )
local counter = 0;
for key, value in pairs( t ) do
counter = counter + 1;
end
return counter;
end
--[[Doc
@function U link
@description Creates a wikitext link.
@parameter {string} page Page name to link.
@parameter {string|nil} label Label for the link. If unspecified,
the label used will be `page` with its dab removed.
@return {string} Wikilink.
]]
function U.link( page, label )
return ('[[%s|%s]]'):format(
page:gsub( '#', '' ),
label or U.removeDab( page )
);
end
--[[Doc
@function U getDab
@description Gets the dab text of a title, if it has dab.
@parameter {string} title Page title to get the dab from.
@return {string} Dab for `title`.
]]
function U.getDab( title )
return title:match( '%(([^%(]*)%)%s*$' ) or '';
end
--[[Doc
@function U removeDab
@description Removes the dab text of a title.
@parameter {string} title Page title to get its dab removed.
@return {string} `title` with its dab removed.
]]
function U.removeDab( title )
return title:gsub( '%s*%(([^%(]*)%)%s*$', '' );
end
--[[Doc
@function isSomething
@description Meta-function for type checkers.
@parameter {*} toCompare Anything to type-compare.
@parameter {*} compareTo Specific thing to be type-compared with.
@return {boolean} If `toCompare` and `compareTo` have the same type.
]]
local function isSomething( toCompare, compareTo )
return type( toCompare ) == type( compareTo );
end
--[=[Doc
@function U isBoolean
@description Checks if it's a `boolean` type.
@parameter {*} v Any value to check if it's a `boolean`.
@return {boolean} If `v` type is `boolean`.
@see [[#isSomething]]
]=]
function U.isBoolean( v )
return isSomething( v, true );
end
--[=[Doc
@function U isFunction
@description Checks if it's a `function` type.
@parameter {*} v Any value to check if it's a `function`.
@return {boolean} If `v` type is `function`.
@see [[#isSomething]]
]=]
function U.isFunction( v )
return isSomething( v, function() end );
end
--[=[Doc
@function U isNil
@description Checks if it's `nil`.
@parameter {*} v Any value to check if it's `nil`.
@return {boolean} If `v` type `nil`.
@see [[#isSomething]]
]=]
function U.isNil( v )
return isSomething( v, nil );
end
--[=[Doc
@function U isNumber
@description Checks if it's a `number` type.
@parameter {*} v Any value to check if it's a `number`.
@return {boolean} If `v` type is `number`.
@see [[#isSomething]]
]=]
function U.isNumber( v )
return isSomething( v, 1 );
end
--[=[Doc
@function U isString
@description Checks if it's a `string` type.
@parameter {*} v Any value to check if it's a `string`.
@return {boolean} If `v` type is `string`.
@see [[#isSomething]]
]=]
function U.isString( v )
return isSomething( v, '' );
end
--[=[Doc
@function U isTable
@description Checks if it's a `table` type.
@parameter {*} v Any value to check if it's a `table`.
@return {boolean} If `v` type is `table`.
@see [[#isSomething]]
]=]
function U.isTable( v )
return isSomething( v, {} );
end
--[[Doc
@function U isEmpty
@description Checks if it's a empty.
@parameter {*} v Any value to check if it's empty.
@return {boolean} If `v` type is empty.
@todo Keep this? Check dependencies.
]]
function U.isEmpty( v )
return (
U.isString( v ) and mwTextTrim( v ) == ''
or
U.isTable( v ) and U.count( v ) == 0
);
end
-- @name validate
-- @description Asserts if a value has content.
--[[function U.validate( v )
-- If boolean, function or nil, just return them:
if U.isBoolean( v ) or U.isFunction( v ) or U.isNil( v ) then return v end
-- If number, it is accepted if it's not 0:
if U.isNumber( v ) then return v ~= 0 and v end
-- If string, it is accepted if it's not the empty string:
if U.isString( v ) then return mwTextTrim( v ) ~= '' and v end
-- If table, it is accepted if it has elements:
if U.isTable( v ) then return U.count( v ) ~= 0 and v end
end--]]
--[[Doc
@function U wrapInQuotes
@description Wraps a name in quotes, based on the language.
@parameter {string|nil} name A name to wrap in quotes.
@parameter {string} ln A language index.
@return {string} Wrapped `name`. If `name` is `nil`, returns the empty string.
@todo Accept `ln` as a language struct.
]]
function U.wrapInQuotes( name, ln )
if not UTIL.trim( name ) then
return ''; -- Return empty string.
end
return (ln ~= 'ja' and ln ~= 'zh')
and table.concat( { '"', name, '"' } )
or table.concat( { '「', name, '」' } )
;
end
--[[function U.processArgs( frame, ... )
return
end]]
-- @name getArgs
-- @description Parses arguments.
-- @see [[Module:Arguments]]
function U.getArgs( ... )
return require( 'Module:Arguments' ).getArgs( ... );
end
-- @name getName
-- @description Gets the localized name of a card, set or character.
-- @see [[Module:Name]]
function U.getName( ... )
return require( 'Module:Name' ).main( ... );
end
-- @name getImgName
-- @description Gets the localized name of a card, set or character.
-- @see [[Module:Name]]
function U.getImgName( ... )
return require( 'Module:Card image name' ).main( ... );
end
-- @name newInfoObject
-- @description
-- @see [[Module:Info class]]
function U.newInfoObject( title )
return require( 'Module:Info class' ).new( title );
end
-- @name newStringBuffer
-- @description
-- @see [[Module:StringBuffer]]
function U.newStringBuffer()
return require( 'Module:StringBuffer' ).new();
end
----------
-- Return:
----------
--[[Doc
@exports Util library (`U`).
]]
return U;
-- </pre>