sunflower 0.4.5 → 0.5

data/README

@@ -1,4 +1,4 @@
-Version: 0.4.5 alpha
+Version: 0.5 alpha
 
 >>> English:
 

data/example-bot.rb

@@ -1,12 +1,11 @@
+# coding: utf-8
 # This is the most basic bot possible.
 
-require 'sunflower-commontasks.rb'
+require 'sunflower'
 
-s=Sunflower.new
-s.login
+s = Sunflower.new.login
+s.summary = 'test summary'
 
-$summary='Sunflower: test'
-
-p=Page.get('Test')
-p.write p.text+"\n\ntest"
-p.save
+p = Sunflower::Page.new 'Test'
+p.text += "\n\ntest"
+p.save

data/lib/sunflower/commontasks.rb

@@ -1,80 +1,6 @@
 # coding: utf-8
-# extends Page with some methods letting easily perform common tasks
 
-class Page
-	# executes methods on self
-	# "commands" is array of arrays
-	# page.execute([
-		# [:replace, 'something', 'whatever'],
-		# [:append, 'some things']
-	# ])
-	#        equals to
-	# page.replace('something', 'whatever')
-	# page.append('some things')
-	
-	# allowed modifiers:
-	# r, required
-	# oi:module, only-if:module
-	# !oi:module, only-if-not:module
-	# s:append to summary, summary:append to summary
-	def execute commands
-		originalText = self.text.dup
-	
-		commands.each do |cmd|
-			f=cmd.shift
-			if f.class==Array
-				methodName=f.shift
-				modifiers=f.map{|i|
-					i+=':' if !i.include? ':'
-					i=i.split(':',-1)
-					i[0]=i[0].downcase.gsub(/[^a-z!]/,'')
-					
-					i[0]='r' if i[0]=='required'
-					i[0]='oi' if i[0]=='onlyif'
-					i[0]='!oi' if i[0]=='onlyifnot'
-					i[0]='s' if i[0]=='summary'
-					
-					type=i.shift
-					i=i.join(':')
-					
-					[type,i]
-				}
-				modifiers=Hash[*(modifiers.flatten)]
-			else
-				methodName=f
-				modifiers={}
-			end
-			
-			if modifiers['oi']
-				if !@modulesExecd.index(modifiers['oi'].strip)
-					next #skip this command
-				end
-			end
-			if modifiers['!oi']
-				if @modulesExecd.index(modifiers['oi'].strip)
-					next #skip this command
-				end
-			end
-			
-			oldText=self.text
-			self.method(methodName).call(*cmd)
-			newText=self.text
-			
-			@modulesExecd<<methodName if oldText!=newText
-			
-			if modifiers['s'] && oldText!=newText
-				@summaryAppend<<modifiers['s'].strip
-			end
-			
-			if modifiers['r'] && oldText==newText
-				self.text = originalText
-				break #reset text and stop executing commands
-			end
-		end
-	end
-	
-	
-	
+class Sunflower::Page
 	# replaces "from" with "to" in page text
 	# "from" may be regex
 	def replace from, to, once=false
@@ -152,7 +78,7 @@ class Page
 		
 		str.gsub!(/\[\[([^\|\]]+)(\||\]\])/){
 			name, rest = $1, $2
-			"[[#{self.sunflower.cleanup_title name}#{rest}"
+			"[[#{self.sunflower.cleanup_title name, true, true}#{rest}"
 		}
 		
 		# headings
@@ -164,7 +90,7 @@ class Page
 		
 		if wikiid = self.sunflower.siteinfo['general']['wikiid']
 			if self.respond_to? :"code_cleanup_#{wikiid}"
-				str = self.call :"code_cleanup_#{wikiid}", str
+				str = self.send :"code_cleanup_#{wikiid}", str
 			end
 		end
 		

data/lib/sunflower/core.rb

@@ -3,8 +3,6 @@ require 'rest-client'
 require 'json'
 require 'cgi'
 
-class SunflowerError < StandardError; end
-
 # Main class. To start working, you have to create new Sunflower:
 #   s = Sunflower.new('en.wikipedia.org')
 # And then log in:
@@ -19,7 +17,7 @@ class SunflowerError < StandardError; end
 #
 # You can use multiple Sunflowers at once, to work on multiple wikis.
 class Sunflower
