User:AnomieBOT/source/d/WikiProjectTagging.pm/doc

NAME

d::WikiProjectTagging - AnomieBOT decorator for WikiProject tagging

SYNOPSIS

 use AnomieBOT::API;
 
 $api = new AnomieBOT::API('conf.ini', 1);
 $api->decorators(qw/d::WikiProjectTagging/);

DESCRIPTION

d::WikiProjectTagging contains functions for manipulating the WikiProject banners on a talk page. When "d::WikiProjectTagging" is used as a decorator on the API object, the following methods are available.

Also, all the methods provided by d::Templates and d::Redirects are available, as they are used internally.

CALLBACKS

Several functions in this module take callback functions. In all cases, these callbacks are called with the following parameters:

$banner: Name of the banner.
$name: Name of the banner template used in the page.
$oname: The original name of the banner template as specified in the wikitext, including any leading or trailing whitespace.
$params: Array reference containing all the banner's parameters.
$wikitext: The raw wikitext of the banner.
$new: A boolean indicating whether the banner is being added to the page.

In cases where output text is being constructed, the callback may return any string to replace the original banner wikitext in the output; in all other cases, it should return undef.

BANNER DESCRIPTORS

In order to properly assess an article, a descriptor must be loaded for each banner to be assessed (using the WPBconfig function). The descriptor is a hash with the following properties:

ns

This is a hash mapping assessments to the appropriate "class" and "importance" parameters. The keys are the assessments as returned by WPBassess, and the values are 4-element arrays:

0: If defined, the "class" parameter to apply.
1: If defined and the banner already has a "class" parameter, the class will not be changed if it matches this regular expression. For example, setting qr/\S.*/s will only apply the class assessment if the banner has no class parameter or the class parameter is empty.
2: If defined, the "importance" parameter to apply.
3: The same as element index 1 for the "importance" parameter.

stubauto: If the banner supports "auto=yes" or the like to indicate that the stub assessment was automatically applied, specify the parameter and value here.
blp: If this is defined and the banner has a pattern matching this regex, "blp=yes" will be added by WPBfixshell. For example, {{WikiProject Biography}} would specify qr/^\s*living\s*=\s*+(?!(?i)no|n|0|$|¬)/ here.
blpo: If this is defined and the banner has a pattern matching this regex, "blpo=yes" will be added by WPBfixshell. For example, {{WikiProject Biography}} would specify qr/^\s*blpo\s*=\s*+(?!(?i)no|n|0|$|¬)/ here.
activepol: If this is defined and the banner has a pattern matching this regex, "activepol=yes" will be added by WPBfixshell. For example, {{WikiProject Biography}} would specify qr/^\s*activepol\s*=\s*+(?!(?i)no|n|0|$|¬)/ here.
importance: If the banner names its "importance" parameter something other than "importance" (e.g. "priority"), specify that here.
canonicalize: If this is defined, instances of the banner will be renamed to this canonical name.

For banners using {{WPBannerMeta}}, a typical default configuration may be obtained from WPBMetaConfig.

METHODS PROVIDED

$api->WPBMetaConfig( $full, %options ): Returns a typical default configuration for a banner using {{WPBannerMeta}}. $full indictaes whether assessments should be made for the non-article classes available when QUALITY_SCALE=extended is used. Additional options specify values for the non-"ns" options in the descriptor.
$api->WPBconfig( $banner => \%descriptor, ... ): Load banner descriptors for use by WPBassess and WPBfixshell. If you need to unload a descriptor, pass undef.; Note that $banner must be the true name of the banner template (without the Template: prefix), not a redirect.
$api->WPBassess( $title ): Return the assessment for the named page. Technically, this only needs to be called for mainspace pages, as for all other namespaces the assessment is the namespace number.; Possible assessments are "stub", "redirect", "disambig", 0, 2, 4, 6, 8, 10, 12, 14, and 100.; On API query errors, the error hash from $api->query is returned.
$api->WPBmax( $text, @banners )
$api->WPBmin( $text, @banners ): Returns the maximum/minimum class and importance given by the specified WikiProject banners on this page, or all banners if @banners is empty. If a descriptor is loaded for any banner, it is used to detect the "importance" parameter.; Classes considered are: FA, FL, A, GA, B, C, start, stub; Importances considered are: top, high, mid, low; For either assessment, if no banners with the assessment are found the empty string is returned. On API error, the error object is returned (twice).
$api->WPBcheck( $text, @banners )
$api->WPBcheck( $text, $callback, @banners ): $text is the page text whose section 0 should be scanned. $callback is a callback (as defined above) to call for each found banner. The remaining parameters are the (non-redirect, non-prefixed) names of banners to check.; In a scalar context, returns the number of banners found. In a list context, returns a 2-element list consisting of the count and the possibly-modified $text. On error, returns the API error object.
$api->WPBremove( $text, @banners ): $text is the page text whose section 0 should be scanned, and the remaining parameters are the (non-redirect, non-prefixed) names of banners to remove.; On error, returns the API error object. In a scalar context, returns the text with banners removed; in a list context, returns a list with the text removed as the first element and the removed banners' wikitext as the remaining elements.
$api->WPBadd( $text, $assessment, $banner, @params )
$api->WPBadd( $text, $assessment, $callback, $banner, @params ): Adds the banner to the page, or modifies the existing banner if it is already present. If $assessment is not undef, the loaded banner descriptor will be used to assess the banner prior to merging the parameters.; If the banner already exists and no callback is specified, the passed parameters are merged into the existing banner; if a callback is passed, the callback may return appropriately-merged banner text, or undef to merge in the default manner. When the banner does not already exist, the callback is called with parameters already in place so no merging is needed.; Returns the text with the banner added, or an API error object on error.
$api->WPBassessbanners( $text, $assessment, @banners ): $text is the page text whose section 0 should be scanned, and the remaining parameters are the (non-redirect, non-prefixed) names of banners to assess.; On error, returns the API error object. In a scalar context, returns the text with banners assessed; in a list context, returns a list with the text as the first element and the banners' names as the remaining elements.
$api->WPBfixshell( $text )
$api->WPBfixshell( $text, \@log ): This function fixes up any banner shells in section 0 of $text, and returns the fixed text.; At the moment, this renumbers the parameters if necessary, adds blp or activepol if necessary, edits configured banners to remove unneeded "nested=yes" and canonicalize names.; If the optional @log arrayref is provided, the actions performed will be added there.; On error, returns the API error object.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.