mediawiki-gateway 0.6.2 → 1.0.0.rc1

data/lib/media_wiki/gateway.rb

@@ -1,18 +1,23 @@
-require 'rubygems'
 require 'logger'
 require 'rest_client'
 require 'rexml/document'
 require 'uri'
-require 'active_support'
 
 module MediaWiki
 
   class Gateway
-    attr_reader :log
+
+    USER_AGENT = "#{self}/#{VERSION}"
+
+    class << self
+
+      attr_accessor :default_user_agent
+
+    end
 
     # Set up a MediaWiki::Gateway for a given MediaWiki installation
     #
-    # [url] Path to API of target MediaWiki (eg. "http://en.wikipedia.org/w/api.php")
+    # [url] Path to API of target MediaWiki (eg. 'http://en.wikipedia.org/w/api.php')
     # [options] Hash of options
     # [http_options] Hash of options for RestClient::Request (via http_send)
     #
@@ -25,912 +30,59 @@ module MediaWiki
     # [:maxlag] Maximum allowed server lag (see http://www.mediawiki.org/wiki/Manual:Maxlag_parameter), defaults to 5 seconds.
     # [:retry_count] Number of times to try before giving up if MediaWiki returns 503 Service Unavailable, defaults to 3 (original request plus two retries).
     # [:retry_delay] Seconds to wait before retry if MediaWiki returns 503 Service Unavailable, defaults to 10 seconds.
-    def initialize(url, options={}, http_options={})
-      default_options = {
-        :bot => false,
-        :limit => 500,
-        :logdevice => STDERR,
-        :loglevel => Logger::WARN,
-        :maxlag => 5,
-        :retry_count => 3,
-        :retry_delay => 10,
-        :max_results => 500
-      }
-      @options = default_options.merge(options)
-      @http_options = http_options
-      @wiki_url = url
+    # [:user_agent] User-Agent header to send with requests, defaults to ::default_user_agent or nil.
+    def initialize(url, options = {}, http_options = {})
+      @options = {
+        bot:         false,
+        limit:       500,
+        logdevice:   STDERR,
+        loglevel:    Logger::WARN,
+        max_results: 500,
+        maxlag:      5,
+        retry_count: 3,
+        retry_delay: 10,
+        user_agent:  self.class.default_user_agent
+      }.merge(options)
+
       @log = Logger.new(@options[:logdevice])
       @log.level = @options[:loglevel]
-      @headers = { "User-Agent" => "MediaWiki::Gateway/#{MediaWiki::VERSION}", "Accept-Encoding" => "gzip" }
-      @cookies = {}
-    end
-
-    attr_reader :base_url, :cookies
-
-    # Login to MediaWiki
-    #
-    # [username] Username
-    # [password] Password
-    # [domain] Domain for authentication plugin logins (eg. LDAP), optional -- defaults to 'local' if not given
-    # [options] Hash of additional options
-    #
-    # Throws MediaWiki::Unauthorized if login fails
-    def login(username, password, domain = 'local', options = {})
-      make_api_request(options.merge(
-        'action'     => 'login',
-        'lgname'     => username,
-        'lgpassword' => password,
-        'lgdomain'   => domain
-      ))
-
-      @password = password
-      @username = username
-    end
-
-    # Fetch MediaWiki page in MediaWiki format.  Does not follow redirects.
-    #
-    # [page_title] Page title to fetch
-    # [options] Hash of additional options
-    #
-    # Returns content of page as string, nil if the page does not exist.
-    def get(page_title, options = {})
-      page = make_api_request(options.merge(
-        'action' => 'query',
-        'prop'   => 'revisions',
-        'rvprop' => 'content',
-        'titles' => page_title
-      )).first.elements['query/pages/page']
-
-      page.elements['revisions/rev'].text || '' if valid_page?(page)
-    end
-
-    # Fetch latest revision ID of a MediaWiki page.  Does not follow redirects.
-    #
-    # [page_title] Page title to fetch
-    # [options] Hash of additional options
-    #
-    # Returns revision ID as a string, nil if the page does not exist.
-    def revision(page_title, options = {})
-      page = make_api_request(options.merge(
-        'action'  => 'query',
-        'prop'    => 'revisions',
-        'rvprop'  => 'ids',
-        'rvlimit' => 1,
-        'titles'  => page_title
-      )).first.elements['query/pages/page']
-
-      page.elements['revisions/rev'].attributes['revid'] if valid_page?(page)
-    end
-
-    # Render a MediaWiki page as HTML
-    #
-    # [page_title] Page title to fetch
-    # [options] Hash of additional options
-    #
-    # Options:
-    # * [:linkbase] supply a String to prefix all internal (relative) links with. '/wiki/' is assumed to be the base of a relative link
-    # * [:noeditsections] strips all edit-links if set to +true+
-    # * [:noimages] strips all +img+ tags from the rendered text if set to +true+
-    #
-    # Returns rendered page as string, or nil if the page does not exist
-    def render(page_title, options = {})
-      form_data = {'action' => 'parse', 'page' => page_title}
 