-	VERSION = '0.4.5'
+	VERSION = '0.5'
 	
 	INVALID_CHARS = %w(# < > [ ] | { })
 	INVALID_CHARS_REGEX = Regexp.union *INVALID_CHARS
@@ -28,7 +26,19 @@ class Sunflower
 	def self.path
 		File.join(ENV['HOME'], 'sunflower-userdata')
 	end
-
+	
+	# Returns array of [url, username, password], or nil if userdata is unavailable or invalid.
+	def self.read_userdata
+		data = nil
+		data = File.read(Sunflower.path).split(/\r?\n/).map{|i| i.strip} rescue nil
+		
+		if data && data.length==3 && data.all?{|a| a and a != ''}
+			return data
+		else
+			return nil
+		end
+	end
+	
 	# Summary used when saving edits with this Sunflower.
 	attr_accessor :summary
 	# Whether to run #code_cleanup when calling #save.
@@ -38,6 +48,11 @@ class Sunflower
 	# Siteinfo, as returned by API call.
 	attr_accessor :siteinfo
 	
+	# Whether we are logged in.
+	def logged_in?; @loggedin; end
+	# Username if logged in; nil otherwise.
+	attr_reader :username
+	
 	# Whether this user (if logged in) has bot rights.
 	def is_bot?; @is_bot; end
 	
@@ -49,29 +64,72 @@ class Sunflower
 	attr_writer :log
 	def log?; @log; end
 	
-	# Initialize a new Sunflower working on a wiki with given URL, for ex. "pl.wikipedia.org".
-	def initialize url=nil
-		begin
-			r=File.read(Sunflower.path)
-			@userdata=r.split(/\r?\n/).map{|i| i.strip}
-		rescue
-			@userdata=[]
-		end
+	# Used by #initialize to convert short identifiers such as "b:pl" to domains such as "pl.wikibooks.org".
+	# Identifier is of the format "type:lang" or "lang:type" (see below for valid values).
+	# 
+	# Either or both parts can be ommitted; default type is "w", default lang is "en". 
+	# (Since clashes are impossible, the colon can be ommitted in such cases as well.)
+	# 
+	# lang can be any valid language code. It is ignored for type == "meta" or "commons".
+	# 
+	# Valid values for type are the same as used for inter-wiki links, that is:
+	# [w] Wikipedia
+	# [b] Wikibooks
+	# [n] Wikinews
+	# [q] Wikiquote
+	# [s] Wikisource
+	# [v] Wikiversity
+	# [wikt] Wiktionary
+	# [species] Wikispecies
+	# [commons] Wikimedia Commons
+	# [meta] Wikimedia Meta-Wiki 
+	def self.resolve_wikimedia_id id
+		keys = id.split(':').select{|a| a and !a.empty? }
+		
+		raise ArgumentError, 'invalid format' if keys.length > 2
+		
+		type_map = {
+			'b' => 'XX.wikibooks.org',
+			'q' => 'XX.wikiquote.org',
+			'n' => 'XX.wikinews.org',
+			'w' => 'XX.wikipedia.org',
+			'wikt' => 'XX.wiktionary.org',
+			'species' => 'XX.wikispecies.org',
+			'v' => 'XX.wikiversity.org',
+			's' => 'XX.wikisource.org',
+			'commons' => 'commons.wikimedia.org',
+			'meta' => 'meta.wikimedia.org',
+		}
+		
+		types, langs = keys.partition{|a| type_map.keys.include? a }
+		type = types.first || 'w'
+		lang = langs.first || 'en'
 		
+		return type_map[type].sub 'XX', lang
+	end
+	
+	# Initialize a new Sunflower working on a wiki with given URL, for ex. "pl.wikipedia.org". url can also be a shorthand identifier such as "b:pl" - see Sunflower.resolve_wikimedia_id for details.
+	def initialize url=nil
 		if !url
-			if !@userdata.empty?
-				url=@userdata[0]
+			userdata = Sunflower.read_userdata()
+			
+			if userdata
+				url = userdata[0]
 			else
-				raise SunflowerError, 'initialize: no URL supplied and no userdata found!'
+				raise Sunflower::Error, 'initialize: no URL supplied and no userdata found!'
 			end
 		end
 		
-		@warnings=true
-		@log=false
+		@wikiURL = (url.include?('.') ? url : Sunflower.resolve_wikimedia_id(url))
+		
+		@warnings = true
+		@log = false
 		
-		@wikiURL=url
+		@loggedin = false
+		@username = nil
+		@is_bot = false
 		
-		@loggedin=false
+		@cookies = {}
 		
 		siprop = 'general|namespaces|namespacealiases|specialpagealiases|magicwords|interwikimap|dbrepllag|statistics|usergroups|extensions|fileextensions|rightsinfo|languages|skins|extensiontags|functionhooks|showhooks|variables'
 		@siteinfo = self.API(action: 'query', meta: 'siteinfo', siprop: siprop)['query']
@@ -79,6 +137,10 @@ class Sunflower
 		_build_ns_map
 	end
 	
+	def inspect
+		"#<Sunflower #{@loggedin ? @username : "[anon]"}@#{@wikiURL}#{@is_bot ? ' [bot]' : ''}>"
+	end
+	
 	# Private. Massages data from siteinfo to be used for recognizing namespaces.
 	def _build_ns_map
 		@namespace_to_id = {} # all keys lowercase
@@ -99,6 +161,7 @@ class Sunflower
 			@namespace_to_id[ h['*'].downcase ] = h['id'].to_i
 		end
 	end
+	private :_build_ns_map
 	
 	# Call the API. Returns a hash of JSON response. Request can be a HTTP request string or a hash.
 	def API request
@@ -116,25 +179,69 @@ class Sunflower
 		JSON.parse resp.to_str
 	end
 	
+	# Call the API. While more results are available via the xxcontinue parameter, call it again. 
+	# 
+	# Assumes action=query. 
+	# 
+	# By default returns an array of all API responses. Attempts to merge the responses
+	# into a response that would have been returned if the limit was infinite. merge_on is
+	# the key of response['query'] to merge consecutive responses on.
+	# 
+	# If limit given, will perform no more than this many API calls before returning.
+	# If limit is 1, behaves exactly like #API.
+	# 
+	# Example: get list of all pages linking to Main Page:
+	#   
+	#   sunflower.API_continued "action=query&list=backlinks&bllimit=max&bltitle=Main_Page", 'backlinks', 'blcontinue'
+	def API_continued request, merge_on, xxcontinue, limit=nil
+		out = []
+		
+		# gather
+		res = self.API(request)
+		out << res
+		while res['query-continue'] and (!limit || out.length < limit)
+			api_endpoint = if request.is_a? String
+				request + "&#{xxcontinue}=#{res["query-continue"][merge_on][xxcontinue]}"
+			elsif request.is_a? Hash
+				request.merge({xxcontinue => res["query-continue"][merge_on][xxcontinue]})
+			end
+			
+			res = self.API(api_endpoint)
+			out << res
+		end
+		
+		# merge
+		merged = out[0]
+		meth = (merged['query'][merge_on].is_a?(Hash) ? :merge! : :concat)
+		
+		out.drop(1).each do |cur|
+			merged['query'][merge_on].send meth, cur['query'][merge_on]
+		end
+		
+		return merged
+	end
+	
 	# Log in using given info.
 	def login user='', password=''
 		if user=='' || password==''
-			if !@userdata.empty?
-				user=@userdata[1] if user==''
-				password=@userdata[2] if password==''
+			userdata = Sunflower.read_userdata()
+			
+			if userdata
+				user = userdata[1] if user==''
+				password = userdata[2] if password==''
 			else
-				raise SunflowerError, 'login: no user/pass supplied and no userdata found!'
+				raise Sunflower::Error, 'login: no user/pass supplied and no userdata found!'
 			end
 		end
 		
-		raise SunflowerError, 'bad username!' if user =~ INVALID_CHARS_REGEX
+		raise Sunflower::Error, 'bad username!' if user =~ INVALID_CHARS_REGEX
 		
 		
 		# 1. get the login token
 		response = RestClient.post(
 			'http://'+@wikiURL+'/w/api.php?'+"action=login&lgname=#{CGI.escape user}&lgpassword=#{CGI.escape password}"+'&format=json', 
 			nil,
-			{:user_agent => 'Sunflower alpha'}
+			{:user_agent => "Sunflower #{VERSION} alpha"}
 		)
 		
 		@cookies = response.cookies
@@ -146,7 +253,7 @@ class Sunflower
 		response = RestClient.post(
 			'http://'+@wikiURL+'/w/api.php?'+"action=login&lgname=#{CGI.escape user}&lgpassword=#{CGI.escape password}&lgtoken=#{token}"+'&format=json',
 			nil,
-			{:user_agent => 'Sunflower alpha', :cookies => @cookies}
+			{:user_agent => "Sunflower #{VERSION} alpha", :cookies => @cookies}
 		)
 		
 		json = JSON.parse response.to_str
@@ -158,7 +265,7 @@ class Sunflower
 		})
 		
 		
