mediawiki-gateway 0.6.2 → 1.0.0.rc1

data/lib/media_wiki/gateway/query.rb

@@ -0,0 +1,98 @@
+module MediaWiki
+
+  class Gateway
+
+    module Query
+
+      # 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, form_data = [], 0, options.merge(
+          'action'   => 'query',
+          'list'     => 'search',
+          'srwhat'   => 'text',
+          'srsearch' => key,
+          'srlimit'  => limit
+        )
+
+        if namespaces
+          form_data['srnamespace'] = Array(namespaces).map! { |ns|
+            namespaces_by_prefix[ns]
+          }.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
+
+      # 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
+          send_request(options.merge(
+            'action' => 'ask',
+            'query'  => "#{query}|#{params.join('|')}"
+          ))
+        else
+          send_request(options.merge(
+            'action' => 'parse',
+            'prop'   => 'text',
+            'text'   => "{{#ask:#{query}|#{params.push('format=list').join('|')}}}"
+          )).elements['parse/text'].text
+        end
+      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 }
+        send_request(form_data.merge('action' => 'query')).elements['query']
+      end
+
+    end
+
+    include Query
+
+  end
+
+end

data/lib/media_wiki/gateway/site.rb

@@ -0,0 +1,101 @@
+module MediaWiki
+
+  class Gateway
+
+    module Site
+
+      # 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 = {})
+        send_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 = {})
+        send_request(options.merge(
+          'action'       => 'query',
+          'titles'       => Array(page_titles).join('|'),
+          'export'       => nil,
+          'exportnowrap' => nil
+        ))
+      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 = send_request(options.merge(
+          'action' => 'query',
+          'meta'   => 'siteinfo'
+        ))
+
+        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 = send_request(options.merge(
+          'action' => 'query',
+          'meta'   => 'siteinfo',
+          'siprop' => 'namespaces'
+        ))
+
+        REXML::XPath.match(res, '//ns').each_with_object({}) { |namespace, namespaces|
+          prefix = namespace.attributes['canonical'] || ''
+          namespaces[prefix] = namespace.attributes['id'].to_i
+        }
+      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 = send_request(options.merge(
+          'action' => 'query',
+          'meta'   => 'siteinfo',
+          'siprop' => 'extensions'
+        ))
+
+        REXML::XPath.match(res, '//ext').each_with_object({}) { |extension, extensions|
+          name = extension.attributes['name'] || ''
+          extensions[name] = extension.attributes['version']
+        }
+      end
+
+    end
+
+    include Site
+
+  end
+
+end

data/lib/media_wiki/gateway/users.rb

@@ -0,0 +1,182 @@
+module MediaWiki
+
+  class Gateway
+
+    module Users
+
+      # 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 = {})
+        send_request(options.merge(
+          'action'     => 'login',
+          'lgname'     => username,
+          'lgpassword' => password,
+          'lgdomain'   => domain
+        ))
+
+        @password = password
+        @username = username
+      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 }
+        }
+
+        count ? result.take(count) : result
+      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 = send_request(options.merge(
+          'action'  => 'emailuser',
+          'target'  => user,
+          'subject' => subject,
+          'text'    => text,
+          'token'   => get_token('email', "User:#{user}")
+        ))
+
+        res.elements['emailuser'].attributes['result'] == 'Success'
+      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)
+        send_request(options.merge('action' => 'createaccount'))
+      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 && !changes.empty?
+          form_data['change'] = changes.map { |key, value| "#{key}=#{value}" }.join('|')
+        end
+
+        if optionname && !optionname.empty?
+          form_data[optionname] = optionvalue
+        end
+
+        if reset
+          form_data['reset'] = true
+        end
+
+        send_request(form_data)
+      end
+
+      # Set groups for a user
+      #
+      # [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
+
+      private
+
+      # User rights management (aka group assignment)
+      def get_userrights_token(user)
+        res = send_request(
+          'action'  => 'query',
+          'list'    => 'users',
+          'ustoken' => 'userrights',
+          'ususers' => user
+        )
+
+        token = res.elements['query/users/user'].attributes['userrightstoken']
+
+        @log.debug("RESPONSE: #{res.to_s}")
+
+        unless token
+          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
+        end
+
+        token
+      end
+
+      def get_options_token
+        send_request('action' => 'tokens', 'type' => 'options')
+          .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
+
+        send_request(options.merge(
+          'action' => 'userrights',
+          'user'   => user,
+          'token'  => token,
+          'add'    => groups_to_add,
+          'remove' => groups_to_remove,
+          'reason' => reason
+        ))
+      end
+
+    end
+
+    include Users
+
+  end
+
+end

