Modul:TemplatePar

--[=[ TemplatePar 2013-05-05 Template parameter utility

• check
• count
• valid
• TemplatePar()

]=]

-- Module globals local TemplatePar = { } local messagePrefix = "lua-module-TemplatePar-" local l10nDef = {} l10nDef[ "en" ] = {

   badPattern  = "#invoke:TemplatePar * pattern syntax error",
   dupOpt      = "#invoke:TemplatePar * repeated optional parameter",
   dupRule     = "#invoke:TemplatePar * parameter conflict key/pattern",
   empty       = "Error in template: undefined value for mandatory",
   invalid     = "Error in template: invalid parameter",
   invalidPar  = "#invoke:TemplatePar * invalid parameter",
   minmax      = "#invoke:TemplatePar * min > max",
   noname      = "#invoke:TemplatePar * missing parameter name",
   tooLong     = "Error in template: parameter too long",
   tooShort    = "Error in template: parameter too short",
   undefined   = "Error in template: mandatory parameter missing",
   unknown     = "Error in template: unknown parameter name",
   unknownRule = "#invoke:TemplatePar * unknown rule"

} l10nDef[ "de" ] = {

   badPattern  = "#invoke:TemplatePar * Syntaxfehler des pattern",
   dupOpt      = "#invoke:TemplatePar * Optionsparameter wiederholt",
   dupRule     = "#invoke:TemplatePar * Parameterkonflikt key/pattern",
   empty       = "Fehler bei Vorlage: Pflichtparameter ohne Wert",
   invalid     = "Fehler bei Vorlage: Parameter ungültig",
   invalidPar  = "#invoke:TemplatePar * Ungültiger Parameter",
   minmax      = "#invoke:TemplatePar * min > max",
   noname      = "#invoke:TemplatePar * Parametername nicht angegeben",
   tooLong     = "Fehler bei Vorlage: Parameter zu lang",
   tooShort    = "Fehler bei Vorlage: Parameter zu kurz",
   undefined   = "Fehler bei Vorlage: Pflichtparameter fehlt",
   unknown     = "Fehler bei Vorlage: Parametername unbekannt",
   unknownRule = "#invoke:TemplatePar * Unbekannte Regel"

} local Patterns = {

   [ "ASCII" ]   = "^[ -~]*$",
   [ "ASCII+" ]  = "^[ -~]+$",
   [ "ASCII+1" ] = "^[!-~]+$",
   [ "n" ]       = "^%-?[0-9]*$",
   [ "n>0" ]     = "^[0-9]*[1-9][0-9]*$",
   [ "N+" ]      = "^%-?[1-9][0-9]*$",
   [ "N>0" ]     = "^[1-9][0-9]*$",
   [ "x" ]       = "^[0-9A-Fa-f]*$",
   [ "x+" ]      = "^[0-9A-Fa-f]+$",
   [ "X" ]       = "^[0-9A-F]*$",
   [ "X+" ]      = "^[0-9A-F]+$",
   [ "0,0" ]     = "^%-?[0-9]*,?[0-9]*$",
   [ "0,0+" ]    = "^%-?[0-9]+,[0-9]+$",
   [ "0,0+?" ]   = "^%-?[0-9]+,?[0-9]*$",
   [ "0.0" ]     = "^%-?[0-9]*%.?[0-9]*$",
   [ "0.0+" ]    = "^%-?[0-9]+%.[0-9]+$",
   [ "0.0+?" ]   = "^%-?[0-9]+%.?[0-9]*$",
   [ ".0+" ]     = "^%-?[0-9]*%.?[0-9]+$",
   [ "ID" ]      = "^[A-Za-z]?[A-Za-z_0-9]*$",
   [ "ID+" ]     = "^[A-Za-z][A-Za-z_0-9]*$",
   [ "ABC" ]     = "^[A-Z]*$",
   [ "ABC+" ]    = "^[A-Z]+$",
   [ "Abc" ]     = "^[A-Z]*[a-z]*$",
   [ "Abc+" ]    = "^[A-Z][a-z]+$",
   [ "abc" ]     = "^[a-z]*$",
   [ "abc+" ]    = "^[a-z]+$",
   [ "aBc+" ]    = "^[a-z]+[A-Z][A-Za-z]*$",
   [ "base64" ]  = "^[A-Za-z0-9%+/]*$",
   [ "base64+" ] = "^[A-Za-z0-9%+/]+$",
   [ "+" ]       = "%S"

}

function trim( s )

   -- Trim string
   -- Precondition:
   --     s  -- string or nil; to be trimmed
   -- Postcondition:
   --     Return trimmed string or nil
   local r = s
   if type( s ) == "string" then
       if s:match( "^%s*$" ) then
           r = ""
       else
           r = s:match( "^%s*(%S.*)$" )
           r = r:match( "^(.*%S)%s*$" )
       end
   end
   return r