-		raise SunflowerError, 'unable to log in (no cookies received)!' if !@cookies
+		raise Sunflower::Error, 'unable to log in (no cookies received)!' if !@cookies
 		
 		
 		# 3. confirm you did log in by checking the watchlist.
@@ -166,9 +273,12 @@ class Sunflower
 		r=self.API('action=query&list=watchlistraw')
 		if r['error'] && r['error']['code']=='wrnotloggedin'
 			@loggedin=false
-			raise SunflowerError, 'unable to log in!'
+			raise Sunflower::Error, 'unable to log in!'
 		end
 		
+		# set the username
+		@username = user
+		
 		# 4. check bot rights
 		r=self.API('action=query&list=allusers&aulimit=1&augroup=bot&aufrom='+(CGI.escape user))
 		unless r['query']['allusers'][0]['name']==user
@@ -187,7 +297,9 @@ class Sunflower
 	end
 	
 	# Cleans up underscores, percent-encoding and title-casing in title (with optional anchor).
-	def cleanup_title title
+	def cleanup_title title, preserve_case=false, preserve_colon=false
+		return '' if title.strip == ''
+		
 		name, anchor = title.split '#', 2
 		
 		# CGI.unescape also changes pluses to spaces; code borrowed from there
@@ -197,6 +309,10 @@ class Sunflower
 		name = unescape.call(name).gsub(/[ _]+/, ' ').strip
 		anchor = unescape.call(anchor.gsub(/\.([0-9a-fA-F]{2})/, '%\1')).gsub(/[ _]+/, ' ').strip if anchor
 		
