צפונות ויקי

יחידה:ParamValidator: הבדלים בין גרסאות בדף

→ העריכה הקודמתהעריכה הבאה ←
dumpkopf
סירוק, פליית כינים, עדכון התיעוד
שורה 1: שורה 1:
--[[
--[[
this unit contains a single function.
this unit contains a single function.
it gets 2 optional parameters:
base = options base name, for the inbuilt options. if not passed, "default" is assumed.
ATM, the only other viable value is "quiet" (without quotes). this is useful when complete substitution of all the outputs is desired.
options = json-coded string that describes the desired output for each error condition, and some more site-specific settings,
such as the default "Documentation" subpage, so the function can try to look for tempaltedata in the correct subpages.
there are several error conditions, and a the options define the desired output for each.
if no output is desired for specific option, give the appropriate key empty string value.
the error conditions are:
* "no-templatedata": no valid tempaltedata was found in tempalte page, or documentation subpage
* "undeclared": parameters with non-empty value, which do not exist in templatedata
* "empty-undeclared": parameters with empty value, which do not exist in templatedata
* "empty-required": parameters marked as "required" in tempaltedata have no value
* "deprecated":  parameters with non-empty value, marked as "deprecated" in tempaltedata
* "any": any of the above conditions is true. deprecated and empty-undeclared will be ignored if corresponding option is null.


for each condition that evaluates to true, the value of the corresponding options field is used to add to the output of the function.
it retrieves the template's templatedata, and uses it to validate the parameters passed to the template.
before appending this value to the output, 2 substitutions occur: the tokens "templatename" and "paramname" in the value are
if any violations found, it returns am appropriate string. this string will typically include some maintenance category, and/or error message.
substituted with the actual template name, and a comma-joined list of the parameters violating the , where relevant.
the operation of the module is controlled by a single parameter passed to it. this string should be valid JSON describing the actions.
the fields of this structure has the following keys, with string or null value:


there is one more useful option:
* "no-templatedata": no valid tempaltedata was found in tempalte page, or documentation subpage
* "doc-subpage": use this field to tell what is the default "Documentation" subpage on your wiki. this enable the system to
* "undeclared": parameters with non-empty value, which do not exist in templatedata
look for tempalatedata in the appropriate subpage.
* "empty-undeclared": parameters with empty value, which do not exist in templatedata
usage:
* "deprecated": parameters with non-empty value, marked as "deprecated" in tempaltedata
place
* "empty-deprecated":  parameters with empty value, marked as "deprecated" in tempaltedata
<includeonly>{{#invoke:ParamValidator | validateParams }}</includeonly>
* "empty-required": parameters marked as "required" in tempaltedata have no value
at the very bigining of the tempalate (not mandatory - it can be in any part of the template, but it's recommended).
* "any": at least one of the above properies has non-empty value, and the corresponding error actually exists.
<includeonly>{{#invoke:ParamValidator | validateParams | base = quiet }}</includeonly>
will use the "quiet" inbuilt option. the default behavior in this case is to only emit a html comment to the page if any error exists.


if any of these error-conditions exists, the value associated with the corresponding key, if not empty, will be appended to the output,
after possibly replacing either one of two tokens:
-- "templatename" is replaced with the actual template name,
-- "paramname" is replaced by a comma-separated list of parameters offending the rule.
if the value of some key is null, it means this error condition will be ignored.


you can pass your own options. these options will be applied above the selected (or default) inbuilt.
in addition, there are several other optional keys of the "options" structure:
the options value is supplied as a json-encoded string. it is recommended to create one or two tempaltes that will return
* "doc-subpage": if supplied, optional subpage to look for tempaltedata definition. typically it's "Documentation", or a translation
the desired options (in valid json format) so the use will be like so:
* "ignore": list of parameter names which will be ignored, both in tempaltedata (for "required" and "deprecated" calculation),
or the template, for "undeclared" calculation


<
typically, this JSON structure will be placed in a special template, and retrieved for the module-use like so:
includeonly>{{#invoke:ParamValidator | validateParams | options = {{validator-options}} }}</includeonly>
<includeonly>{{#invoke:ParamValidatoe | validateParams | options = {{PV Default Values}} }}</includeonly>
use the "default" option as template for the template to be used on your site.
this code is to be placed at the very beginning of the page of the template whose uses are to be validated.
several such options pages may exist, so the user can decide which validation regime to use with each template, by invoking it and passing
the appropriate one for the "options" parameter.


]]
]]
local inbuilt_options = {
['default'] = [=[
{
"no-templatedata": "[[Category:Parametererror invalid templatedata]]",
"undeclared": "[[Category:Parametererror undeclared]][[Category:parameter undeclared templatename]]<p class='paramvalidator-error'>templatename has undeclared parameters: paramname</p>",
"empty-undeclared": "",
"empty-required": "[[Category:Parametererror empty required]][[Category:Parametererror empty equired templatename]]<p class='paramvalidator-error'>templatename misses required parameters: paramname</p>",
"deprecated": "[[Category:Parametererror deprecated]][[Category:Parametererror deprecated templatename]]<p class='paramvalidator-error'>templatename uses deprecated parameters: (paramname)</p>",
"any": "[[Category:Parametererror]]",
"doc-subpage": "Documentation"
}
]=]
,
['cat-only'] = [=[
{
"no-templatedata": "[[Category:Parametererror invalid templatedata]]",
"undeclared": "[[Category:Parametererror undeclared]][[Category:parameter undeclared templatename]]",
"empty-undeclared": "",
"empty-required": "[[Category:Parametererror empty required]][[Category:Parametererror empty equired templatename]]",
"deprecated": "[[Category:Parametererror deprecated]][[Category:Parametererror deprecated templatename]]",
"any": "[[Category:Parametererror]]",
"doc-subpage": "Documentation"
}
]=]
,
['message-only'] = [=[
{
"no-templatedata": "<p class='paramvalidator-error'>Missing tempatedata in templatename</p>",
"undeclared": "<p class='paramvalidator-error'>templatename has undeclared parameters: (paramname)</p>",
"empty-undeclared": "<p class='paramvalidator-error'>templatename has empty undeclared parameters: (paramname)</p>",
"empty-required": "<p class='paramvalidator-error'>templatename misses required parameters: (paramname)</p>",
"deprecated": "<p class='paramvalidator-error'>templatename uses deprecated parameters: (paramname)</p>",
"any": "<p class='paramvalidator-error'>Some errors found in templatename parameters</p>",
"doc-subpage": "Documentation"
}
]=]
,
['comments'] = [=[
{
"no-templatedata": "<!-- Missing tempatedata in templatename -->",
"undeclared": "<!-- templatename has undeclared parameters: (paramname) -->",
"empty-undeclared": "<!-- templatename has empty undeclared parameters: (paramname) -->",
"empty-required": "<!-- templatename misses required parameters: (paramname) -->",
"deprecated": "<!-- templatename uses deprecated parameters: (paramname) -->",
"any": "<!-- Some errors found in templatename parameters -->",
"doc-subpage": "Documentation"
}
]=]
,
quiet = [[
{ "any": "<!-- Some template parameters errors exist, for tempplate templatename -->" }
]]
}


function extract_options( frame )
function extract_options( frame )
local options
local options
local args = frame.args
local args = frame.args
local base = args.base or 'default'
 
local options = not empty( args.options ) and mw.text.jsonDecode( args.options ) or {}
local options = not empty( args.options ) and mw.text.jsonDecode( args.options ) or {}
   
   
local base_options = not empty( inbuilt_options[base] ) and mw.text.jsonDecode( inbuilt_options[base] ) or {}
for k, v in pairs( base_options ) do
options[k] = options[k] or v
end
local n = 1
local n = 1
while not empty( args['options' .. n] ) do
while not empty( args['options' .. n] ) do
שורה 130: שורה 63:


function validateParams( frame )
function validateParams( frame )
local report = ''
local options = extract_options( frame )
local options = extract_options( frame )
local t_frame = frame:getParent()
local t_frame = frame:getParent()
local t_args, template_name = t_frame.args, t_frame:getTitle()
local t_args, template_name = t_frame.args, t_frame:getTitle()
local td_source = build_namelist( options, template_name )
local td_source = build_namelist( options, template_name )
local templatedata = require( 'Module:ReadTd' ).ReadTemplateData( td_source )
local templatedata = require( 'Module:ReadTd' ).ReadTemplateData( td_source )
local td_p = templatedata.params -- now we have options, template args, and td params metadata. we can work now.
local report = ''


local wrapreport = function()
local wrapreport = function()
return not empty( report ) and "<div class = 'paramvalidator-wrapper'>" .. report .. "</div>" or ''
if empty( report ) then return '' end
return ( options['report-prefix'] or "<div class = 'paramvalidator-wrapper'>" )
.. report  
.. ( options['report-suffix'] or "</div>" )
end
end


שורה 176: שורה 113:
return wrapreport() -- from this point on, we know templatedata is valid.
return wrapreport() -- from this point on, we know templatedata is valid.
end
end
local td_p = templatedata.params
-- undeclared and deprecated contains only non-empty parameters.
-- undeclared and deprecated contains only non-empty parameters.
-- empty_undeclared contains undeclared parameters with no value  
-- empty_undeclared contains undeclared parameters with no value  
local undeclared, empty_undeclared, empty_required, deprecated = {}, {}, {}, {}
local undeclared, empty_undeclared, empty_required, deprecated, empty_deprecated = {}, {}, {}, {}, {}
local undec = { [true] = empty_undeclared, [false] = undeclared }
for p_name, value in pairs( t_args ) do
local dep = { [true] = empty_deprecated, [false] = deprecated }
if not td_p[p_name] and not ignore( p_name ) then
 
if empty( value ) then
 
if not empty( options['empty-undeclared'] ) then
-- if paramete does not appear in TD, add it to undeclared or empty-undeclared. if it does appear, 
table.insert( empty_undeclared, p_name )
for p_name, value in pairs( t_args ) do  
end
if not ignore( p_name ) then
else
local noval = empty( value )
table.insert( undeclared, p_name )
if not td_p[p_name] then -- fill undeclared or undeclared_empty, depends on noval
table.insert( undec[noval], p_name )  
elseif td_p[p_name].deprecated then
table.insert( dep[noval], p_name )
end
end
end
end
end
end


שורה 198: שורה 136:
-- and optionally (if options.deprecated exists), use of non-empty deprecated parameters.  
-- and optionally (if options.deprecated exists), use of non-empty deprecated parameters.  
for p_name, param in pairs( td_p ) do
for p_name, param in pairs( td_p ) do
if param.required and empty( t_args[p_name] ) and not ignore( p_name ) then
if not ignore( p_name ) and param.required and empty( t_args[p_name] ) then
table.insert( empty_required, p_name )
table.insert( empty_required, p_name )
end
if options.deprecated and param.deprecated and not empty( t_args[p_name] ) and not ignore( p_name ) then
table.insert( deprecated, p_name )
end
end
end
end
שורה 214: שורה 149:
end
end
if #empty_undeclared ~= 0 then
report_params( 'empty-undeclared', empty_undeclared )
end
if #deprecated ~= 0 then
if #deprecated ~= 0 then
report_params( 'deprecated', deprecated )
report_params( 'deprecated', deprecated )
end
end
if #empty_undeclared ~= 0 then
if #emptyy_deprecated ~= 0 then
report_params( 'empty-undeclared', empty_undeclared )
report_params( 'deprecated', deprecated )
end
end
if #empty_required + #undeclared + #deprecated + #empty_undeclared ~= 0 then
report_params( 'any' )
if not empty( report ) then report_params( 'any' ) end
end
return wrapreport()
return wrapreport()
אוחזר מתוך "https://tzefunotwiki.com/index.php/יחידה:ParamValidator"