data/lib/media_wiki/utils.rb

@@ -1,5 +1,6 @@
 module MediaWiki
-  class << self
+
+  module Utils
 
     # Extract base name.  If there are no subpages, return page name.
     #
@@ -7,7 +8,7 @@ module MediaWiki
     # get_base_name("Namespace:Foo/Bar/Baz") -> "Namespace:Foo"
     # get_base_name("Namespace:Foo") -> "Namespace:Foo"
     #
-    # [title] Page name string in Wiki format 
+    # [title] Page name string in Wiki format
     def get_base_name(title)
       title.split('/').first if title
     end
@@ -18,10 +19,9 @@ module MediaWiki
     # get_path_to_subpage("Namespace:Foo/Bar/Baz") -> "Namespace:Foo/Bar"
     # get_path_to_subpage("Namespace:Foo") -> nil
     #
-    # [title] Page name string in Wiki format 
+    # [title] Page name string in Wiki format
     def get_path_to_subpage(title)
-      return nil unless title and title.include? '/'
-      title.split(/\/([^\/]*)$/).first
+      title.split(/\/([^\/]*)$/).first if title && title.include?('/')
     end
 
     # Extract subpage name.  If there is no hierarchy above, return page name.
@@ -30,7 +30,7 @@ module MediaWiki
     # get_subpage("Namespace:Foo/Bar/Baz") -> "Baz"
     # get_subpage("Namespace:Foo") -> "Namespace:Foo"
     #
-    # [title] Page name string in Wiki format 
+    # [title] Page name string in Wiki format
     def get_subpage(title)
       title.split('/').last if title
     end
@@ -42,24 +42,58 @@ module MediaWiki
     def uri_to_wiki(uri)
       upcase_first_char(CGI.unescape(uri).tr('_', ' ').tr('#<>[]|{}', '')) if uri
     end
-    
+
     # Convert a Wiki page name ("Getting there & away") to URI-safe format ("Getting_there_%26_away"),
     # taking care not to mangle slashes or colons
     # [wiki] Page name string in Wiki format
     def wiki_to_uri(wiki)
-      wiki.to_s.split('/').map {|chunk| CGI.escape(CGI.unescape(chunk).tr(' ', '_')) }.join('/').gsub('%3A', ':') if wiki
+      wiki.to_s.split('/').map { |chunk|
+        CGI.escape(CGI.unescape(chunk).tr(' ', '_'))
+      }.join('/').gsub('%3A', ':') if wiki
     end
 
     # Return current version of MediaWiki::Gateway
     def version
       MediaWiki::VERSION
     end
-    
+
     private
-    
-    def upcase_first_char(str)
-      [ ActiveSupport::Multibyte::Chars.new(str.mb_chars.slice(0,1)).upcase.to_s, str.mb_chars.slice(1..-1) ].join
+
+    NO_UNICODE_SUPPORT = begin
+      require 'unicode'
+    rescue LoadError
+      begin
+        require 'active_support/core_ext/string/multibyte'
+      rescue LoadError
+        warn 'mediawiki-gateway: For better Unicode support,' <<
+             " install the `unicode' or `activesupport' gem."
+
+        def upcase_first_char(str)
+          first, rest = str.slice(0, 1), str.slice(1..-1)
+          [first.upcase, rest].join
+        end
+
+        'No Unicode support'
+      else
+        def upcase_first_char(str)
+          mb_str = str.mb_chars
+          first, rest = mb_str.slice(0, 1), mb_str.slice(1..-1)
+          [ActiveSupport::Multibyte::Chars.new(first).upcase.to_s, rest].join
+        end
+
+        nil
+      end
+    else
+      def upcase_first_char(str)
+        first, rest = str.slice(0, 1), str.slice(1..-1)
+        [Unicode.upcase(first), rest].join
+      end
+
+      nil
     end
+
   end
-  
+
+  extend Utils
+
 end