end -- trim()

local function factory( say )

   -- Retrieve localized message string in content language
   -- Precondition:
   --     say  -- string; message ID
   -- Postcondition:
   --     Return some message string
   -- Uses:
   --     >  messagePrefix
   --     >  l10nDef
   --     mw.language.getContentLanguage()
   --     mw.message.new()
   local c = mw.language.getContentLanguage():getCode()
   local m = mw.message.new( messagePrefix .. say )
   local r = false
   if m:isBlank() then
       local l10n = l10nDef[ c ]
       if not l10n then
           l10n = l10nDef[ "en" ]
       end
       r = l10n[ say ]
   else
       m:inLanguage( c )
       r = m:plain()
   end
   if not r then
       r = "(((".. say .. ")))"
   end
   return r

end -- factory()

local function failsafe( story, scan )

   -- Test for match (possibly user-defined with synrax error)
   -- Precondition:
   --     story  -- string; parameter value
   --     scan   -- string; pattern
   -- Postcondition:
   --     Return nil, if not matching, else non-nil
   -- Uses:
   --     mw.ustring.match()
   return  mw.ustring.match( story, scan )

end -- failsafe()

local function failure( spec, suspect, options )

   -- Submit localized error message
   -- Precondition:
   --     spec     -- string; message ID
   --     suspect  -- string or nil; additional information
   --     options  -- table or nil; optional details
   --                 options.template
   -- Postcondition:
   --     Return string
   -- Uses:
   --     factory()
   local r = factory( spec )
   if type( options ) == "table" then
       if type( options.template ) == "string" then
           if #options.template > 0 then
               r = r .. " (" .. options.template .. ")"
           end
       end
   end
   if suspect then
       r = r .. " " .. suspect
   end
   return r

end -- failure()

local function fault( store, key )

   -- Add key to collection string and insert separator
   -- Precondition:
   --     store  -- string or nil or false; collection string
   --     key    -- string or number; to be appended
   -- Postcondition:
   --    Return string; extended
   local r
   local s
   if type( key ) == "number" then
       s = tostring( key )
   else
       s = key
   end
   if store then
       r = store .. "; " .. s
   else
       r = s
   end
   return r

end -- fault()

local function fed( haystack, needle )

   -- Find needle in haystack map
   -- Precondition:
   --     haystack  -- table; map of key values
   --     needle    -- any; identifier
   -- Postcondition:
   --    Return true iff found
   local k, v
   for k, v in pairs( haystack ) do
       if k == needle then
           return true
       end
   end -- for k, v
   return false

end -- fed()

local function fetch()

   -- Return regular table with all template transclusion parameters
   -- Postcondition:
   --    Return table; whitespace-only values as false
   -- Uses:
   --     mw.getCurrentFrame()
   --     frame:getParent()
   local k, v
   local r = { }
   local t = mw.getCurrentFrame():getParent()
   local o = t.args
   for k, v in pairs( o ) do
       if type( v ) == "string" then
           if v:match( "^%s*$" ) then
               v = false
           end
       else
           v = false
       end
       if type( k ) == "number" then
           k = tostring( k )
       end
       r[ k ] = v
   end -- for k, v
   return r

end -- fetch()

local function fill( specified )

   -- Split requirement string separated by '='
   -- Precondition:
   --     specified  -- string or nil; requested parameter set
   -- Postcondition:
   --    Return sequence table
   -- Uses:
   --     mw.text.split()
   local r
   if specified then
       local i, s
       r = mw.text.split( specified, "%s*=%s*" )
       for i = #r, 1, -1 do
           s = r[ i ]
           if #s == 0 then
               table.remove( r, i )
           end
       end -- for i, -1
   else
       r = { }
   end
   return r

end -- fill()

local function finalize( submit, options )

   -- Finalize message
   -- Precondition:
   --     submit   -- string or false or nil; non-empty error message
   --     options  -- table or nil; optional details
   --                 options.noError
   --                 options.cat
   --                 options.template
   -- Postcondition:
   --     Return string or false
   local r = false
   if submit then
       local opt, s
       if type( options ) == "table" then
           opt = options
       else
           opt = { }
       end
       if opt.noError then
           r = false
       else
           r = ""
       end
       s = opt.cat
       if type( s ) == "string" then
           if not r then
              r = ""
           end
           if s:find( "@@@" ) then
               if type( opt.template ) == "string" then
                   s = s:gsub( "@@@", opt.template )
               end
           end
           r = r .. ""
       end
   end
   return r

end -- finalize()

