wayback 0.1.0

data/.yardopts

@@ -0,0 +1,10 @@
+--no-private
+--protected
+--tag rate_limited:"Rate Limited?"
+--tag authentication:"Authentication"
+--markup markdown
+-
+CHANGELOG.md
+CONTRIBUTING.md
+LICENSE.md
+README.md

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+0.1.0
+-----
+* [Initial release](https://github.com/XOlator/wayback_gem)

data/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+## Contributing
+In the spirit of [free software][free-sw], **everyone** is encouraged to help
+improve this project.
+
+[free-sw]: http://www.fsf.org/licensing/essays/free-sw.html
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (**no patch is too small**: fix typos, add comments, clean up
+  inconsistent whitespace)
+* by refactoring code
+* by fixing [issues][]
+* by reviewing patches
+* [financially][pledgie]
+
+[issues]: https://github.com/xolator/wayback/issues
+
+## Submitting an Issue
+We use the [GitHub issue tracker][issues] to track bugs and features. Before
+submitting a bug report or feature request, check to make sure it hasn't
+already been submitted. When submitting a bug report, please include a [Gist][]
+that includes a stack trace and any details that may be necessary to reproduce
+the bug, including your gem version, Ruby version, and operating system.
+Ideally, a bug report should include a pull request with failing specs.
+
+[gist]: https://gist.github.com/
+
+## Submitting a Pull Request
+1. [Fork the repository.][fork]
+2. [Create a topic branch.][branch]
+3. Add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake spec`. If your specs fail, return to step 5.
+7. Run `open coverage/index.html`. If your changes are not completely covered
+   by your tests, return to step 3.
+8  Run `RUBYOPT=W2 bundle exec rake spec 2>&1 | grep wayback`. If your changes
+   produce any warnings, return to step 5.
+9. Add documentation for your feature or bug fix.
+10. Run `bundle exec rake yard`. If your changes are not 100% documented, go
+    back to step 9.
+11. Commit and push your changes.
+12. [Submit a pull request.][pr]
+
+[fork]: http://help.github.com/fork-a-repo/
+[branch]: http://learn.github.com/p/branching.html
+[pr]: http://help.github.com/send-pull-requests/

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2013 XOlator.
+
+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,81 @@
+# Wayback Gem
+
+![Build Status](https://secure.travis-ci.org/XOlator/wayback_gem.png?branch=master)
+![Coverage Status](https://coveralls.io/repos/XOlator/wayback_gem/badge.png?branch=master)
+
+A Ruby interface to Archive.org's Wayback Machine Memento API.
+
+## Installation
+    gem install wayback
+
+## Quick Start Guide
+So you want to get up and tweeting as fast as possible?
+
+
+## Documentation
+COMING SOON! -- [documentation](http://rdoc.info/gems/wayback)
+
+
+## Configuration
+
+There is no real configuration necessary for accessing Archive.org's Wayback Machine Memento API, however you can change endpoint and other basic connection options.
+
+The current defaults for this gem are:
+
+```ruby
+Wayback.configure do |c|
+  c.endpoint = 'http://api.wayback.archive.org'
+  c.connection_options = {
+    :headers  => {:user_agent => "Wayback Ruby Gem #{Wayback::Version}"},
+    :request  => {:open_timeout => 5, :timeout => 10},
+    :ssl      => {:verify => false},
+  }
+  c.identiy_map = false
+  c.middleware = Faraday::Builder.new do |builder|
+    # Convert request params to "www-form-urlencoded"
+    builder.use Faraday::Request::UrlEncoded
+    # Follow redirects
+    builder.use FaradayMiddleware::FollowRedirects
+    # Handle 4xx server responses
+    builder.use Wayback::Response::RaiseError, Wayback::Error::ClientError
+    # Handle 5xx server responses
+    builder.use Wayback::Response::RaiseError, Wayback::Error::ServerError
+    # Parse memento page
+    builder.use Wayback::Response::ParseMementoPage
+    # Parse link-format with custom memento parser
+    builder.use Wayback::Response::ParseMemento
+    # Set Faraday's HTTP adapter
+    builder.adapter Faraday.default_adapter
+  end
+```
+
+
+## Usage Examples
+
+**Fetch the timeline of archived pages**
+
+```ruby
+Wayback.list('http://www.xolator.com')
+```
+
+**Fetch a specific archived page**
+
+```ruby
+Wayback.page('http://www.xolator.com', 1363488758)
+Wayback.page('http://www.xolator.com', :first)
+Wayback.page('http://www.xolator.com', :last)
+```
+
+
+## Additional Notes
+Based heavily on the [Twitter gem](https://www.github.com/sferik/twitter). (Xie xie!)
+
+More information on Archive's Wayback Machine memento API can be found [here](http://mementoweb.org/depot/native/ia/).
+
+
+
+## Copyright
+Copyright (c) 2013 XOlator.
+See [LICENSE][] for details.
+
+[license]: LICENSE.md

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/wayback.rb

@@ -0,0 +1,32 @@
+require 'wayback/archive'
+require 'wayback/client'
+require 'wayback/configurable'
+require 'wayback/default'
+require 'wayback/page'
+
+module Wayback
+  class << self
+    include Wayback::Configurable
+
+    # Delegate to a Wayback::Client
+    #
+    # @return [Wayback::Client]
+    def client
+      @client = Wayback::Client.new(options) unless defined?(@client) && @client.hash == options.hash
+      @client
+    end
+
+    def respond_to_missing?(method_name, include_private=false); client.respond_to?(method_name, include_private); end if RUBY_VERSION >= "1.9"
+    def respond_to?(method_name, include_private=false); client.respond_to?(method_name, include_private) || super; end if RUBY_VERSION < "1.9"
+
+  private
+
+    def method_missing(method_name, *args, &block)
+      return super unless client.respond_to?(method_name)
+      client.send(method_name, *args, &block)
+    end
+
+  end
+end
+
+Wayback.setup

data/lib/wayback/api/archive.rb

@@ -0,0 +1,42 @@
+require 'time'
+require 'wayback/api/utils'
+require 'wayback/error/not_found'
+
+module Wayback
+  module API
+    module Archive
+      include Wayback::API::Utils
+
+      # Return a list of archived pages
+      #
+      # @return [Wayback::Archive]
+      # @param url [String] The page that of which was archived.
+      # @param options [Hash] A customizable set of options.
+      # @example Return the list of available archives for a web page.
+      #   Wayback.list('http://gleu.ch')
+      def list(url, options={})
+        object_from_response(Wayback::Archive, :get, "/list/timemap/link/#{url}", options)
+      end
+
+      # Returns the HTML contents of an archive page, fetched by date
+      #
+      # @raise [Wayback::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @return [Wayback::Page]
+      # @param url [String] The page that of which was archived.
+      # @param options [Hash] A customizable set of options.
+      # @example Return the HTML archive for the page.
+      #   Wayback.page('http://gleu.ch')
+      #   Wayback.page('http://gleu.ch', 'Tue, 17 Jan 2012 07:33:06 GMT')
+      #   Wayback.page('http://gleu.ch', '20130113125339')
+      #   Wayback.page('http://gleu.ch', :first)
+      #   Wayback.page('http://gleu.ch', :last)
+      def page(url, date=0, options={})
+        date = 0 if date == :first
+        date = Time.now if date == :last
+        date = Time.parse(date).to_i unless [Fixnum,Time,Integer].include?(date.class)
+        object_from_response(Wayback::Page, :get, "/memento/#{date.to_i}/#{url}", options)
+      end
+
+    end
+  end
+end

data/lib/wayback/api/utils.rb

@@ -0,0 +1,27 @@
+module Wayback
+  module API
+    module Utils
+
+    private
+
+      # @param klass [Class]
+      # @param request_method [Symbol]
+      # @param path [String]
+      # @param options [Hash]
+      # @return [Object]
+      def object_from_response(klass, request_method, path, options={})
+        response = send(request_method.to_sym, path, options)
+        klass.from_response(response)
+      end
+
+      # def handle_forbidden_error(klass, error)
+      #   if error.message == klass::MESSAGE
+      #     raise klass.new
+      #   else
+      #     raise error
+      #   end
+      # end
+
+    end
+  end
+end

data/lib/wayback/archive.rb

@@ -0,0 +1,15 @@
+require 'wayback/identity'
+
+module Wayback
+  class Archive < Wayback::Identity
+
+    attr_reader :dates, :first_date, :last_date, :original_url
+
+    # Nicer method for mapping
+    def url; id; end
+
+  private
+
+
+  end
+end

data/lib/wayback/base.rb

@@ -0,0 +1,127 @@
+require 'wayback/error/identity_map_key_error'
+
+module Wayback
+  class Base
+    # Define methods that retrieve the value from an initialized instance variable Hash, using the attribute as a key
+    #
+    # @param attrs [Array, Set, Symbol]
+    def self.attr_reader(*attrs)
+      mod = Module.new do
+        attrs.each do |attribute|
+          define_method attribute do
+            @attrs[attribute.to_sym]
+          end
+          define_method "#{attribute}?" do
+            !!@attrs[attribute.to_sym]
+          end
+        end
+      end
+      const_set(:Attributes, mod)
+      include mod
+    end
+
+    # return [Wayback::IdentityMap]
+    def self.identity_map
+      return unless Wayback.identity_map
+      @identity_map = Wayback.identity_map.new unless defined?(@identity_map) && @identity_map.class == Wayback.identity_map
+      @identity_map
+    end
+
+    # Retrieves an object from the identity map.
+    #
+    # @param attrs [Hash]
+    # @return [Wayback::Base]
+    def self.fetch(attrs)
+      return unless identity_map
+      if object = identity_map.fetch(Marshal.dump(attrs))
+        return object
+      end
+      return yield if block_given?
+      raise Wayback::Error::IdentityMapKeyError, "key not found"
+    end
+
+    # Stores an object in the identity map.
+    #
+    # @param object [Object]
+    # @return [Wayback::Base]
+    def self.store(object)
+      return object unless identity_map
+      identity_map.store(Marshal.dump(object.attrs), object)
+    end
+
+    # Returns a new object based on the response hash
+    #
+    # @param response [Hash]
+    # @return [Wayback::Base]
+    def self.from_response(response={})
+      fetch_or_new(response[:body])
+    end
+
+    # Retrieves an object from the identity map, or stores it in the
+    # identity map if it doesn't already exist.
+    #
+    # @param attrs [Hash]
+    # @return [Wayback::Base]
+    def self.fetch_or_new(attrs={})
+      return unless attrs
+      return new(attrs) unless identity_map
+
+      fetch(attrs) do
+        object = new(attrs)
+        store(object)
+      end
+    end
+
+    # Initializes a new object
+    #
+    # @param attrs [Hash]
+    # @return [Wayback::Base]
+    def initialize(attrs={})
+      @attrs = attrs
+    end
+
+    # Fetches an attribute of an object using hash notation
+    #
+    # @param method [String, Symbol] Message to send to the object
+    def [](method)
+      send(method.to_sym)
+    rescue NoMethodError
+      nil
+    end
+
+    # Retrieve the attributes of an object
+    #
+    # @return [Hash]
+    def attrs
+      @attrs.inject({}) do |attrs, (key, value)|
+        attrs.merge!(key => respond_to?(key) ? send(key) : value)
+      end
+    end
+    alias to_hash attrs
+
+    # Update the attributes of an object
+    #
+    # @param attrs [Hash]
+    # @return [Wayback::Base]
+    def update(attrs)
+      @attrs.update(attrs)
+      self
+    end
+
+  protected
+
+    # @param attr [Symbol]
+    # @param other [Wayback::Base]
+    # @return [Boolean]
+    def attr_equal(attr, other)
+      self.class == other.class && !other.send(attr).nil? && send(attr) == other.send(attr)
+    end
+
+    # @param other [Wayback::Base]
+    # @return [Boolean]
+    def attrs_equal(other)
+      self.class == other.class && !other.attrs.empty? && attrs == other.attrs
+    end
+
+  end
+end

data/lib/wayback/client.rb

@@ -0,0 +1,62 @@
+require 'faraday'
+require 'wayback/api/archive'
+require 'wayback/configurable'
+require 'wayback/error/client_error'
+require 'wayback/error/decode_error'
+require 'uri'
+
+module Wayback
+  # Wrapper for the Wayback Memento/Timehop API
+  class Client
+    include Wayback::API::Archive
+    include Wayback::Configurable
+
+    # Initializes a new Client object
+    #
+    # @param options [Hash]
+    # @return [Wayback::Client]
+    def initialize(options={})
+      Wayback::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || Wayback.instance_variable_get(:"@#{key}"))
+      end
+    end
+
+    # Perform an HTTP DELETE request
+    def delete(path, params={})
+      request(:delete, path, params)
+    end
+
+    # Perform an HTTP GET request
+    def get(path, params={})
+      request(:get, path, params)
+    end
+
+    # Perform an HTTP POST request
+    def post(path, params={})
+      signature_params = params.values.any?{|value| value.respond_to?(:to_io)} ? {} : params
+      request(:post, path, params, signature_params)
+    end
+
+    # Perform an HTTP PUT request
+    def put(path, params={})
+      request(:put, path, params)
+    end
+
+
+  private
+
+    def request(method, path, params={}, signature_params=params)
+      connection.send(method.to_sym, path, params).env
+    rescue Faraday::Error::ClientError
+      raise Wayback::Error::ClientError
+    end
+
+    # Returns a Faraday::Connection object
+    #
+    # @return [Faraday::Connection]
+    def connection
+      @connection ||= Faraday.new(@endpoint, @connection_options.merge(:builder => @middleware))
+    end
+
+  end
+end