 | This module is rated as ready for general use. It has reached a mature form and is thought to be relatively bug-free and ready for use wherever appropriate. It is ready to mention on help pages and other Wikipedia resources as an option for new users to learn. To reduce server load and bad output, it should be improved by sandbox testing rather than repeated trial-and-error editing. |
This is a library for getting information about individual requests for adminship (RfA) and requests for bureaucratship (RfB) pages on the English Wikipedia. It is not meant to be used directly from wiki pages, but rather to be used by other Lua modules.
Creating new objects
First of all, the library must be loaded, like this:
local rfx = require( 'Module:Rfx' )
Once the library is loaded, you can make a new rfx object using rfx.new(). Caution - this function is expensive (see
below).
rfx.new() is used like this:
local myRfx = rfx.new( pagename )
The pagename variable should be the name of a valid RfA or RfB page, for example:
local exampleRfa = rfx.new( 'Wikipedia:Requests for adminship/Example' )
If pagename is not specified, or the page is not a subpage of
Wikipedia:Requests for adminship or
Wikipedia:Requests for bureaucratship, then rfx.new will return nil.
Methods and properties
Once you have created a new rfx object, there are a number of methods and properties that you can use. They are all read-only.
- Properties
type: the type of the rfx. This is either "rfa" or "rfb".supports: the number of supports in the RfX.nilif the supports could not be processed.opposes: the number of opposes in the RfX.nilif the opposes could not be processed.neutrals: the number of neutrals in the RfX.nilif the neutrals could not be processed.percent: the support percentage. Calculated by and rounded to the nearest integer.nilif it could not be processed.endTime: the end time of the RfX. This is a string value taken from the RfX page.nilif it could not be found.user: the username of the RfX candidate.nilif it could not be found.
- Methods
Methods must be called with the colon syntax:
local titleObject = exampleRfa:getTitleObject()
getTitleObject(): gets the title object for the RfX page. See the reference manual for details on how to use title objects.getSupportUsers(): gets an array containing the usernames that supported the RfX. If any usernames could not be processed, the text "Error parsing signature" is used instead, along with the text of the comment in question. N.b. this technique relies on the text of comment text being unique - if it is not unique thendupesExist()will treat the identical comments as duplicate votes. If the page content could not be parsed at all, this method returnsnil.getOpposeUsers(): gets an array containing the usernames that opposed the RfX. Functions similarly togetSupportUsers().getNeutralUsers(): gets an array containing the usernames that were neutral at the RfX. Functions similarly togetSupportUsers().dupesExist(): returns a boolean indicating whether there were any duplicate votes at the RfX. Returnsnilif the vote tables couldn't be processed.getSecondsLeft(): returns the number of seconds left before the RfX is due to close. Once it is due to close, shows zero. If the ending time cannot be found, returnsnil.getTimeLeft(): returns a string showing the time left before the RfX is due to close. The string is in the format "x days, y hours".getReport(): returns a URI object for X!'s RfA Analysis tool at Wikimedia Labs, preloaded with the RfX page.getStatus(): returns a string showing the current status of the RfX. This can be "successful", "unsuccessful", "open", or "pending closure". Returnsnilif the status could not be determined.
You can compare rfx objects with the == operator. This will return true only if the two objects point to the same page. tostring( rfx ) will return prefixedTitle from the RfX page's title object (see the
reference manual).
Expensive functions
This module makes use of the
title:getContent method to fetch RfX page sources. This method will be called for each RfX page being looked up, so each use of rfx.new will count as an
expensive function call. Please be aware that the library may fail for scripts which create many different RfX objects. (The current limit for the English Wikipedia is 500 expensive function calls per page.) Also, each RfX page that is looked up will count as a
transclusion in
Special:WhatLinksHere.
----------------------------------------------------------------------
-- Module:Rfx --
-- This is a library for retrieving information about requests --
-- for adminship and requests for bureaucratship on the English --
-- Wikipedia. Please see the module documentation for instructions. --
----------------------------------------------------------------------
local libraryUtil = require('libraryUtil')
local lang = mw.getContentLanguage()
local textSplit = mw.text.split
local umatch = mw.ustring.match
local newTitle = mw.title.new
local rfx = {}
--------------------------------------
-- Helper functions --
--------------------------------------
local function getTitleObject(title)
local success, titleObject = pcall(newTitle, title)
if success and titleObject then
return titleObject
else
return nil
end
end
local function parseVoteBoundaries(section)
-- Returns an array containing the raw wikitext of RfX votes in a given section.
section = section:match('^.-\n#(.*)$') -- Strip non-votes from the start.
if not section then
return {}
end
section = section:match('^(.-)\n[^#]') or section -- Discard subsequent numbered lists.
local comments = textSplit(section, '\n#')
local votes = {}
for i, comment in ipairs(comments) do
if comment:find('^[^#*;:].*%S') then
votes#votes + 1 = comment
end
end
return votes
end
local function parseVote(vote)
-- parses a username from an RfX vote.
local userStart, userMatch = vote:match('^(.*)%[%[[%s_]*:?[%s_]*[uU][sS][eE][rR][%s_]*:[%s_]*(.-)[%s_]*%]%].-$')
local talkStart, talkMatch = vote:match('^(.*)%[%[[%s_]*:?[%s_]*[uU][sS][eE][rR][%s_]+[tT][aA][lL][kK][%s_]*:[%s_]*(.-)[%s_]*%]%].-$')
local contribStart, contribMatch = vote:match('^(.*)%[%[[%s_]*:?[%s_]*[sS][pP][eE][cC][iI][aA][lL][%s_]*:[%s_]*[cC][oO][nN][tT][rR][iI][bB][uU][tT][iI][oO][nN][sS]/[%s_]*(.-)[%s_]*%]%].-$')
local username
if userStart and talkStart then
if #userStart > #talkStart then
username = userMatch
else
username = talkMatch
end
elseif userStart then
username = userMatch
elseif talkStart then
username = talkMatch
elseif contribStart then
username = contribMatch
else
return string.format( "'''Error parsing signature''': ''%s''", vote )
end
username = username:match('^[^|/#]*')
return username
end
local function parseVoters(votes)
local voters = {}
for i, vote in ipairs(votes) do
voters#voters + 1 = parseVote(vote)
end
return voters
end
local function dupesExist(...)
local exists = {}
local tables = {...}
for i, usernames in ipairs(tables) do
for j, username in ipairs(usernames) do
username = lang:ucfirst(username)
if existsusername then
return true
else
existsusername = true
end
end
end
return false
end
------------------------------------------
-- Define the constructor function --
------------------------------------------
function rfx.new(title)
local obj = {}
local data = {}
local checkSelf = libraryUtil.makeCheckSelfFunction( 'Module:Rfx', 'rfx', obj, 'rfx object' )
-- Get the title object and check to see whether we are a subpage of WP:RFA or WP:RFB.
title = getTitleObject(title)
if not title then
return nil
end
function data:getTitleObject()
checkSelf(self, 'getTitleObject')
return title
end
if title.namespace == 4 then
local rootText = title.rootText
if rootText == 'Requests for adminship' then
data.type = 'rfa'
elseif rootText == 'Requests for bureaucratship' then
data.type = 'rfb'
else
return nil
end
else
return nil
end
-- Get the page content and divide it into sections.
local pageText = title:getContent()
if not pageText then
return nil
end
local introText, supportText, opposeText, neutralText = umatch(
pageText,
'^(.-)\n====[^=\n][^\n]-====.-'
.. '\n=====%s*[sS]upport%s*=====(.-)'
.. '\n=====%s*[oO]ppose%s*=====(.-)'
.. '\n=====%s*[nN]eutral%s*=====(.-)$'
)
if not introText then
introText, supportText, opposeText, neutralText = umatch(
pageText,
"^(.-\n'''[^\n]-%(%d+/%d+/%d+%)[^\n]-''')\n.-"
.. "\n'''Support'''(.-)\n'''Oppose'''(.-)\n'''Neutral'''(.-)"
)
end
-- Get vote counts.
local supportVotes, opposeVotes, neutralVotes
if supportText and opposeText and neutralText then
supportVotes = parseVoteBoundaries(supportText)
opposeVotes = parseVoteBoundaries(opposeText)
neutralVotes = parseVoteBoundaries(neutralText)
end
local supports, opposes, neutrals
if supportVotes and opposeVotes and neutralVotes then
supports = #supportVotes
data.supports = supports
opposes = #opposeVotes
data.opposes = opposes
neutrals = #neutralVotes
data.neutrals = neutrals
end
-- Voter methods and dupe check.
function data:getSupportUsers()
checkSelf(self, 'getSupportUsers')
if supportVotes then
return parseVoters(supportVotes)
else
return nil
end
end
function data:getOpposeUsers()
checkSelf(self, 'getOpposeUsers')
if opposeVotes then
return parseVoters(opposeVotes)
else
return nil
end
end
function data:getNeutralUsers()
checkSelf(self, 'getNeutralUsers')
if neutralVotes then
return parseVoters(neutralVotes)
else
return nil
end
end
function data:dupesExist()
checkSelf(self, 'dupesExist')
local supportUsers = self:getSupportUsers()
local opposeUsers = self:getOpposeUsers()
local neutralUsers = self:getNeutralUsers()
if not (supportUsers and opposeUsers and neutralUsers) then
return nil
end
return dupesExist(supportUsers, opposeUsers, neutralUsers)
end
if supports and opposes then
local total = supports + opposes
if total <= 0 then
data.percent = 0
else
data.percent = math.floor((supports / total * 100) + 0.5)
end
end
if introText then
data.endTime = umatch(introText, '(%d%d:%d%d, %d+ %w+ %d+) %(UTC%)')
data.user = umatch(introText, '===%s*%[%[[_%s]*[wW]ikipedia[_%s]*:[_%s]*[rR]equests[_ ]for[_ ]%w+/.-|[_%s]*(.-)[_%s]*%]%][_%s]*===')
if not data.user then
data.user = umatch(introText, '===%s*([^\n]-)%s*===')
end
end
-- Methods for seconds left and time left.
function data:getSecondsLeft()
checkSelf(self, 'getSecondsLeft')
local endTime = self.endTime
if not endTime then
return nil
end
local now = tonumber(lang:formatDate("U"))
local success, endTimeU = pcall(lang.formatDate, lang, 'U', endTime)
if not success then
return nil
end
endTimeU = tonumber(endTimeU)
if not endTimeU then
return nil
end
local secondsLeft = endTimeU - now
if secondsLeft <= 0 then
return 0
else
return secondsLeft
end
end
function data:getTimeLeft()
checkSelf(self, 'getTimeLeft')
local secondsLeft = self:getSecondsLeft()
if not secondsLeft then
return nil
end
return mw.ustring.gsub(lang:formatDuration(secondsLeft, {'days', 'hours'}), ' and', ',')
end
function data:getReport()
-- Gets the URI object for Vote History tool
checkSelf(self, 'getReport')
return mw.uri.new('https://apersonbot.toolforge.org/vote-history?page=' .. mw.uri.encode(title.prefixedText))
end
function data:getStatus()
-- Gets the current status of the RfX. Returns either "successful", "unsuccessful",
-- "open", or "pending closure". Returns nil if the status could not be found.
checkSelf( self, 'getStatus' )
local rfxType = data.type
if rfxType == 'rfa' then
if umatch(
pageText,
'%[%[[%s_]*[cC][aA][tT][eE][gG][oO][rR][yY][%s_]*:[%s_]*[sS]uccessful requests for adminship(.-)[%s_]*%]%]'
) then
return 'successful'
elseif umatch(
pageText,
'%[%[[%s_]*[cC][aA][tT][eE][gG][oO][rR][yY][%s_]*:[%s_]*[uU]nsuccessful requests for adminship(.-)[%s_]*%]%]'
) then
return 'unsuccessful'
end
elseif rfxType == 'rfb' then
if umatch(
pageText,
'%[%[[%s_]*[cC][aA][tT][eE][gG][oO][rR][yY][%s_]*:[%s_]*[sS]uccessful requests for bureaucratship(.-)[%s_]*%]%]'
) then
return 'successful'
elseif umatch(
pageText,
'%[%[[%s_]*[cC][aA][tT][eE][gG][oO][rR][yY][%s_]*:[%s_]*[uU]nsuccessful requests for bureaucratship(.-)[%s_]*%]%]'
) then
return 'unsuccessful'
end
end
local secondsLeft = self:getSecondsLeft()
if secondsLeft and secondsLeft > 0 then
return 'open'
elseif secondsLeft and secondsLeft <= 0 then
return 'pending closure'
else
return nil
end
end
-- Specify which fields are read-only, and prepare the metatable.
local readOnlyFields = {
getTitleObject = true,
'type' = true,
getSupportUsers = true,
getOpposeUsers = true,
getNeutralUsers = true,
supports = true,
opposes = true,
neutrals = true,
endTime = true,
percent = true,
user = true,
dupesExist = true,
getSecondsLeft = true,
getTimeLeft = true,
getReport = true,
getStatus = true
}
local function pairsfunc( t, k )
local v
repeat
k = next( readOnlyFields, k )
if k == nil then
return nil
end
v = tk
until v ~= nil
return k, v
end
return setmetatable( obj, {
__pairs = function ( t )
return pairsfunc, t, nil
end,
__index = data,
__newindex = function( t, key, value )
if readOnlyFields key then
error( 'index "' .. key .. '" is read-only', 2 )
else
rawset( t, key, value )
end
end,
__tostring = function( t )
return t:getTitleObject().prefixedText
end
} )
end
return rfx