local function finder( haystack, needle )

   -- Find needle in haystack sequence
   -- Precondition:
   --     haystack  -- table; sequence of key names
   --     needle    -- any; key name
   -- Postcondition:
   --    Return true iff found
   local i
   for i = 1, #haystack do
       if haystack[ i ] == needle then
           return true
       end
   end -- for i
   return false

end -- finder()

local function fit( base, extend )

   -- Merge two tables, create new sequence if both not empty
   -- Precondition:
   --     base    -- table; sequence kept unchanged
   --     extend  -- table; sequence to be appended
   -- Postcondition:
   --     Return merged table, or message string if duplicated entries
   -- Uses:
   --     finder()
   --     fault()
   local r
   if #base == 0 then
       if #extend == 0 then
           r = { }
       else
           r = extend
       end
   else
       if #extend == 0 then
           r = base
       else
           local i, s
           r = false
           for i = 1, #extend do
               s = extend[ i ]
               if finder( base, s ) then
                   r = fault( r, s )
               end
           end -- for i
           if not r then
               r = { }
               for i = 1, #base do
                   table.insert( r, base[ i ] )
               end -- for i
               for i = 1, #extend do
                   table.insert( r, extend[ i ] )
               end -- for i
           end
       end
   end
   return r

end -- fit()

local function fix( valid, duty, options )

   -- Perform transclusion parameter analysis
   -- Precondition:
   --     valid    -- table; unique sequence of known parameters
   --     duty     -- table; sequence of mandatory parameters
   --     options  -- table or nil; optional details
   -- Postcondition:
   --     Return string as configured; empty if valid
   -- Uses:
   --     fetch()
   --     finder()
   --     fault()
   --     failure()
   --     fed()
   local k, v
   local r   = false
   local got = fetch()
   for k, v in pairs( got ) do
       if not finder( valid, k ) then
           r = fault( r, k )
       end
   end -- for k, v
   if r then
       r = failure( "unknown", r, options )
   else -- all names valid
       local i, s
       for i = 1, #duty do
           s = duty[ i ]
           if not fed( got, s ) then
               r = fault( r, s )
           end
       end -- for i
       if r then
           r = failure( "undefined", r, options )
       else -- all mandatory present
           for i = 1, #duty do
               s = duty[ i ]
               if not got[ s ] then
                   r = fault( r, s )
               end
           end -- for i
           if r then
               r = failure( "empty", r, options )
           end
       end
   end
   return r

end -- fix()

local function format( seek, options )

   -- Check validity of one particular template parameter
   -- Precondition:
   --     seek     -- string non-empty; name of template parameter
   --     options  -- table or nil; optional details
   --                 options.pattern
   --                 options.key
   --                 options.min
   --                 options.max
   -- Postcondition:
   --     Return string with error message as configured;
   --            false if valid or no answer permitted
   -- Uses:
   --     >  Patterns
   --     mw.getCurrentFrame()()
   --     frame:getParent()
   --     failure()
   --     failsafe()
   local r = false
   local s
   local scan  = false
   local story = mw.getCurrentFrame():getParent()
   story = ( story.args[ seek ] or "" )
   if type( options.pattern ) == "string" then
       if options.key then
           r = failure( "dupRule", false, options )
       else
           scan = options.pattern
       end
   else
       if type( options.key ) == "string" then
           s = trim( options.key )
       else
           s = "+"
       end
       scan = Patterns[ s ]
       if type( scan ) == "string" then
           if s == "n" or s == "0,0" or s == "0.0" then
              if not story:match( "[0-9]" ) then
                   scan = false
                   r    = failure( "invalid",
                                   "'" .. seek .. "'",
                                   options )
               end
           end
       else
           r = failure( "unknownRule", s, options )
       end
   end
   if scan then
       local legal, got = pcall( failsafe, story, scan )
       if legal then
           if not got then
               r = failure( "invalid",  "'" .. seek .. "'",  options )
           end
       else
           r = failure( "badPattern",
                        scan .. " *** " .. got,
                        options )
       end
   end
   if options.min  and  not r then
       if type( options.min ) == "number" then
           if type( options.max ) == "number" then
               if options.max < options.min then
                   r = failure( "minmax",
                                tostring( options.min )
                                .. " > " ..
                                tostring( options.max ),
                                options )
               end
           end
           if #story < options.min  and  not r then
               r = failure( "tooShort",
                            " <" .. options.min .. " '" .. seek .. "'",
                            options )
           end
       else
           r = failure( "invalidPar", "min", options )
       end
   end
   if options.max  and  not r then
       if type( options.max ) == "number" then
           if #story > options.max then
               r = failure( "tooLong",
                            " >" .. options.max .. " '" .. seek .. "'",
                            options )
           end
       else
           r = failure( "invalidPar", "max", options )
       end
   end
   return r