-      valid_options = %w(linkbase noeditsections noimages)
-      # Check options
-      options.keys.each{|opt| raise ArgumentError.new("Unknown option '#{opt}'") unless valid_options.include?(opt.to_s)}
-
-      rendered = nil
-      parsed = make_api_request(form_data).first.elements["parse"]
-      if parsed.attributes["revid"] != '0'
-        rendered = parsed.elements["text"].text.gsub(/<!--(.|\s)*?-->/, '')
-        # OPTIMIZE: unifiy the keys in +options+ like symbolize_keys! but w/o
-        if options["linkbase"] or options[:linkbase]
-          linkbase = options["linkbase"] || options[:linkbase]
-          rendered = rendered.gsub(/\shref="\/wiki\/([\w\(\)\-\.%:,]*)"/, ' href="' + linkbase + '/wiki/\1"')
-        end
-        if options["noeditsections"] or options[:noeditsections]
-          rendered = rendered.gsub(/<span class="editsection">\[.+\]<\/span>/, '')
-        end
-        if options["noimages"] or options[:noimages]
-          rendered = rendered.gsub(/<img.*\/>/, '')
-        end
-      end
-      rendered
-    end
-
-    # Create a new page, or overwrite an existing one
-    #
-    # [title] Page title to create or overwrite, string
-    # [content] Content for the page, string
-    # [options] Hash of additional options
-    #
-    # Options:
-    # * [:overwrite] Allow overwriting existing pages
-    # * [:summary] Edit summary for history, string
-    # * [:token] Use this existing edit token instead requesting a new one (useful for bulk loads)
-    # * [:minor] Mark this edit as "minor" if true, mark this edit as "major" if false, leave major/minor status by default if not specified
-    # * [:notminor] Mark this edit as "major" if true
-    # * [:bot] Set the bot parameter (see http://www.mediawiki.org/wiki/API:Edit#Parameters).  Defaults to false.
-    def create(title, content, options={})
-      form_data = {'action' => 'edit', 'title' => title, 'text' => content, 'summary' => (options[:summary] || ""), 'token' => get_token('edit', title)}
-      if @options[:bot] or options[:bot]
-        form_data['bot'] = '1'
-        form_data['assert'] = 'bot'
-      end
-      form_data['minor'] = '1' if options[:minor]
-      form_data['notminor'] = '1' if options[:minor] == false or options[:notminor]
-      form_data['createonly'] = "" unless options[:overwrite]
-      form_data['section'] = options[:section].to_s if options[:section]
-      make_api_request(form_data)
-    end
-
-    # Edit page
-    #
-    # Same options as create, but always overwrites existing pages (and creates them if they don't exist already).
-    def edit(title, content, options={})
-      create(title, content, {:overwrite => true}.merge(options))
-    end
-
-    # Protect/unprotect a page
-    #
-    # Arguments:
-    # * [title] Page title to protect, string
-    # * [protections] Protections to apply, hash or array of hashes
-    #
-    #   Protections:
-    #   * [:action] (required) The action to protect, string
-    #   * [:group] (required) The group allowed to perform the action, string
-    #   * [:expiry] The protection expiry as a GNU timestamp, string
-    #
-    # * [options] Hash of additional options
-    #
-    #   Options:
-    #   * [:cascade] Protect pages included in this page, boolean
-    #   * [:reason] Reason for protection, string
-    #
-    # Examples:
-    # 1. mw.protect('Main Page', {:action => 'edit', :group => 'all'}, {:cascade => true})
-    # 2. prt = [{:action => 'move', :group => 'sysop', :expiry => 'never'},
-    #      {:action => 'edit', :group => 'autoconfirmed', :expiry => 'next Monday 16:04:57'}]
-    #    mw.protect('Main Page', prt, {:reason => 'awesomeness'})
-    #
-    def protect(title, protections, options={})
-      # validate and format protections
-      protections = [protections] if protections.is_a?(Hash)
-      raise ArgumentError.new("Invalid type '#{protections.class}' for protections") unless protections.is_a?(Array)
-      valid_prt_options = %w(action group expiry)
-      required_prt_options = %w(action group)
-      p,e = [],[]
-      protections.each do |prt|
-        existing_prt_options = []
-        prt.keys.each do |opt|
-          if valid_prt_options.include?(opt.to_s)
-            existing_prt_options.push(opt.to_s)
-          else
-            raise ArgumentError.new("Unknown option '#{opt}' for protections")
-          end
-        end
-        required_prt_options.each{|opt| raise ArgumentError.new("Missing required option '#{opt}' for protections") unless existing_prt_options.include?(opt)}
-        p.push("#{prt[:action]}=#{prt[:group]}")
-        if prt.has_key?(:expiry)
-          e.push(prt[:expiry].to_s)
-        else
-          e.push('never')
-        end
-      end
-
-      # validate options
-      valid_options = %w(cascade reason)
-      options.keys.each{|opt| raise ArgumentError.new("Unknown option '#{opt}'") unless valid_options.include?(opt.to_s)}
-
-      # make API request
-      form_data = {'action' => 'protect', 'title' => title, 'token' => get_token('protect', title)}
-      form_data['protections'] = p.join('|')
-      form_data['expiry'] = e.join('|')
-      form_data['cascade'] = '' if options[:cascade] === true
-      form_data['reason'] = options[:reason].to_s if options[:reason]
-      make_api_request(form_data)
-    end
-
-    # Move a page to a new title
-    #
-    # [from] Old page name
-    # [to] New page name
-    # [options] Hash of additional options
-    #
-    # Options:
-    # * [:movesubpages] Move associated subpages
-    # * [:movetalk] Move associated talkpages
-    # * [:noredirect] Do not create a redirect page from old name.  Requires the 'suppressredirect' user right, otherwise MW will silently ignore the option and create the redirect anyway.
-    # * [:reason] Reason for move
-    # * [:watch] Add page and any redirect to watchlist
-    # * [:unwatch] Remove page and any redirect from watchlist
-    def move(from, to, options={})
-      valid_options = %w(movesubpages movetalk noredirect reason watch unwatch)
-      options.keys.each{|opt| raise ArgumentError.new("Unknown option '#{opt}'") unless valid_options.include?(opt.to_s)}
-
-      form_data = options.merge({'action' => 'move', 'from' => from, 'to' => to, 'token' => get_token('move', from)})
-      make_api_request(form_data)
-    end
-
-    # Delete one page. (MediaWiki API does not support deleting multiple pages at a time.)
-    #
-    # [title] Title of page to delete
-    # [options] Hash of additional options
-    def delete(title, options = {})
-      make_api_request(options.merge(
-        'action' => 'delete',
-        'title'  => title,
-        'token'  => get_token('delete', title)
-      ))
-    end
-
-    # Undelete all revisions of one page.
-    #
-    # [title] Title of page to undelete
-    # [options] Hash of additional options
-    #
-    # Returns number of revisions undeleted, or zero if nothing to undelete
-    def undelete(title, options = {})
-      if token = get_undelete_token(title)
-        make_api_request(options.merge(
-          'action' => 'undelete',
-          'title'  => title,
-          'token'  => token
-        )).first.elements['undelete'].attributes['revisions'].to_i
-      else
-        0 # No revisions to undelete
-      end
-    end
-
-    # Get a list of matching page titles in a namespace
-    #
-    # [key] Search key, matched as a prefix (^key.*).  May contain or equal a namespace, defaults to main (namespace 0) if none given.
-    # [options] Optional hash of additional options, eg. { 'apfilterredir' => 'nonredirects' }.  See http://www.mediawiki.org/wiki/API:Allpages
-    #
-    # Returns array of page titles (empty if no matches)
-    def list(key, options = {})
-      key, namespace = key.split(':', 2).reverse
-      namespace = namespaces_by_prefix[namespace] || 0
-
-      iterate_query('allpages', '//p', 'title', 'apfrom', options.merge(
-        'list'        => 'allpages',
-        'apprefix'    => key,
-        'apnamespace' => namespace,
-        'aplimit'     => @options[:limit]
-      ))
-    end
-
-    # Get a list of pages that are members of a category
-    #
-    # [category] Name of the category
-    # [options] Optional hash of additional options. See http://www.mediawiki.org/wiki/API:Categorymembers
-    #
-    # Returns array of page titles (empty if no matches)
-    def category_members(category, options = {})
-      iterate_query('categorymembers', '//cm', 'title', 'cmcontinue', options.merge(
-        'cmtitle' => category,
-        'cmlimit' => @options[:limit]
-      ))
-    end
-
-    # Get a list of pages that link to a target page
-    #
-    # [title] Link target page
-    # [filter] "all" links (default), "redirects" only, or "nonredirects" (plain links only)
-    # [options] Hash of additional options
-    #
-    # Returns array of page titles (empty if no matches)
-    def backlinks(title, filter = 'all', options = {})
-      iterate_query('backlinks', '//bl', 'title', 'blcontinue', options.merge(
-        'bltitle'       => title,
-        'blfilterredir' => filter,
-        'bllimit'       => @options[:limit]
-      ))
-    end
-
-    # Get a list of pages with matching content in given namespaces
-    #
-    # [key] Search key
-    # [namespaces] Array of namespace names to search (defaults to main only)
-    # [limit] Maximum number of hits to ask for (defaults to 500; note that Wikimedia Foundation wikis allow only 50 for normal users)
-    # [max_results] Maximum total number of results to return
-    # [options] Hash of additional options
-    #
-    # Returns array of page titles (empty if no matches)
-    def search(key, namespaces = nil, limit = @options[:limit], max_results = @options[:max_results], options = {})
-      titles = []
-      offset = 0
-
-      form_data = options.merge(
-        'action'   => 'query',
-        'list'     => 'search',
-        'srwhat'   => 'text',
-        'srsearch' => key,
-        'srlimit'  => limit
-      )
-
-      if namespaces
-        namespaces = [ namespaces ] unless namespaces.kind_of? Array
-        form_data['srnamespace'] = namespaces.map! do |ns| namespaces_by_prefix[ns] end.join('|')
-      end
-
-      begin
-        form_data['sroffset'] = offset if offset
-        form_data['srlimit'] = [limit, max_results - offset.to_i].min
-        res, offset = make_api_request(form_data, '//query-continue/search/@sroffset')
-        titles += REXML::XPath.match(res, "//p").map { |x| x.attributes["title"] }
-      end while offset && offset.to_i < max_results.to_i
-
-      titles
-    end
-
-    # Get a list of users
-    #
-    # [options] Optional hash of options, eg. { 'augroup' => 'sysop' }.  See http://www.mediawiki.org/wiki/API:Allusers
-    #
-    # Returns array of user names (empty if no matches)
-    def users(options = {})
-      iterate_query('allusers', '//u', 'name', 'aufrom', options.merge(
-        'aulimit' => @options[:limit]
-      ))
-    end
-
-    # Get user contributions
-    #
-    # user: The user name
-    # count: Maximum number of contributions to retreive, or nil for all
-    # [options] Optional hash of options, eg. { 'ucnamespace' => 4 }.  See http://www.mediawiki.org/wiki/API:Usercontribs
-    #
-    # Returns array of hashes containing the "item" attributes defined here: http://www.mediawiki.org/wiki/API:Usercontribs
-    def contributions(user, count = nil, options = {})
-      result = []
-
-      iterate_query('usercontribs', '//item', nil, 'uccontinue', options.merge(
-        'ucuser'  => user,
-        'uclimit' => @options[:limit]
-      )) { |element|
-        result << hash = {}
-        element.attributes.each { |key, value| hash[key] = value }
+      @http_options, @wiki_url, @cookies, @headers = http_options, url, {}, {
+        'User-Agent'      => [@options[:user_agent], USER_AGENT].compact.join(' '),
+        'Accept-Encoding' => 'gzip'
       }
-
-      count ? result.take(count) : result
     end
 
-    # Upload a file, or get the status of pending uploads. Several
-    # methods are available:
-    #
-    # * Upload file contents directly.
-    # * Have the MediaWiki server fetch a file from a URL, using the
-    #   "url" parameter
-    #
-    # Requires Mediawiki 1.16+
-    #
-    # Arguments:
-    # * [path] Path to file to upload. Set to nil if uploading from URL.
-    # * [options] Hash of additional options
-    #
-    # Note that queries using session keys must be done in the same login
-    # session as the query that originally returned the key (i.e. do not
-    # log out and then log back in).
-    #
-    # Options:
-    # * 'filename'       - Target filename (defaults to local name if not given), options[:target] is alias for this.
-    # * 'comment'        - Upload comment. Also used as the initial page text for new files if "text" is not specified.
-    # * 'text'           - Initial page text for new files
-    # * 'watch'          - Watch the page
-    # * 'ignorewarnings' - Ignore any warnings
-    # * 'url'            - Url to fetch the file from. Set path to nil if you want to use this.
-    #
-    # Deprecated but still supported options:
-    # * :description     - Description of this file. Used as 'text'.
-    # * :target          - Target filename, same as 'filename'.
-    # * :summary         - Edit summary for history. Used as 'comment'. Also used as 'text' if neither it or :description is specified.
-    #
-    # Examples:
-    #   mw.upload('/path/to/local/file.jpg', 'filename' => "RemoteFile.jpg")
-    #   mw.upload(nil, 'filename' => "RemoteFile2.jpg", 'url' => 'http://remote.com/server/file.jpg')
-    #
-    def upload(path, options={})
-      if options[:description]
-        options['text'] = options[:description]
-        options.delete(:description)
-      end
-
-      if options[:target]
-        options['filename'] = options[:target]
-        options.delete(:target)
-      end
-
-      if options[:summary]
-        options['text'] ||= options[:summary]
-        options['comment'] = options[:summary]
-        options.delete(:summary)
-      end
-
-      options['comment'] ||= "Uploaded by MediaWiki::Gateway"
-      options['file'] = File.new(path) if path
-      full_name = path || options['url']
-      options['filename'] ||= File.basename(full_name) if full_name
-
-      raise ArgumentError.new(
-        "One of the 'file', 'url' or 'sessionkey' options must be specified!"
-      ) unless options['file'] || options['url'] || options['sessionkey']
-
-      form_data = options.merge(
-        'action' => 'upload',
-        'token' => get_token('edit', options['filename'])
-      )
-
-      make_api_request(form_data)
-    end
-
-    # Checks if page is a redirect.
-    #
-    # [page_title] Page title to fetch
-    #
-    # Returns true if the page is a redirect, false if it is not or the page does not exist.
-    def redirect?(page_title)
-      form_data = {'action' => 'query', 'prop' => 'info', 'titles' => page_title}
-      page = make_api_request(form_data).first.elements["query/pages/page"]
-      !!(valid_page?(page) and page.attributes["redirect"])
-    end
-
-    # Get image list for given article[s].  Follows redirects.
-    # 
-    # _article_or_pageid_ is the title or pageid of a single article
-    # _imlimit_ is the maximum number of images to return (defaults to 200)
-    # _options_ is the hash of additional options
-    #
-    # Example:
-    #   images = mw.images('Gaborone')
-    # _images_ would contain ['File:Gaborone at night.jpg', 'File:Gaborone2.png', ...]
-    def images(article_or_pageid, imlimit = 200, options = {})
-      form_data = options.merge(
-        'action'    => 'query',
-        'prop'      => 'images',
-        'imlimit'   => imlimit,
-        'redirects' => true
-      )
-
-      case article_or_pageid
-      when Fixnum
-        form_data['pageids'] = article_or_pageid
-      else
-        form_data['titles'] = article_or_pageid
-      end
-      xml, _ = make_api_request(form_data)
-      page = xml.elements["query/pages/page"]
-      if valid_page? page
-        if xml.elements["query/redirects/r"]
-          # We're dealing with redirect here.
-          images(page.attributes["pageid"].to_i, imlimit)
-        else
-          REXML::XPath.match(page, "images/im").map { |x| x.attributes["title"] }
-        end
-      else
-        nil
-      end
-    end
-
-    # Get list of interlanguage links for given article[s].  Follows redirects.  Returns a hash like { 'id' => 'Yerusalem', 'en' => 'Jerusalem', ... }
-    # 
-    # _article_or_pageid_ is the title or pageid of a single article
-    # _lllimit_ is the maximum number of langlinks to return (defaults to 500, the maximum)
-    # _options_ is the hash of additional options
-    #
-    # Example:
-    #   langlinks = mw.langlinks('Jerusalem')
-    def langlinks(article_or_pageid, lllimit = 500, options = {})
-      form_data = options.merge(
-        'action'    => 'query',
-        'prop'      => 'langlinks',
-        'lllimit'   => lllimit,
-        'redirects' => true
-      )
+    attr_reader :log, :wiki_url, :cookies, :headers
 
-      case article_or_pageid
-      when Fixnum
-        form_data['pageids'] = article_or_pageid
-      else
-        form_data['titles'] = article_or_pageid
-      end
-      xml, _ = make_api_request(form_data)
-      page = xml.elements["query/pages/page"]
-      if valid_page? page
-        if xml.elements["query/redirects/r"]
-          # We're dealing with the redirect here.
-          langlinks(page.attributes["pageid"].to_i, lllimit)
-        else
-          langl = REXML::XPath.match(page, 'langlinks/ll')
-          if langl.nil?
-            nil
-          else
-            links = {}
-            langl.each{ |ll| links[ll.attributes["lang"]] = ll.children[0].to_s } 
-            return links
-          end
-        end
-      else
-        nil
-      end
-    end
-
-    # Convenience wrapper for _langlinks_ returning the title in language _lang_ (ISO code) for a given article of pageid, if it exists, via the interlanguage link 
-    # 
-    # Example:
-    #
-    #  langlink = mw.langlink_for_lang('Tycho Brahe', 'de')
-    def langlink_for_lang(article_or_pageid, lang)
-      return langlinks(article_or_pageid)[lang]
-    end
-
-    # Requests image info from MediaWiki. Follows redirects.
-    #
-    # _file_name_or_page_id_ should be either:
-    # * a file name (String) you want info about without File: prefix.
-    # * or a Fixnum page id you of the file.
-    #
-    # _options_ is +Hash+ passed as query arguments. See
-    # http://www.mediawiki.org/wiki/API:Query_-_Properties#imageinfo_.2F_ii
-    # for more information.
-    #
-    # options['iiprop'] should be either a string of properties joined by
-    # '|' or an +Array+ (or more precisely something that responds to #join).
-    #
-    # +Hash+ like object is returned where keys are image properties.
-    #
-    # Example:
-    #   mw.image_info(
-    #     "Trooper.jpg", 'iiprop' => ['timestamp', 'user']
-    #   ).each do |key, value|
-    #     puts "#{key.inspect} => #{value.inspect}"
-    #   end
-    #
-    # Output:
-    #   "timestamp" => "2009-10-31T12:59:11Z"
-    #   "user" => "Valdas"
-    #
-    def image_info(file_name_or_page_id, options={})
-      options['iiprop'] = options['iiprop'].join('|') \
-        if options['iiprop'].respond_to?(:join)
-      form_data = options.merge(
-        'action' => 'query',
-        'prop' => 'imageinfo',
-        'redirects' => true
-      )
-
-      case file_name_or_page_id
-      when Fixnum
-        form_data['pageids'] = file_name_or_page_id
-      else
-        form_data['titles'] = "File:#{file_name_or_page_id}"
-      end
-
-      xml, _ = make_api_request(form_data)
-      page = xml.elements["query/pages/page"]
-      if valid_page? page
-        if xml.elements["query/redirects/r"]
-          # We're dealing with redirect here.
-          image_info(page.attributes["pageid"].to_i, options)
-        else
-          page.elements["imageinfo/ii"].attributes
-        end
-      else
-        nil
-      end
-    end
-
-    # Download _file_name_ (without "File:" or "Image:" prefix). Returns file contents. All options are passed to
-    # #image_info however options['iiprop'] is forced to url. You can still
-    # set other options to control what file you want to download.
-    def download(file_name, options={})
-      options['iiprop'] = 'url'
-
-      attributes = image_info(file_name, options)
-      if attributes
-        RestClient.get attributes['url']
-      else
-        nil
-      end
-    end
-
-    # Imports a MediaWiki XML dump
-    #
-    # [xml] String or array of page names to fetch
-    # [options] Hash of additional options
-    #
-    # Returns XML array <api><import><page/><page/>...
-    # <page revisions="1"> (or more) means successfully imported
-    # <page revisions="0"> means duplicate, not imported
-    def import(xmlfile, options = {})
-      make_api_request(options.merge(
-        'action'  => 'import',
-        'xml'     => File.new(xmlfile),
-        'token'   => get_token('import', 'Main Page'), # NB: dummy page name
-        'format'  => 'xml'
-      ))
-    end
-
-    # Exports a page or set of pages
-    #
-    # [page_titles] String or array of page titles to fetch
-    # [options] Hash of additional options
-    #
-    # Returns MediaWiki XML dump
-    def export(page_titles, options = {})
-      make_api_request(options.merge(
-        'action'       => 'query',
-        'titles'       => Array(page_titles).join('|'),
-        'export'       => nil,
-        'exportnowrap' => nil
-      )).first
-    end
-
-    # Get the wiki's siteinfo as a hash. See http://www.mediawiki.org/wiki/API:Siteinfo.
-    #
-    # [options] Hash of additional options
-    def siteinfo(options = {})
-      res = make_api_request(options.merge(
-        'action' => 'query',
-        'meta'   => 'siteinfo'
-      )).first
-
-      REXML::XPath.first(res, '//query/general')
-        .attributes.each_with_object({}) { |(k, v), h| h[k] = v }
-    end
-
-    # Get the wiki's MediaWiki version.
-    #
-    # [options] Hash of additional options passed to #siteinfo
-    def version(options = {})
-      siteinfo(options).fetch('generator', '').split.last
-    end
-
-    # Get a list of all known namespaces
-    #
-    # [options] Hash of additional options
-    #
-    # Returns array of namespaces (name => id)
-    def namespaces_by_prefix(options = {})
-      res = make_api_request(options.merge(
-        'action' => 'query',
-        'meta'   => 'siteinfo',
-        'siprop' => 'namespaces'
-      )).first
-
-      REXML::XPath.match(res, "//ns").inject(Hash.new) do |namespaces, namespace|
-        prefix = namespace.attributes["canonical"] || ""
-        namespaces[prefix] = namespace.attributes["id"].to_i
-        namespaces
-      end
-    end
-
-    # Get a list of all installed (and registered) extensions
-    #
-    # [options] Hash of additional options
-    #
-    # Returns array of extensions (name => version)
-    def extensions(options = {})
-      res = make_api_request(options.merge(
-        'action' => 'query',
-        'meta'   => 'siteinfo',
-        'siprop' => 'extensions'
-      )).first
-
-      REXML::XPath.match(res, "//ext").inject(Hash.new) do |extensions, extension|
-        name = extension.attributes["name"] || ""
-        extensions[name] = extension.attributes["version"]
-        extensions
-      end
-    end
-
-    # Sends e-mail to a user
-    #
-    # [user] Username to send mail to (name only: eg. 'Bob', not 'User:Bob')
-    # [subject] Subject of message
-    # [content] Content of message
-    # [options] Hash of additional options
-    #
-    # Will raise a 'noemail' APIError if the target user does not have a confirmed email address, see http://www.mediawiki.org/wiki/API:E-mail for details.
-    def email_user(user, subject, text, options = {})
-      res = make_api_request(options.merge(
-        'action'  => 'emailuser',
-        'target'  => user,
-        'subject' => subject,
-        'text'    => text,
-        'token'   => get_token('email', "User:#{user}")
-      )).first
-
-      res.elements['emailuser'].attributes['result'] == 'Success'
-    end
-
-    # Execute Semantic Mediawiki query
-    #
-    # [query] Semantic Mediawiki query
-    # [params] Array of additional parameters or options, eg. mainlabel=Foo or ?Place (optional)
-    # [options] Hash of additional options
-    #
-    # Returns result as an HTML string
-    def semantic_query(query, params = [], options = {})
-      unless smw_version = extensions['Semantic MediaWiki']
-        raise MediaWiki::Exception, 'Semantic MediaWiki extension not installed.'
-      end
-
-      if smw_version.to_f >= 1.7
-        make_api_request(options.merge(
-          'action' => 'ask',
-          'query'  => "#{query}|#{params.join('|')}"
-        )).first
-      else
-        make_api_request(options.merge(
-          'action' => 'parse',
-          'prop'   => 'text',
-          'text'   => "{{#ask:#{query}|#{params.push('format=list').join('|')}}}"
-        )).first.elements['parse/text'].text
-      end
-    end
-
-    # Create a new account
-    #
-    # [options] is +Hash+ passed as query arguments. See https://www.mediawiki.org/wiki/API:Account_creation#Parameters for more information.
-    def create_account(options)
-      make_api_request(options.merge('action' => 'createaccount')).first
-    end
-
-    # Sets options for currenlty logged in user
-    # 
-    # [changes] a +Hash+ that will be transformed into an equal sign and pipe-separated key value parameter
-    # [optionname] a +String+ indicating which option to change (optional)
-    # [optionvalue] the new value for optionname - allows pipe characters (optional)
-    # [reset] a +Boolean+ indicating if all preferences should be reset to site defaults (optional)
-    # [options] Hash of additional options
-    def options(changes = {}, optionname = nil, optionvalue = nil, reset = false, options = {})
-      form_data = options.merge(
-        'action' => 'options',
-        'token'  => get_options_token
-      )
-
-      if changes.present?
-        form_data['change'] = changes.map { |key, value| "#{key}=#{value}" }.join('|')
-      end
-
-      if optionname.present?
-        form_data[optionname] = optionvalue
-      end
-
-      if reset
-        form_data['reset'] = true
-      end
-
-      make_api_request(form_data).first
-    end
-
-    # Set groups for a user
+    # Make generic request to API
     #
-    # [user] Username of user to modify
-    # [groups_to_add] Groups to add user to, as an array or a string if a single group (optional)
-    # [groups_to_remove] Groups to remove user from, as an array or a string if a single group (optional)
-    # [options] Hash of additional options
-    def set_groups(user, groups_to_add = [], groups_to_remove = [], comment = '', options = {})
-      token = get_userrights_token(user)
-      userrights(user, token, groups_to_add, groups_to_remove, comment, options)
-    end
-
-    # Review current revision of an article (requires FlaggedRevisions extension, see http://www.mediawiki.org/wiki/Extension:FlaggedRevs)
+    # [form_data] hash of attributes to post
+    # [continue_xpath] XPath selector for query continue parameter
     #
-    # [title] Title of article to review
-    # [flags] Hash of flags and values to set, eg. { "accuracy" => "1", "depth" => "2" }
-    # [comment] Comment to add to review (optional)
-    # [options] Hash of additional options
-    def review(title, flags, comment = "Reviewed by MediaWiki::Gateway", options = {})
-      raise APIError.new('missingtitle', "Article #{title} not found") unless revid = revision(title)
-
-      form_data = options.merge(
-        'action'  => 'review',
-        'revid'   => revid,
-        'token'   => get_token('edit', title),
-        'comment' => comment
-      )
-
-      flags.each { |k, v| form_data["flag_#{k}"] = v }
-
-      make_api_request(form_data).first
+    # Returns XML document
+    def send_request(form_data, continue_xpath = nil)
+      make_api_request(form_data, continue_xpath).first
     end
 
     private
 
     # Fetch token (type 'delete', 'edit', 'email', 'import', 'move', 'protect')
     def get_token(type, page_titles)
-      form_data = {'action' => 'query', 'prop' => 'info', 'intoken' => type, 'titles' => page_titles}
-      res, _ = make_api_request(form_data)
-      token = res.elements["query/pages/page"].attributes[type + "token"]
-      raise Unauthorized.new "User is not permitted to perform this operation: #{type}" if token.nil?
-      token
-    end
+      res = send_request(
+        'action'  => 'query',
+        'prop'    => 'info',
+        'intoken' => type,
+        'titles'  => page_titles
+      )
 
-    def get_undelete_token(page_titles)
-      form_data = {'action' => 'query', 'list' => 'deletedrevs', 'prop' => 'info', 'drprop' => 'token', 'titles' => page_titles}
-      res, _ = make_api_request(form_data)
-      if res.elements["query/deletedrevs/page"]
-        token = res.elements["query/deletedrevs/page"].attributes["token"]
-        raise Unauthorized.new "User is not permitted to perform this operation: #{type}" if token.nil?
-        token
-      else
-        nil
-      end
-    end
-
-    # User rights management (aka group assignment)
-    def get_userrights_token(user)
-      form_data = {'action' => 'query', 'list' => 'users', 'ustoken' => 'userrights', 'ususers' => user}
-      res, _ = make_api_request(form_data)
-      token = res.elements["query/users/user"].attributes["userrightstoken"]
-
-      @log.debug("RESPONSE: #{res.to_s}")
-      if token.nil?
-        if res.elements["query/users/user"].attributes["missing"]
-          raise APIError.new('invaliduser', "User '#{user}' was not found (get_userrights_token)")
-        else
-          raise Unauthorized.new "User '#{@username}' is not permitted to perform this operation: get_userrights_token"
-        end
+      unless token = res.elements['query/pages/page'].attributes[type + 'token']
+        raise Unauthorized.new "User is not permitted to perform this operation: #{type}"
       end
 
       token
     end
 
-    def get_options_token
-      form_data = { 'action' => 'tokens', 'type' => 'options' }
-      res, _ = make_api_request(form_data)
-      res.elements['tokens'].attributes['optionstoken']
-    end
-
-    def userrights(user, token, groups_to_add, groups_to_remove, reason, options = {})
-      # groups_to_add and groups_to_remove can be a string or an array. Turn them into MediaWiki's pipe-delimited list format.
-      if groups_to_add.is_a? Array
-        groups_to_add = groups_to_add.join('|')
-      end
-
-      if groups_to_remove.is_a? Array
-        groups_to_remove = groups_to_remove.join('|')
-      end
-
-      make_api_request(options.merge(
-        'action' => 'userrights',
-        'user'   => user,
-        'token'  => token,
-        'add'    => groups_to_add,
-        'remove' => groups_to_remove,
-        'reason' => reason
-      )).first
-    end
-
-
-    # Make a custom query
-    #
-    # [options] query options
-    #
-    # Returns the REXML::Element object as result
-    #
-    # Example:
-    #   def creation_time(pagename)
-    #     res = bot.custom_query(:prop => :revisions,
-    #                            :titles => pagename,
-    #                            :rvprop => :timestamp,
-    #                            :rvdir => :newer,
-    #                            :rvlimit => 1)
-    #     timestr = res.get_elements('*/*/*/rev')[0].attribute('timestamp').to_s
-    #     time.parse(timestr)
-    #   end
-    #
-    def custom_query(options)
-      form_data = {}
-      options.each {|k,v| form_data[k.to_s] = v.to_s }
-      form_data['action'] = 'query'
-      make_api_request(form_data).first.elements['query']
-    end
-
     # Iterate over query results
     #
     # [list] list name to query
@@ -967,37 +119,39 @@ module MediaWiki
 
     # Make generic request to API
     #
-    # [form_data] hash or string of attributes to post
+    # [form_data] hash of attributes to post
     # [continue_xpath] XPath selector for query continue parameter
     # [retry_count] Counter for retries
     #
-    # Returns XML document
-    def make_api_request(form_data, continue_xpath=nil, retry_count=1)
-      if form_data.kind_of? Hash
-        form_data['format'] = 'xml'
-        form_data['maxlag'] = @options[:maxlag]
-      end
-      http_send(@wiki_url, form_data, @headers.merge({:cookies => @cookies})) do |response, &block|
-        if response.code == 503 and retry_count < @options[:retry_count]
+    # Returns array of XML document and query continue parameter.
+    def make_api_request(form_data, continue_xpath = nil, retry_count = 1)
+      form_data.update('format' => 'xml', 'maxlag' => @options[:maxlag])
+
+      http_send(@wiki_url, form_data, @headers.merge(cookies: @cookies)) { |response, &block|
+        if response.code == 503 && retry_count < @options[:retry_count]
           log.warn("503 Service Unavailable: #{response.body}.  Retry in #{@options[:retry_delay]} seconds.")
-          sleep @options[:retry_delay]
+          sleep(@options[:retry_delay])
           make_api_request(form_data, continue_xpath, retry_count + 1)
         end
+
         # Check response for errors and return XML
-        raise MediaWiki::Exception.new "Bad response: #{response}" unless response.code >= 200 and response.code < 300
+        unless response.code >= 200 && response.code < 300
+          raise MediaWiki::Exception.new("Bad response: #{response}")
+        end
+
         doc = get_response(response.dup)
-        action = form_data['action']
 
         # login and createaccount actions require a second request with a token received on the first request
-        if %w(login createaccount).include?(action)
+        if %w[login createaccount].include?(action = form_data['action'])
           action_result = doc.elements[action].attributes['result']
-          @cookies.merge!(response.cookies)
+          @cookies.update(response.cookies)
 
           case action_result.downcase
-            when "success" then
+            when 'success'
               return [doc, false]
-            when "needtoken"
-              token = doc.elements[action].attributes["token"]
+            when 'needtoken'
+              token = doc.elements[action].attributes['token']
+
               if action == 'login'
                 return make_api_request(form_data.merge('lgtoken' => token))
               elsif action == 'createaccount'
@@ -1011,23 +165,21 @@ module MediaWiki
               end
           end
         end
-        continue = (continue_xpath and doc.elements['query-continue']) ? REXML::XPath.first(doc, continue_xpath) : nil
-        return [doc, continue]
-      end
+
+        return [doc, (continue_xpath && doc.elements['query-continue']) ?
+          REXML::XPath.first(doc, continue_xpath) : nil]
+      }
     end
 
     # Execute the HTTP request using either GET or POST as appropriate
     def http_send url, form_data, headers, &block
-      opts = @http_options.merge(:url => url, :headers => headers)
+      opts = @http_options.merge(url: url, headers: headers)
+      opts[:method] = form_data['action'] == 'query' ? :get : :post
+      opts[:method] == :get ? headers[:params] = form_data : opts[:payload] = form_data
 
-      if form_data['action'] == 'query'
-        log.debug("GET: #{form_data.inspect}, #{@cookies.inspect}")
-        headers[:params] = form_data
-        RestClient::Request.execute(opts.update(:method => :get), &block)
-      else
-        log.debug("POST: #{form_data.inspect}, #{@cookies.inspect}")
-        RestClient::Request.execute(opts.update(:method => :post, :payload => form_data), &block)
-      end
+      log.debug("#{opts[:method].upcase}: #{form_data.inspect}, #{@cookies.inspect}")
+
+      RestClient::Request.execute(opts, &block)
     end
 
     # Get API XML response
@@ -1035,41 +187,54 @@ module MediaWiki
     # Otherwise return XML root
     def get_response(res)
       begin
-        res = res.force_encoding("UTF-8") if res.respond_to?(:force_encoding)
+        res = res.force_encoding('UTF-8') if res.respond_to?(:force_encoding)
         doc = REXML::Document.new(res).root
       rescue REXML::ParseException
-        raise MediaWiki::Exception.new "Response is not XML.  Are you sure you are pointing to api.php?"
+        raise MediaWiki::Exception.new('Response is not XML.  Are you sure you are pointing to api.php?')
       end
+
       log.debug("RES: #{doc}")
-      raise MediaWiki::Exception.new "Response does not contain Mediawiki API XML: #{res}" unless [ "api", "mediawiki" ].include? doc.name
-      if doc.elements["error"]
-        code = doc.elements["error"].attributes["code"]
-        info = doc.elements["error"].attributes["info"]
-        raise APIError.new(code, info)
+
+      unless %w[api mediawiki].include?(doc.name)
+        raise MediaWiki::Exception.new("Response does not contain Mediawiki API XML: #{res}")
       end
-      if doc.elements["warnings"]
-        warning("API warning: #{doc.elements["warnings"].children.map {|e| e.text}.join(", ")}")
+
+      if error = doc.elements['error']
+        raise APIError.new(*error.attributes.values_at(*%w[code info]))
       end
+
+      if warnings = doc.elements['warnings']
+        warning("API warning: #{warnings.children.map(&:text).join(', ')}")
+      end
+
       doc
     end
 
+    def validate_options(options, valid_options)
+      options.each_key { |opt|
+        unless valid_options.include?(opt.to_s)
+          raise ArgumentError, "Unknown option '#{opt}'", caller(1)
+        end
+      }
+    end
+
     def valid_page?(page)
-      return false unless page
-      return false if page.attributes["missing"]
-      if page.attributes["invalid"]
-        warning("Invalid title '#{page.attributes["title"]}'")
-      else
-        true
-      end
+      page && !page.attributes['missing'] && (!page.attributes['invalid'] ||
+        warning("Invalid title '#{page.attributes['title']}'"))
     end
 
     def warning(msg)
-      if @options[:ignorewarnings]
-        log.warn(msg)
-        return false
-      else
-        raise APIError.new('warning', msg)
-      end
+      raise APIError.new('warning', msg) unless @options[:ignorewarnings]
+      log.warn(msg)
+      false
     end
+
   end
+
 end
+
+require_relative 'gateway/files'
+require_relative 'gateway/pages'
+require_relative 'gateway/query'
+require_relative 'gateway/site'
+require_relative 'gateway/users'