+		leading_colon = name[0]==':'
+		name = name.sub(/^:\s*/, '') if leading_colon
+		leading_colon = false if !preserve_colon
+		
 		# FIXME unicode? downcase, upcase
 		
 		if name.include? ':'
@@ -206,9 +322,9 @@ class Sunflower
 			end
 		end
 		
-		name[0] = name[0].upcase if @siteinfo["general"]["case"] == "first-letter"
+		name[0] = name[0].upcase if !preserve_case and @siteinfo["general"]["case"] == "first-letter"
 		
-		return [ns ? "#{ns}:" : nil,  name,  anchor ? "##{anchor}" : nil].join ''
+		return [leading_colon ? ':' : nil,  ns ? "#{ns}:" : nil,  name,  anchor ? "##{anchor}" : nil].join ''
 	end
 	
 	# Returns the localized namespace name for ns, which may be namespace number, canonical name, or any namespace alias.
@@ -245,76 +361,103 @@ class Sunflower
 end
 
 # Class representing a single Wiki page. To load specified page, use #new. To save it back, use #save.
-class Page
+class Sunflower::Page
 	# Characters which MediaWiki does not permit in page title.
 	INVALID_CHARS = %w(# < > [ ] | { })
 	# Regex matching characters which MediaWiki does not permit in page title.
 	INVALID_CHARS_REGEX = Regexp.union *INVALID_CHARS
 	
-	# The current text of the page.
+	# The Sunflower instance this page belongs to.
+	attr_reader :sunflower
+	
+	# The current text of the page. Lazy-loaded.
 	attr_accessor :text
-	# The text of the page, as of when it was loaded.
+	# The text of the page, as of when it was loaded. Lazy-loaded.
 	attr_reader :orig_text
 	
-	# The Sunflower instance this page belongs to.
-	attr_reader :sunflower
+	# Page title, as passed to #initialize and cleaned by Sunflower#cleanup_title.
+	# Real page title as canonicalized by MediaWiki software can be accessed via #real_title
+	# (but it should always be the same).
+	attr_reader :title
 	
-	# this is only for RDoc. wrapped in "if false" to avoid warnings when running with ruby -w
-	if false
-	# Return value of given attribute, as returned by API call prop=info for this page. Lazy-loaded.
-	attr_reader :pageid, :ns, :title, :touched, :lastrevid, :counter, :length, :starttimestamp, :edittoken, :protection
-	end
+	# Value of given attribute, as returned by API call prop=info for this page. Lazy-loaded.
+	attr_reader :pageid, :ns, :touched, :lastrevid, :counter, :length, :starttimestamp, :edittoken, :protection
+	# Value of `title` attribute, as returned by API call prop=info for this page. Lazy-loaded. See #title.
+	attr_reader :real_title
+	
+	# Whether this datum is already loaded. Can be set to true to suppress loading
+	# (used e.g. by Sunflower::List#pages_preloaded)
+	attr_accessor :preloaded_text, :preloaded_attrs
 	
 	# calling any of these accessors will fetch the data.
-	[:pageid, :ns, :title, :touched, :lastrevid, :counter, :length, :starttimestamp, :edittoken, :protection].each do |meth|
+	# getters...
+	[:pageid, :ns, :real_title, :touched, :lastrevid, :counter, :length, :starttimestamp, :edittoken, :protection].each do |meth|
+		remove_method meth # to avoid warnings when running with ruby -w
 		define_method meth do
 			preload_attrs unless @preloaded_attrs
 			instance_variable_get "@#{meth}"
 		end
 	end
+	[:text, :orig_text].each do |meth|
+		remove_method meth # to avoid warnings when running with ruby -w
+		define_method meth do
+			preload_text unless @preloaded_text
+			instance_variable_get "@#{meth}"
+		end
+	end
+	# setters...
+	[:text=].each do |meth|
+		remove_method meth # to avoid warnings when running with ruby -w
+		define_method meth do |a|
+			preload_text unless @preloaded_text
+			instance_variable_set "@#{meth.to_s.chop}", a
+		end
+	end
 	
-	# Load the specified page. Only the text will be immediately loaded - attributes and edit token will be loaded when needed, or when you call #preload_attrs.
-	#
-	# If you are using multiple Sunflowers, you have to specify which wiki this page belongs to using the second argument of function; you can pass whole URL (same as when creating new Sunflower) or just the language code.
-	def initialize title='', wiki=''
-		raise SunflowerError, 'title invalid: '+title if title =~ INVALID_CHARS_REGEX
+	# Load the specified page. 
+	# Only the text will be immediately loaded - attributes and edit token will be loaded when needed, or when you call #preload_attrs.
+	# 
+	# If you are using multiple Sunflowers, you have to specify which one this page belongs to using the second argument of function.
+	# You can pass either a Sunflower object, wiki URL, or a shorthand id as specified in Sunflower.resolve_wikimedia_id.
+	def initialize title='', url=''
+		raise Sunflower::Error, 'title invalid: '+title if title =~ INVALID_CHARS_REGEX
 		
 		@modulesExecd=[] #used by sunflower-commontasks.rb
 		@summaryAppend=[] #used by sunflower-commontasks.rb
 		
-		wiki = wiki+'.wikipedia.org' if wiki.index('.')==nil && wiki!=''
-		
-		if wiki=='' 
-			count=ObjectSpace.each_object(Sunflower){|o| @sunflower=o}
-			raise SunflowerError, 'no Sunflowers present' if count==0
-			raise SunflowerError, 'you must pass wiki name if using multiple Sunflowers at once' if count>1
+		case url
+		when Sunflower
+			@sunflower = url
+		when '', nil
+			count = ObjectSpace.each_object(Sunflower){|o| @sunflower=o}
+			raise Sunflower::Error, 'no Sunflowers present' if count==0
+			raise Sunflower::Error, 'you must pass wiki name if using multiple Sunflowers at once' if count>1
 		else
-			ObjectSpace.each_object(Sunflower){|o| @sunflower=o if o.wikiURL==wiki}
+			url = (url.include?('.') ? url : Sunflower.resolve_wikimedia_id(url))
+			ObjectSpace.each_object(Sunflower){|o| @sunflower=o if o.wikiURL==url}
+			raise Sunflower::Error, "no Sunflower for #{url}" if !@sunflower
 		end
 		
-		raise SunflowerError, "no Sunflower for #{wiki}" if !@sunflower
-		
 		@title = @sunflower.cleanup_title title
 		
-		if title==''
-			@text=''
-			@orig_text=''
-			return
-		end
-		
-		preload_text
+		@preloaded_text = false
+		@preloaded_attrs = false
 	end
 	
 	# Load the text of this page. Semi-private.
 	def preload_text
-		r = @sunflower.API('action=query&prop=revisions&rvprop=content&titles='+CGI.escape(@title))
-		r = r['query']['pages'].first
-		if r['missing']
+		if title == ''
 			@text = ''
-		elsif r['invalid']
-			raise SunflowerError, 'title invalid: '+@title
 		else
-			@text = r['revisions'][0]['*']
+			r = @sunflower.API('action=query&prop=revisions&rvprop=content&titles='+CGI.escape(@title))
+			r = r['query']['pages'].values.first
+			if r['missing']
+				@text = ''
+			elsif r['invalid']
+				raise Sunflower::Error, 'title invalid: '+@title
+			else
+				@text = r['revisions'][0]['*']
+			end
 		end
 		
 		@orig_text = @text.dup
@@ -325,8 +468,9 @@ class Page
 	# Load the metadata associated with this page. Semi-private.
 	def preload_attrs
 		r = @sunflower.API('action=query&prop=info&inprop=protection&intoken=edit&titles='+CGI.escape(@title))
-		r = r['query']['pages'].first
+		r = r['query']['pages'].values.first
 		r.each{|key, value|
+			key = 'real_title' if key == 'title'
 			self.instance_variable_set('@'+key, value)
 		}
 		
@@ -359,8 +503,8 @@ class Page
 		
 		summary = @sunflower.summary if !summary
 		
-		raise SunflowerError, 'title invalid: '+title if title =~ INVALID_CHARS_REGEX
-		raise SunflowerError, 'no summary!' if (!summary or summary=='') && @summaryAppend.empty?
+		raise Sunflower::Error, 'title invalid: '+title if title =~ INVALID_CHARS_REGEX
+		raise Sunflower::Error, 'no summary!' if (!summary or summary=='') && @summaryAppend.empty?
 		
 		unless @summaryAppend.empty?
 			if !summary or summary==''
@@ -383,18 +527,53 @@ class Page
 	alias :put :save
 	
 	def self.get title, wiki=''
-		Page.new(title, wiki)
+		self.new(title, wiki)
 	end
 	
 	def self.load title, wiki=''
-		Page.new(title, wiki)
+		self.new(title, wiki)
+	end
+end
+
+# For backwards compatibility. Deprecated.
+class Page # :nodoc:
+	class << self
+		def new *a
+			warn "warning: toplevel Page class has been renamed to Sunflower::Page, this alias will be removed in v0.6"
+			Sunflower::Page.new *a
+		end
+		alias get new
+		alias load new
 	end
 end
 
-class Hash
-	# just a lil patch
-	def first
-		self.values[0]
+# For backwards compatibility. Deprecated.
+# 
+# We use inheritance shenanigans to keep the usage in "begin ... rescue ... end" working.
+class SunflowerError < StandardError # :nodoc:
+	%w[== backtrace exception inspect message set_backtrace to_s].each do |meth|
+		define_method meth.to_sym do |*a, &b|
+			if self.class == Sunflower::Error and !@warned
+				warn "warning: toplevel SunflowerError class has been renamed to Sunflower::Error, this alias will be removed in v0.6"
+				@warned = true
+			end
+			
+			super *a, &b
+		end
+	end
+	
+	class << self
+		def new *a
+			warn "warning: toplevel SunflowerError class has been renamed to Sunflower::Error, this alias will be removed in v0.6" unless self == Sunflower::Error
+			super
+		end
+		def exception *a
+			warn "warning: toplevel SunflowerError class has been renamed to Sunflower::Error, this alias will be removed in v0.6" unless self == Sunflower::Error
+			super
+		end
 	end
 end
 
+
+# Represents an error raised by Sunflower.
+class Sunflower::Error < SunflowerError; end