end -- format()

TemplatePar.check = function ( options )

   -- Run parameter analysis
   -- Precondition:
   --     options  -- table or nil; optional details
   --                 options.mandatory
   --                 options.optional
   -- Postcondition:
   --     Return string with error message as configured;
   --            false if valid or no answer permitted
   -- Uses:
   --     fit()
   --     failure()
   --     fix()
   --     finalize()
   local duty, r
   if type( options ) == "table" then
       if type( options.mandatory ) == "table" then
           duty = options.mandatory
       else
           duty = { }
       end
       if type( options.optional ) ~= "table" then
           options.optional = { }
       end
       r = fit( duty, options.optional )
   else
       duty = { }
       r    = { }
   end
   if type( r ) == "string" then
       r = failure( "dupOpt", r, options )
   else
       r = fix( r, duty, options )
   end
   return finalize( r, options )

end -- TemplatePar.check()

TemplatePar.count = function ()

   -- Return number of template parameters
   -- Postcondition:
   --    Return number, starting at 0
   -- Uses:
   --     mw.getCurrentFrame()
   --     frame:getParent()
   local k, v
   local r = 0
   local t = mw.getCurrentFrame():getParent()
   local o = t.args
   for k, v in pairs( o ) do
       r = r + 1
   end -- for k, v
   return r

end -- TemplatePar.count()

TemplatePar.valid = function ( seek, options )

   -- Check validity of one particular template parameter
   -- Precondition:
   --     seek     -- string; name of template parameter
   --     options  -- table or nil; optional details
   -- Postcondition:
   --     Return string with error message as configured;
   --            false if valid or no answer permitted
   -- Uses:
   --     trim()
   --     format()
   --     failure()
   --     finalize()
   local r
   if type( seek ) == "string" then
       r = trim( seek )
       if #r == 0 then
           r = false
       end
   end
   if r then
       r = format( seek, options )
   else
       r = failure( "noname", false, options )
   end
   return finalize( r, options )

end -- TemplatePar.valid()

-- Provide external access local p = {}

function p.check( frame )

   -- Check validity of template parameters
   -- Precondition:
   --     frame  -- object; #invoke environment
   -- Postcondition:
   --     Return string with error message or ""
   -- Uses:
   --     fill()
   --     TemplatePar.check()
   local options = { mandatory = fill( frame.args[ 1 ] ),
                     optional  = fill( frame.args[ 2 ] ),
                     cat       = frame.args.cat,
                     noError   = frame.args.noError,
                     template  = frame.args.template
                   }
   return TemplatePar.check( options ) or ""

end -- .check()

function p.count( frame )

   -- Count number of template parameters
   -- Postcondition:
   --     Return string with digits including "0"
   -- Uses:
   --     TemplatePar.count()
   return tostring( TemplatePar.count() )

end -- .count()

function p.valid( frame )

   -- Check validity of one particular template parameter
   -- Precondition:
   --     frame  -- object; #invoke environment
   -- Postcondition:
   --     Return string with error message or ""
   -- Uses:
   --     trim()
   --     mw.ustring.gsub()
   --     TemplatePar.valid()
   local r = false
   local s
   local options = { cat      = frame.args.cat,
                     noError  = frame.args.noError,
                     template = frame.args.template
                   }
   s = trim( frame.args[ 2 ] )
   if type( s ) == "string" then
       local sub = s:match( "^/(.*%S)/$" )
       if type( sub ) == "string" then
           sub = sub:gsub( "%%!", "|" )
           sub = sub:gsub( "%%%(%(", "{{" )
           sub = sub:gsub( "%%%)%)", "}}" )
           options.pattern = sub
       else
           options.key = s
       end
   end
   if type( frame.args.min ) == "string" then
       s = frame.args.min:match( "^%s*([0-9]+)%s*$" )
       if s then
           options.min = tonumber( s )
       else
           r = failure( "invalidPar",
                        "min=" .. frame.args.min,
                        options )
       end
   end
   if type( frame.args.max ) == "string" then
       s = frame.args.max:match( "^%s*([1-9][0-9]*)%s*$" )
       if s then
           options.max = tonumber( s )
       else
           r = failure( "invalidPar",
                        "max=" .. frame.args.max,
                        options )
       end
   end
   if r then
       r = finalize( r, options )
   else
       s = frame.args[ 1 ] or ""
       r = TemplatePar.valid( s, options ) or ""
   end
   return r

end -- .valid()

function p.TemplatePar()

   -- Retrieve function access for modules
   -- Postcondition:
   --     Return table with functions
   return TemplatePar

end -- .TemplatePar()

return p