riki 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in riki.gemspec
+gemspec
+
+group :test do
+  gem "rake"
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Nicholas E. Rabenau
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# Riki
+
+`riki` is a MediaWiki client written in Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'riki'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install riki
+
+## Usage
+### Working with Wikipedia
+
+    # Optional - this step is only required if you are working with a non-english Wikipedia
+    Riki.url = 'http://de.wikipedia.org/w/api.php'
+
+    # find a page
+    ruby = Riki::Page.find('Ruby')
+    
+    # query its properties
+    ruby.last_modified # some date
+
+### Working with a custom MediaWiki installation that requires authentication
+    
+    # Tell riki where to  to use
+    Riki.url = 'http://example.com/wiki/api.php'
+    Riki.username = 'jon_doe'
+    Riki.password = 's3cret'
+
+    # everything else is the same as above
+
+## Commandline Client
+
+`riki` comes with a simple command-line app that takes one or more titles of wikipedia pages and prints the Wikipedia page as plain text to STDOUT. Additional tools can be chained, e.g. `fmt` can be used to achieve word wrapping:
+
+    riki "Sinatra_(software)" | fmt -w $COLUMNS
+
+## Troubleshooting
+
+Riki uses [RestClient](http://github.com/archiloque/rest-client) under the hood, to the simplest way to understand what goes wrong is to turn on logging for RestClient. For the bin script, the simplest way to achieve that is to set the appropriate environment variable:
+
+    RESTCLIENT_LOG=stdout riki Ruby
+    
+This command will invove the `riki` script with RestClient's logging set to STDOUT.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.test_files = FileList["test/**/*.rb"].exclude("test/test_helper.rb")
+  test.verbose = false
+  test.warning = false
+end

data/TODO.md

@@ -0,0 +1,3 @@
+* Revisions class. Multiple revisions are part of a page; page content reader takes an optional revision parameter (defaults to latest)
+* Find a page by id
+* Handle MediaWiki redirects

data/bin/riki

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+require 'bundler'
+Bundler.require
+require 'active_support'
+
+include Riki
+
+prefs = Preferences::User.load(File.basename($0))
+Riki::Base.url = prefs[:url] if prefs[:url] # prevent overriding with nil
+
+# These may be nil. If present, all operations will occur under this account
+Riki::Base.username = prefs[:username]
+Riki::Base.password = prefs[:password]
+Riki::Base.domain = prefs[:domain]
+Riki::Base.cache = ActiveSupport::Cache::FileStore.new(File.expand_path(File.join('~', '.cache', File.basename($0))))
+
+if ARGV.empty?
+  STDERR.puts "Error: Missing page title. Usage: #{$0} TITLE [TITLE]*"
+  exit 1
+end
+
+begin
+  results = Page.find_by_title(ARGV)
+rescue PageNotFound
+  STDERR.puts $!
+  exit 2
+rescue PageInvalid
+  STDERR.puts $!
+  exit 3
+end
+
+if results.empty?
+  STDERR.puts "No pages found for '#{ARGV.join(' ')}'"
+  exit 4
+else
+  results.each{|page|
+    puts page.to_s
+    STDERR.puts "Page #{page.title} last modified #{page.last_modified}"
+  }
+end

data/bin/riki-prefs

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'bundler'
+Bundler.require
+
+NAMESPACE = 'riki'
+
+options = Preferences::User.load!(NAMESPACE)
+
+verbose = false
+dirty = false
+
+def set_or_delete(options, key, value)
+  if value
+    options[key] = value
+  else
+    options.delete(key)
+  end
+end
+
+option_parser = OptionParser.new do |opts|
+  opts.on('-v', '--verbose') do 
+    verbose = true
+  end
+  
+  opts.on('-h', '--help') do 
+    STDERR.puts "#{File.basename($0)} writes preferences for #{NAMESPACE}, the Ruby library for MediaWiki"
+    exit(1)
+  end
+  
+  opts.on('-m [URL]', '--url [URL]') do |url| 
+    set_or_delete(options, :url, url)
+    dirty = true
+  end
+  
+  opts.on('-u [USER]', '--user [USER]') do |user| 
+    set_or_delete(options, :username, user)
+    dirty = true
+  end
+  
+  opts.on('-p [PASSWORD]', '--password [PASSWORD]') do |password| 
+    set_or_delete(options, :password, password)
+    dirty = true
+  end
+  
+  opts.on('-d [DOMAIN]', '--domain [DOMAIN]') do |domain| 
+    set_or_delete(options, :domain, domain)
+    dirty = true
+  end
+end
+
+option_parser.parse!
+
+STDERR.puts "Loaded user preferences from #{Preferences::User.user_preferences_file(NAMESPACE)}" if verbose
+
+if !dirty
+  puts options.inspect # dump if called without args
+else
+  STDERR.puts "Saving modified user preferences to #{Preferences::User.user_preferences_file(NAMESPACE)}" if verbose
+  Preferences::User.save!(options, NAMESPACE)
+  puts Preferences::User.load!(NAMESPACE).inspect if verbose
+end

data/lib/preferences/base.rb

@@ -0,0 +1,42 @@
+require 'yaml'
+
+module Preferences
+  def self.load(file_name)
+    YAML::load_file(file_name)
+  end
+
+  def self.save(attribs, file_name)
+    File.open(file_name, 'w') do |out|
+      YAML::dump(attribs, out)
+    end
+  end
+
+  module User
+    FILE_NAME = 'preferences.yaml'
+    
+    def self.load!(namespace)
+      Preferences.load(user_preferences_file(namespace))
+    end
+
+    def self.load(namespace)
+      begin
+        self.load!(namespace)
+      rescue
+        {}
+      end
+    end
+    
+    def self.save!(attribs, namespace)
+      FileUtils.makedirs(user_preferences_path(namespace))
+      Preferences.save(attribs, user_preferences_file(namespace))
+    end
+    
+    def self.user_preferences_path(namespace)
+      File.expand_path(File.join('~', '.config', namespace))
+    end
+    
+    def self.user_preferences_file(namespace)
+      File.join(user_preferences_path(namespace), FILE_NAME)
+    end
+  end
+end

data/lib/riki.rb

@@ -0,0 +1,9 @@
+require 'riki/version'
+require 'riki/errors'
+require 'riki/base'
+require 'riki/page'
+
+require 'preferences/base'
+
+module Riki
+end

data/lib/riki/base.rb

@@ -0,0 +1,145 @@
+require 'rest_client'
+require 'xml'
+require 'active_support'
+
+module Riki
+  class Base
+    class << self
+      attr_accessor :username, :password, :domain, :url
+      attr_writer :cache
+
+      def url
+        @url ||= 'http://en.wikipedia.org/w/api.php'
+      end
+
+      HEADERS = {'User-Agent' => "Riki/v#{Riki::VERSION}"}
+
+      DEFAULT_OPTIONS = {:limit => 500,
+                         :maxlag => 5,
+                         :retry_count => 3,
+                         :retry_delay => 10}
+
+      def cache
+        @cache ||= ActiveSupport::Cache::NullStore.new
+      end
+
+      def find_by_id(ids)
+        expects_array = ids.first.kind_of?(Array)
+        return ids.first if expects_array && ids.first.empty?
+
+        ids = ids.flatten.compact.uniq
+
+        case ids.size
+          when 0
+            raise NotFoundError, "Couldn't find #{name} without an ID"
+          when 1
+           result = find_one(ids.first)
+           expects_array ? [ result ] : result
+         else
+           find_some(ids)
+        end
+      end
+
+      #
+      # Login to MediaWiki
+      #
+      def login
+        raise "No authentication information provided" if Riki::Base.username.nil? || Riki::Base.password.nil?
+        api_request({'action' => 'login', 'lgname' => Riki::Base.username, 'lgpassword' => Riki::Base.password, 'lgdomain' => Riki::Base.domain})
+      end
+
+      # Generic API request to API
+      #
+      # [form_data] hash or string of attributes to post
+      # [continue_xpath] XPath selector for query continue parameter
+      # [retry_count] Counter for retries
+      #
+      # Returns XML document
+      def api_request(form_data, continue_xpath = nil, retry_count = 1, p_options = {})
+        if (!cookies.blank? && cookies["#{cookieprefix}_session"])
+          # Attempt to re-use cookies
+        else
+          # there is no session, we are not currently trying to login, and we gave sufficient auth information
+          login if form_data['action'] != 'login' && !Riki::Base.username.blank? && !Riki::Base.password.blank?
+        end
+
+        options = DEFAULT_OPTIONS.merge(p_options)
+
+        if form_data.kind_of? Hash
+          form_data['format'] = 'xml'
+          form_data['maxlag'] = options[:maxlag]
+          form_data['includexmlnamespace'] = 'true'
+        end
+
+        RestClient.post(Riki::Base.url, form_data, HEADERS.merge({:cookies => cookies})) do |response, &block|
+          if response.code == 503 and retry_count < options[:retry_count]
+            log.warn("503 Service Unavailable: #{response.body}.  Retry in #{options[:retry_delay]} seconds.")
+            sleep(options[:retry_delay])
+            api_request(form_data, continue_xpath, retry_count + 1)
+          end
+
+          # Check response for errors and return XML
+          raise "Bad response: #{response}" unless response.code >= 200 and response.code < 300
+
+          doc = parse_response(response.dup)
+
+          # TODO Handle MediaWiki redirects
+
+          if(form_data['action'] == 'login')
+            login_result = doc.find_first('m:login')['result']
+            Riki::Base.cookieprefix = doc.find_first('m:login')['cookieprefix']
+
+            @cookies.merge!(response.cookies)
+            case login_result
+              when "Success"   then Riki::Base.cache.write(cache_key(:cookies), @cookies)
+              when "NeedToken" then api_request(form_data.merge('lgtoken' => doc.find('/m:api/m:login').first['token']))
+              else raise Unauthorized.new("Login failed: " + login_result)
+            end
+          end
+          continue = (continue_xpath and doc.find('m:query-continue').empty?) ? doc.find_first(continue_xpath).value : nil
+
+          return [doc, continue]
+        end
+      end
+
+      def parse_response(res)
+        res = res.force_encoding("UTF-8") if res.respond_to?(:force_encoding)
+        doc = XML::Parser.string(res).parse.root
+        doc.namespaces.default_prefix = 'm'
+
+        raise "Response does not contain Mediawiki API XML: #{res}" unless ["api", "mediawiki"].include? doc.name
+
+        errors = doc.find('/api/error')
+        if errors.any?
+          code = errors.first["code"]
+          info = errors.first["info"]
+          raise RikiError.lookup(code).new(info)
+        end
+
+        if warnings = doc.find('warnings') && warnings
+          warning("API warning: #{warnings.map{|e| e.text}.join(", ")}")
+        end
+
+        doc
+      end
+
+      def cache_key(key)
+        "#{Riki::Base.url}##{key}"
+      end
+
+      def cookies
+        @cookies ||= Riki::Base.cache.fetch(cache_key(:cookies)) do
+          {}
+        end
+      end
+
+      def cookieprefix
+        @cookieprefix ||= Riki::Base.cache.read(cache_key(:cookieprefix))
+      end
+
+      def cookieprefix=(cp)
+        @cookieprefix ||= Riki::Base.cache.write(cache_key(:cookieprefix), cp)
+      end
+    end
+  end
+end

data/lib/riki/errors.rb

@@ -0,0 +1,46 @@
+module Riki
+  # = Riki Errors
+  #
+  # Generic Riki exception class.
+  class RikiError < StandardError
+    class << self
+      def lookup(code)
+        ERRORS[code.to_sym] || RikiError
+      end
+    end
+  end
+
+  # Raised when the authorization information was present, but was not sufficient to complete the request
+  class Unauthorized < RikiError #:nodoc:
+  end
+
+  # Raised when an object cannot be found with the query parameters supplied
+  class NotFound < RikiError #:nodoc:
+    attr_reader :title
+
+    def initialize(message, title)
+      super(message)
+      @title = title
+    end
+  end
+
+  # Raised when a page that was searched for could not be found
+  class PageNotFound < NotFound #:nodoc:
+    def initialize(title)
+      super("Could not find a page named '#{title}'", title)
+    end
+  end
+
+  # Raised when a page that was searched for is not a valid
+  class PageInvalid < NotFound #:nodoc:
+    def initialize(title)
+      super("The page title '#{title}' is not valid", title)
+    end
+  end
+
+  class RikiError < StandardError
+    ERRORS = {
+      :readapidenied => Unauthorized
+    }
+  end
+end