serel 1.0.0.rc1

data/README.md

@@ -0,0 +1,10 @@
+# Serel
+[![Build Status](https://secure.travis-ci.org/thomas-mcdonald/serel.png?branch=master)](http://travis-ci.org/thomas-mcdonald/serel)
+
+Serel is an [AREL][1] inspired library developed for v2.0 of the [Stack Exchange API][2]. It's decent, you should try it too.
+
+Read more on the [Serel site][3] or on Stack Apps.
+
+[1]: https://github.com/rails/arel
+[2]: https://api.stackexchange.com/
+[3]: http://serel.tom.is

data/lib/serel.rb

@@ -0,0 +1,37 @@
+# Utilities
+require 'logger'
+require 'serel/exts'
+require 'serel/relation'
+require 'serel/response'
+
+# Types
+require 'serel/base'
+require 'serel/access_token'
+require 'serel/answer'
+require 'serel/badge'
+require 'serel/comment'
+require 'serel/event'
+require 'serel/inbox'
+require 'serel/info'
+require 'serel/post'
+require 'serel/privilege'
+require 'serel/question'
+require 'serel/reputation'
+require 'serel/request'
+require 'serel/revision'
+require 'serel/site'
+require 'serel/suggested_edit'
+require 'serel/tag'
+require 'serel/tag_score'
+require 'serel/tag_synonym'
+require 'serel/tag_wiki'
+require 'serel/user'
+
+# HTTP magic
+require 'cgi'
+require 'json'
+require 'net/http'
+require 'uri'
+require 'zlib'
+
+class Serel::NoAPIKeyError < StandardError; end

data/lib/serel/access_token.rb

@@ -0,0 +1,54 @@
+module Serel
+  # AccessToken is a special helper class designed to make it easier to use access tokens.
+  #
+  # It doesn't handle the retrieval of the token, merely provides a way to get it into Serel.
+  # Creating a new AccessToken provides a couple of helper methods to access authorized methods and
+  # identify who a user is.
+  class AccessToken < Base
+    attributes :token
+    finder_methods :none
+
+    # Create a new instance of AccessToken.
+    # @param [String] token The access token you wish to use.
+    # @return [Serel::AccessToken] An AccessToken intialized with the token.
+    def initialize(token)
+      @data = {}
+      @data[:token] = token
+    end
+
+    # Retrieve the users' inbox items.
+    #  Serel::AccessToken.new(token).inbox.request
+    #  Serel::AccessToken.new(token).scoping_methods.inbox.request
+    #
+    # This is a scoping method and can be combined with other scoping methods.
+    # @return [Serel::Response] A list of {Serel::Inbox Inbox} items wrapped in our Response wrapper.
+    def inbox
+      type(:inbox).access_token(self.token).url("me/inbox")
+    end
+
+    # Retrieve the users' unread inbox items.
+    #  Serel::AccessToken.new(token).unread_inbox.request
+    #
+    # This is a scoping method and can be combined with other scoping methods.
+    # @return [Serel::Response] A list of {Serel::Inbox Inbox} wrapped in our Response wrapper.
+    def unread_inbox
+      type(:inbox).access_token(self.token).url("me/inbox/unread")
+    end
+
+    # Invalidates the access token
+    #   Serel::AccessToken.new(token).invalidate
+    def invalidate
+      network.url("access-tokens/#{token}/invalidate").request
+    end
+
+    # Retrieve the user associated with this access token.
+    #  Serel::AccessToken.new(token).user
+    #
+    # This does not return a {Response} object, rather it directly returns the User.
+    #
+    # @return [Serel::User] The user associated with the access token.
+    def user
+      type(:user, :singular).access_token(self.token).url("me").request
+    end
+  end
+end

data/lib/serel/answer.rb

@@ -0,0 +1,75 @@
+module Serel
+  # The Answer class represents a Stack Exchange answer object.
+  #
+  # == Finding answers
+  #
+  # There are a few different ways of retrieving answers: +all+, +get+ & +find+, as well as the scopes
+  # on other classes.
+  #
+  # === all
+  # +Serel::Answer.all+
+  # 
+  # This should probably never be used. +all+ loads _every_ answer on the site, which, for many sites,
+  # involves retrieving lots of pages. However, it's there. Feel free to use it.
+  #
+  # == find
+  # +Serel::Answer.find(id)+
+  #
+  # Find an answer by its ID.
+  #
+  # == get
+  # +Serel::Answer.get+
+  #
+  # Retrieves answers, applying (any) scope that has been set. In reality this won't be called as given
+  # above, rather it will called at the end of a chain of scoping functions, e.g:
+  #
+  # +Serel::Answer.pagesize(100).sort(:votes).get+
+  #
+  # which would return the top 100 answers on the site.
+  #
+  # == {Question#answers}
+  # +Serel::Question.find(id).answers.get+
+  #
+  # Retrieves the answers on a particular question. The call to +answers+ returns a {Relation}
+  # object, which accepts all the usual relation scopes. This is true for all of the methods listed
+  # below.
+  #
+  # == {User#answers}
+  # +Serel::User.find(id).answers.get+
+  # 
+  # Retrieves answers by a given user
+  class Answer < Base
+    attributes :answer_id, :body, :community_owned_date, :creation_date, :down_vote_count, :is_accepted, :last_activity_date, :last_edit_date, :link, :locked_date, :question_id, :score, :title, :up_vote_count
+    alias :id :answer_id
+
+    associations :comments => :comment, :owner => :user
+    finder_methods :every
+
+    # Get the comments on an answer.
+    # @return [Serel::Relation] A {Comment} relation scoped to the answer.
+    def comments
+      type(:comment).url("answers/#{id}/comments")
+    end
+
+    # Get the question this answer answers.
+    #
+    # Note that this method returns a question not wrapped in the {Response} wrapper.
+    #
+    # @return [Serel::Question] The parent {Question} for this answer.
+    def question
+      type(:question, :singular).url("questions/#{question_id}").request
+    end
+
+    # Get the revisions on an answer.
+    # @return [Serel::Relation] A {Revision} relation scoped to the answer.
+    def revisions
+      type(:revision).url("posts/#{id}/revisions")
+    end
+
+    # Get the suggested edits on an answer
+    # @return [Serel::Relation] A {SuggestedEdit} relation scoped to the answer.
+    def suggested_edits
+      type(:suggested_edit).url("posts/#{id}/suggested-edits")
+    end
+  end
+end

data/lib/serel/badge.rb

@@ -0,0 +1,89 @@
+module Serel
+  # The Badge class represents a Stack Exchange badge object.
+  #
+  # == Finding Badges
+  #
+  # Badges can be retrieved using any of the standard finder methods: +all+, +get+ & +find+.
+  #
+  # === all
+  #   Serel::Badge.all
+  #
+  # Unlike several of the other classes ({Answer}, {Comment}, {Question} etc) where the usage of +all+
+  # is recommended against, +all+ is probably the most useful finder method for retrieving badges, since
+  # a partial set of badges is probably not useful, and only a few pages have to be retrieved each time
+  # this is called. At the time of writing this, Stack Overflow required 17 pages to be retrieved,
+  # Server Fault required 2, and Gaming required 1, and shouldn't make too much of a dent in your quota.
+  #
+  # ==find
+  #   Serel::Badge.find(id)
+  # 
+  # Retrieves a badge or badges by ID.
+  #
+  # == get
+  #   Serel::Badge.get
+  #
+  # Retrieves a page of badge results, applying any scopes that have previously been defined.
+  #
+  # == {named}
+  #  Serel::Badge.named.request
+  # 
+  # See the documentation for {named} below.
+  #
+  # == {recipients}
+  #   Serel::Badge.recipients.request
+  #   Serel::Badge.recipients(1).request
+  #   Serel::Badge.recipients(1,2,3).request
+  #
+  # See the documentation for {recipients} below.
+  #
+  # == {tags}
+  #  Serel::Badge.tags.request
+  #
+  # See the documentation for {tags} below.
+  class Badge < Base
+    attributes :badge_id, :badge_type, :description, :link, :name, :rank
+    alias :id :badge_id
+
+    associations :user => :user
+    finder_methods :every
+
+    # Retrieves only badges that are explicitly defined.
+    # This is a scoping method, meaning that it can be used around/with other scoping methods, for
+    # example:
+    #  Serel::Badge.pagesize(5).named.request
+    #  Serel::Badge.named.sort('gold').request
+    #
+    # @return [Serel::Relation] A relation scoped to the named URL.
+    def self.named
+      url("badges/name")
+    end
+
+    # Retrieves recently awarded badges.
+    #   Serel::Badge.recipients.request
+    #   Serel::Badge.recipients(1).request
+    #   Serel::Badge.recipients(1,2,3).request
+    #
+    # This is a scoping method and can be combined with other scoping methods.
+    #
+    # @param [Array] ids The ID or IDs of the badges you want information on. Not passing an ID means
+    #                    all recently awarded badges will be returned.
+    # @return [Serel::Relation] A relation scoped to the correct recipients URL
+    def self.recipients(*ids)
+      if ids.length > 0
+        arg = ids.length > 1 ? ids.join(';') : ids.pop
+        url("badges/#{arg}/recipients")
+      else
+        url("badges/recipients")
+      end
+    end
+
+    # Retrieves only badges that have been awarded due to participation in a tag.
+    #  Serel::Badge.tags.request
+    #
+    # This is a scoping method and can be combined with other scoping methods.
+    # @return [Serel::Relation] A relation scoped to the tags URL.
+    def self.tags
+      url("badges/tags")
+    end
+  end
+end

data/lib/serel/base.rb

@@ -0,0 +1,180 @@
+module Serel
+  class Base
+    class_attribute :all_finder_methods, :api_key, :associations, :attributes, :finder_methods, :logger, :network, :site
+    self.all_finder_methods = %w(find get all)
+
+    def initialize(data)
+      @data = {}
+      attributes.each { |k| @data[k] = data[k.to_s] }
+      if associations
+        associations.each do |k,v|
+          if data[k.to_s]
+            @data[k] = find_constant(v).new(data[k.to_s])
+          end
+        end
+      end
+    end
+
+    # Internal: Provides access to the internal data
+    # Rather than store data using attr_writers (problems) we use a hash.
+    def [](attr)
+      @data[attr]
+    end
+
+    def []=(attr, value)
+      @data[attr] = value
+    end
+
+    # Public: Sets the global configuration values.
+    #
+    # site - The API site parameter that represents the site you wish to query.
+    # api_key - Your API key.
+    #
+    # Returns nothing.
+    def self.config(site, api_key = nil)
+      self.site = site.to_sym
+      self.api_key = api_key
+      self.logger = Logger.new(STDOUT)
+      self.logger.formatter = proc { |severity, datetime, progname, msg|
+        %([#{severity}][#{datetime.strftime("%Y-%m-%d %H:%M:%S")}] #{msg}\n)
+      }
+    end
+
+    # Public: Provides a nice and quick way to inspec the properties of a
+    #         Serel instance inheriting from Serel::Base
+    #
+    # Returns a String representation of the class
+    def inspect
+      attribute_collector = {}
+      self.class.attributes.each { |attr| attribute_collector[attr] = self.send(attr) }
+      inspected_attributes = attribute_collector.select { |k,v| v != nil }.collect { |k,v| "@#{k}=#{v}" }.join(", ")
+      association_collector = {}
+      self.class.associations.each { |name, type| association_collector[name] = self[name] }
+      inspected_associations = association_collector.select { |k, v| v != nil }.collect { |k, v| "@#{k}=#<#{v.class}:#{v.object_id}>" }.join(", ")
+      "#<#{self.class}:#{self.object_id} #{inspected_attributes} #{inspected_associations}>"
+    end
+    alias :to_s :inspect
+
+    # Internal: Defines the attributes for a subclass of Serel::Base
+    #
+    # *splat - The Array or List of attributes for the class
+    #
+    # Returns nothing.
+    def self.attributes(*splat)
+      self.attributes = splat
+      splat.each do |meth|
+        define_method(meth) { self[meth.to_sym] }
+        define_method("#{meth}=") { |val| self[meth.to_sym] = val }
+      end
+    end
+
+    # Internal: Defines the associations for a subclass of Serel::Base
+    #
+    # options - The Hash options used to define associations
+    #            { :name => :type }
+    #            :name - The Symbol name that this association will be found as in the data
+    #            :type - The Symbol type that this association should be parsed as
+    #
+    # Returns nothing.
+    def self.associations(options = {})
+      self.associations = options
+      options.each do |meth, type|
+        unless self.respond_to?(meth)
+          define_method(meth) { self[meth.to_sym] }
+        end
+        define_method("#{meth}=") { |val| self[meth.to_sym] = val }
+      end
+    end
+
+    # Public: Creates a new relation scoped to the class
+    #
+    # klass - the name of the class to scope the relation to
+    #
+    # Returns an instance of Serel::Relation
+    def self.new_relation(klass = nil, qty = :singular)
+      klass = name.split('::').last.to_snake unless klass
+      Serel::Relation.new(klass.to_s, qty)
+    end
+
+
+    # Public: Sets the finder methods available to this type
+    #
+    # *splat - The Array of methods this class accepts. Also accepts :every,
+    #          which indicates that all finder methods are valid
+    #
+    # Returns nothing of value
+    def self.finder_methods(*splat)
+      self.finder_methods = splat
+    end
+
+    # Denotes that a class does not need the site parameter
+    def self.network_wide
+      self.network = true
+    end
+
+    # Public: Provides an interface to show which methods this class responds to
+    #
+    # method_sym - The Symbol representation of the method you are interested in
+    # include_private - Whether to include private methods. We ignore this, but
+    #                   it is part of how the core library handles respond_to
+    #
+    # Returns Boolean indicating whether the class responds to it or not
+    def self.respond_to?(method_sym, include_private = true)
+      if self.all_finder_methods.include?(method_sym.to_s)
+        if (self.finder_methods.include?(:every)) || (self.finder_methods.include?(method_sym))
+          true
+        else
+          false
+        end
+      else
+        super(method_sym, include_private)
+      end
+    end
+
+    def all
+      if self.respond_to?(:all)
+        new_relation.all
+      else
+        raise NoMethodError
+      end
+    end
+
+    def find(id)
+      if self.respond_to?(:find)
+        new_relation.find(id)
+      else
+        raise NoMethodError
+      end
+    end
+
+    def get
+      if self.respond_to?(:get)
+        new_relation.get
+      else
+        raise NoMethodError
+      end
+    end
+
+    ## Pass these methods direct to a new Relation
+    # TODO: clean these up
+    %w(access_token filter fromdate inname intitle min max nottagged order page pagesize since sort tagged title todate url).each do |meth|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{meth}(val)
+          new_relation.#{meth}(val)
+        end
+      RUBY
+    end
+    def network; self.class.new_relation.network; end
+    def self.request(path, type = nil); new_relation.request(path, type); end
+    def type(klass, qty = :plural)
+      self.class.new_relation(klass, qty)
+    end
+
+    def self.method_missing(sym, *attrs, &block)
+      # TODO: see if the new_relation responds to the method being called
+      #       requires a rewrite of how method_missing works on the
+      #       relation side.
+      new_relation.send(sym, *attrs, &block)
+    end
+  end
+end

data/lib/serel/comment.rb

@@ -0,0 +1,68 @@
+module Serel
+  # The Comment class represents a Stack Exchange comment object.
+  #
+  # == Finding Comments
+  #
+  # Comments can be retrieved using any of the standard finder methods: +all+, +get+ & +find+.
+  #
+  # === all
+  #   Serel::Comment.all
+  #
+  # It is recommended that you don't use this method, since most of the time it is overkill.
+  # Automatically paginating through all the comments on a site, even 100 comments at a time, will take
+  # a long time and a lot of requests. It is almost certainly better to use one of the other finder
+  # methods, but this is here for the sake of completion. If you need to access every comment, the data
+  # dump and data explorer are your friends.
+  #
+  # ==find
+  #   Serel::Comment.find(id)
+  # 
+  # Retrieves a comment or comments by ID.
+  #
+  # == get
+  #   Serel::Comment.get
+  #
+  # Retrieves a page of comment results, applying any scopes that have previously been defined.
+  #
+  # == {Answer#comments}
+  #  Serel::Answer.find(id).comments.request
+  #
+  # Retrieves a page of comments on the specified answer.
+  #
+  # == {Post#comments}
+  #  Serel::Post.find(id).comments.request
+  #
+  # Retrieves a page of comments on the specified post.
+  #
+  # == {Question#comments}
+  #  Serel::Question.find(id).comments.request
+  #
+  # Retrieves a page of comments on the specified question.
+  #
+  # == {User#comments}
+  #  Serel::User.find(id).comments.request
+  #  Serel::User.find(id).comments(other_id).request
+  #
+  # Retrieves a page of comments by the specified user. If the optional +other_id+ parameter is passed
+  # then only comments in reply to +other_id+ are included.
+  #
+  # == {User#mentioned}
+  #  Serel::User.find(id).mentioned.request
+  #
+  # Retrieves a page of comments mentioning the specified user.
+  class Comment < Base
+    attributes :comment_id, :body, :creation_date, :edited, :link, :post_id, :post_type, :score
+    alias :id :comment_id
+
+    associations :owner => :user, :reply_to_user => :user
+    finder_methods :every
+
+    # Retrieves the post that this comment is on.
+    #
+    # Note that this returns the post, rather than returning a {Serel::Response} wrapped array.
+    # @return [Serel::Post] The post the comment is on.
+    def post
+      type(:post, :singular).url("posts/#{post_id}").request
+    end
+  end
+end

data/lib/serel/event.rb

@@ -0,0 +1,25 @@
+module Serel
+  # The Event class represents a Stack Exchange event.
+  #
+  # == Finding events
+  #
+  # You can use the +all+ and +get+ finder methods to retrieve events. Both of these require
+  # authentication, so {Relation#access_token access_token} must be called before the finders.
+  #
+  # === all
+  #   Serel::Event.access_token(token).all
+  # 
+  # Retrieves (by default) all the events on the site in the last 5 minutes. The +since+ method can
+  # be called to change this return events upto 15 minutes ago. This method is safe to call, since even
+  # on Stack Overflow only roughly 3 pages of events are generated every 5 minutes.
+  #
+  # == get
+  #   Serel::Event.access_token(token).get
+  #
+  # Retrieves a page of Events. As per the +all+ method above, this defaults to events in the last 5
+  # minutes.
+  class Event < Base
+    attributes :event_type, :event_id, :creation_date, :link, :excerpt
+    finder_methods :all, :get
+  end
+end

data/lib/serel/exts.rb

@@ -0,0 +1,88 @@
+# TODO: make file less ugly.
+
+def remove_possible_method(method)
+  if method_defined?(method) || private_method_defined?(method)
+    remove_method(method)
+  end
+rescue NameError
+  # If the requested method is defined on a superclass or included module,
+  # method_defined? returns true but remove_method throws a NameError.
+  # Ignore this.
+end
+
+def singleton_class?
+  !name || '' == name
+end
+
+def singleton_class
+  class << self
+    self
+  end
+end
+
+def class_attribute(*attrs)
+  if attrs.last.is_a?(Hash)
+    options = attrs.pop
+  else
+    options = {}
+  end
+  instance_reader = options.fetch(:instance_reader, true)
+  instance_writer = options.fetch(:instance_writer, true)
+
+    attrs.each do |name|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{name}() nil end
+        def self.#{name}?() !!#{name} end
+
+        def self.#{name}=(val)
+          singleton_class.class_eval do
+            remove_possible_method(:#{name})
+            define_method(:#{name}) { val }
+          end
+
+          if singleton_class?
+            class_eval do
+              remove_possible_method(:#{name})
+              def #{name}
+                defined?(@#{name}) ? @#{name} : singleton_class.#{name}
+              end
+            end
+          end
+          val
+        end
+
+        if instance_reader
+          remove_possible_method :#{name}
+          def #{name}
+            defined?(@#{name}) ? @#{name} : self.class.#{name}
+          end
+
+          def #{name}?
+            !!#{name}
+          end
+        end
+      RUBY
+
+      attr_writer name if instance_writer
+  end
+end
+
+def find_constant(symbol)
+  str = symbol.to_s.dup
+  match = /_([a-z])/.match(str)
+  if match
+    str.gsub!(match[0], match[1].upcase)
+  end
+  str[0] = str[0].upcase
+  Serel.const_get(str)
+end
+
+class String
+  # Yeah, it's #underscore in Rails, but that's not half as fun.
+  def to_snake
+    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+    tr("-", "_").
+    downcase
+  end
+end

data/lib/serel/inbox.rb

@@ -0,0 +1,6 @@
+module Serel
+  class Inbox < Base
+    attributes :item_type, :question_id, :answer_id, :comment_id, :title, :creation_date, :is_unread, :site, :body, :link
+    finder_methods :none
+  end
+end

data/lib/serel/info.rb

@@ -0,0 +1,21 @@
+module Serel
+  # The Info class represents information about a Stack Exchange site.
+  #
+  # == Getting info
+  # The +/info+ route accepts no parameters and requires no IDs, so the default finder methods cannot be
+  # used. We therefore have a custom finder defined, {.get_info}.
+  class Info < Base
+    attributes :total_questions, :total_unanswered, :total_accepted, :total_answers, :questions_per_minute, :answers_per_minute, :total_comments, :total_votes, :total_badges, :badges_per_minute, :total_users, :new_active_users, :api_revision
+    associations :site => :site
+    finder_methods :none
+
+    # Gets information about the current site.
+    #
+    # It is best practice to aggresively cache the returned values with a TTL of at least 3600 seconds.
+    #
+    # @return [Serel::Info] Information about the site
+    def self.get_info
+      new_relation(:info, :singular).url("info").request
+    end
+  end
+end

data/lib/serel/post.rb

@@ -0,0 +1,21 @@
+module Serel
+  class Post < Base
+    attributes :post_id, :post_type, :body, :creation_date, :last_activity_date, :last_edit_date, :score, :up_vote_count, :down_vote_count
+    alias :id :post_id
+
+    associations :comments => :comment, :owner => :user
+    finder_methods :every
+
+    def comments
+      type(:comment).url("posts/#{id}/comments")
+    end
+
+    def revisions
+      type(:revision).url("posts/#{id}/revisions")
+    end
+
+    def suggested_edits
+      type(:suggested_edit).url("posts/#{id}/suggested-edits")
+    end
+  end
+end

data/lib/serel/privilege.rb

@@ -0,0 +1,6 @@
+module Serel
+  class Privilege < Base
+    attributes :short_description, :description, :reputation
+    finder_methods :all
+  end
+end

data/lib/serel/question.rb

@@ -0,0 +1,48 @@
+module Serel
+  class Question < Base
+    attributes :question_id, :accepted_answer_id, :answer_count, :body, :bounty_amount, :bounty_closes_date, :closed_reason, :community_owned_date, :creation_date, :down_vote_count, :favourite_count, :last_activity_date, :last_edit_date, :link, :locked_date, :migrated_to, :migrated_from, :protected_date, :score, :tags, :title, :up_vote_count, :view_count
+    associations :answers => :answer, :comments => :comment, :owner => :user
+    alias :id :question_id
+    finder_methods :every
+
+    def self.featured
+      url("questions/featured")
+    end
+
+    def self.search
+      url("search")
+    end
+
+    def self.similar
+      url("similar")
+    end
+
+    def self.unanswered
+      url("questions/unanswered")
+    end
+
+    def self.no_answers
+      url("questions/no-answers")
+    end
+
+    def answers
+      type(:answer).url("questions/#{@id}/answers")
+    end
+
+    def comments
+      type(:comment).url("questions/#{@id}/comments")
+    end
+
+    def linked
+      type(:question).url("questions/#{@id}/linked")
+    end
+
+    def related
+      type(:question).url("questions/#{@id}/related")
+    end
+
+    def timeline
+      type(:timeline).url("questions/#{@id}/timeline")
+    end
+  end
+end

data/lib/serel/relation.rb

@@ -0,0 +1,125 @@
+module Serel
+  class Relation
+    attr_reader :type, :klass, :qty
+
+    def initialize(type, qty)
+      @type = type
+      @klass = find_constant(type)
+      @scope = {
+        api_key: Serel::Base.api_key,
+        site: Serel::Base.site
+      }
+      @qty = qty
+    end
+
+    # Public: Merges two relation objects together. This is used in our awesome
+    #         new scoping engine!
+    #
+    # relation - A Serel::Relation object with the same base class as the
+    #            current relation
+    #
+    # Returns self
+    def merge(relation)
+      if relation.instance_variable_get(:@type) != @type
+        raise ArgumentError, 'You cannot merge two relation objects based on different classes'
+      end
+      @scope.merge!(relation.scoping)
+    end
+
+    # Scoping returns our internal scope defition. Things like url etc.
+    def scoping
+      @scope
+    end
+
+    def new_relation
+      self
+    end
+
+    def method_missing(sym, *attrs, &block)
+      # If the base relation class responds to the method, call
+      # it and merge in the resulting relation scope
+      if @klass.respond_to?(sym)
+        relation = @klass.send(sym, *attrs, &block)
+        merge(relation)
+        self
+      end
+      super(sym, *attrs, &block)
+    end
+
+    #
+    #
+    #
+    # Scope methods
+    %w(access_token filter fromdate inname intitle min max nottagged order page pagesize since sort tagged title todate url).each do |meth|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{meth}(val)
+          @scope[:#{meth}] = val.to_s
+          self
+        end
+      RUBY
+    end
+
+    def network
+      @network = true
+      self
+    end
+
+    #
+    #
+    #
+    # Finder methods
+    def all
+      if klass.respond_to?(:all)
+        all_helper(1)
+      else
+        raise NoMethodError
+      end
+    end
+
+    # Finds an object by an ID or list of IDs. For example:
+    #   Serel::Answer.find(1) # Find the answer with an ID of 1
+    #   Serel::Answer.find(1, 2, 3) # Find the answers with IDs of 1, 2 & 3
+    #
+    # @param [Array] ids The ID or IDs of the objects you want returning.
+    # @return [Serel::Response] The data returned by the Stack Exchange API, parsed and pushed into our
+    #                           handy response wrapper.
+    def find(*ids)
+      if klass.respond_to?(:find)
+        arg = ids.length > 1 ? ids.join(';') : ids.pop
+        url("#{@type}s/#{arg}").request
+      else
+        raise NoMethodError
+      end
+    end
+
+    def get
+      if klass.respond_to?(:get)
+        url("#{@type}s").request
+      else
+        raise NoMethodError
+      end
+    end
+
+    # Request stuff
+    def request
+      if (klass.network || @network)
+        @scope[:network] = true
+      end
+      Serel::Request.new(@type, scoping, @qty).execute
+    end
+
+    private
+
+    def all_helper(page)
+      response = page(page).pagesize(100).url("#{@type}s").request
+      # TODO: find a query that triggers backoff.
+      # if response.backoff
+      #   Serel::Base.warn response.backoff
+      # end
+      if response.has_more
+        response.concat all_helper(page+1)
+      end
+      response
+    end
+  end
+end

data/lib/serel/reputation.rb

@@ -0,0 +1,6 @@
+module Serel
+  class Reputation < Base
+    attributes :user_id, :post_id, :post_type, :vote_type, :title, :link, :reputation_change, :on_date
+    finder_methods :none
+  end
+end

data/lib/serel/request.rb

@@ -0,0 +1,63 @@
+module Serel
+  class Request
+    def initialize(type, scoping, qty)
+      @type = type
+      @scope = scoping.dup
+      @site = @scope.delete :site
+      @api_key = @scope.delete :api_key
+      raise Serel::NoAPIKeyError, 'You must configure Serel with an API key before you can make requests' if @api_key == nil
+      @method = @scope.delete :url
+      @network = @scope.delete :network
+      @qty = qty
+    end
+
+    def execute
+      build_query_string
+      build_request_path
+      make_request
+    end
+
+    def build_query_string
+      query_hash = @scope
+      unless @network
+        query_hash[:site] = @site
+      end
+      query_hash[:key] = @api_key
+      @query_string = query_hash.map { |k,v| "#{CGI::escape(k.to_s)}=#{CGI::escape(v.to_s)}"}.join('&')
+    end
+
+    def build_request_path
+      @path = "/2.0/#{@method}?#{@query_string}"
+    end
+
+    def make_request
+      Serel::Base.logger.info "Making request to #{@path}"
+      http = Net::HTTP.new('api.stackexchange.com', 443)
+      http.use_ssl = true
+      response = http.get(@path)
+      body = JSON.parse(response.body)
+
+      result = Serel::Response.new
+
+      # Set the values of the response wrapper attributes
+      %w(backoff error_id error_message error_name has_more page page_size quota_max quota_remaining total type).each do |attr|
+        result.send("#{attr}=", body[attr])
+      end
+
+      # Set some response values we know about but SE might not send back
+      result.page ||= (@scope[:page] || 1)
+      result.page_size ||= (@scope[:pagesize] || 30)
+
+      # Insert into the response array the items returned
+      body["items"].each do |item|
+        result << find_constant(@type).new(item)
+      end
+
+      if (@qty == :plural) || (result.length > 1)
+        result
+      else
+        result.pop
+      end
+    end
+  end
+end

data/lib/serel/response.rb

@@ -0,0 +1,5 @@
+module Serel
+  class Response < Array
+    attr_accessor :backoff, :error_id, :error_message, :error_name, :has_more, :page, :page_size, :quota_max, :quota_remaining, :total, :type
+  end
+end

data/lib/serel/revision.rb

@@ -0,0 +1,9 @@
+module Serel
+  class Revision < Base
+    attributes :revision_guid, :revision_number, :revision_type, :post_type, :post_id, :comment, :creation_date, :is_rollback, :last_body, :last_title, :last_tags, :body, :title, :tags, :set_community_wiki
+    alias :id :revision_guid
+
+    associations :user => :user
+    finder_methods :find
+  end
+end

data/lib/serel/site.rb

@@ -0,0 +1,22 @@
+module Serel
+  # The Site class represents a Stack Exchange site.
+  #
+  # == Finding Sites
+  #
+  # Sites can be retrieved using +all+ and +get+.
+  #
+  # === all
+  #   Serel::Site.all
+  #
+  # Automatically paginates through the list of sites and returns an array of every Stack Exchange site.
+  #
+  # == get
+  #   Serel::Site.get
+  #
+  # Retrieves a page of sites, applying any scopes that have previously been defined.
+  class Site < Base
+    attributes :site_type, :name, :logo_url, :api_site_parameter, :site_url, :audience, :icon_url, :aliases, :site_state, :styling, :closed_beta_date, :open_beta_date, :launch_date, :favicon_url, :related_sites, :twitter_account, :markdown_extensions
+    finder_methods :all, :get
+    network_wide
+  end
+end

data/lib/serel/suggested_edit.rb

@@ -0,0 +1,8 @@
+module Serel
+  class SuggestedEdit < Base
+    attributes :suggested_edit_id, :post_id, :post_type, :body, :title, :tags, :comment, :creation_date, :approval_date, :rejection_date
+    alias :id :suggested_edit_id
+    associations :proposing_user => :user
+    finder_methods :every
+  end
+end

data/lib/serel/tag.rb

@@ -0,0 +1,63 @@
+module Serel
+  class Tag < Base
+    attributes :name, :count, :is_required, :is_moderator_only, :user_id, :has_synonyms, :last_activity_date
+    finder_methods :all, :get
+
+    # Finds a tag by name
+    # @param [String] name The name of the tag you wish to find
+    # @return [Serel::Tag] The tag returned by the Stack Exchange API
+    def self.find_by_name(name)
+      url("tags/#{name}/info").request
+    end
+
+    # Retrieves tags which can only be added or removed by a moderator
+    #  Serel::Tag.moderator_only.request
+    #
+    # This is a scoping method and can be combined with other scoping methods
+    # @return [Serel::Relation] A relation scoped to the moderator only URL.
+    def self.moderator_only
+      url("tags/moderator-only")
+    end
+
+    # Retrieves tags that are required on the site
+    #   Serel::Tag.required.request
+    #
+    # This is a scoping method and can be combined with other scoping methods.
+    # @return [Serel::Relation] A relation scoped to the required URL.
+    def self.required
+      url("tags/required")
+    end
+
+    # Retrieves all the tag synonyms on the site
+    #   Serel::Tag.synonyms.request
+    #
+    # This is a scoping method and can be combined with other scoping methods.
+    # @return [Serel::Relation] A relation scoped to {Serel::TagSynonym TagSynonym} and the synonym URL.
+    def self.synonyms
+      new_relation(:tag_synonym).url("tags/synonyms")
+    end
+
+    # Retrieves related tags.
+    #   Serel::Tag.find(1).related.request
+    #
+    # This is a scoping method and can be combined with other scoping methods.
+    # @return [Serel::Relation] A relation scoped to the related URL
+    def related
+      type(:tag).url("tags/#{name}/related")
+    end
+
+    def top_answerers(period)
+      raise ArgumentError, 'period must be :all_time or :month' unless [:all_time, :month].include? period
+      type(:tag_score).url("tags/#{name}/top-answerers/#{period}")
+    end
+
+    def top_askers(period)
+      raise ArgumentError, 'period must be :all_time or :month' unless [:all_time, :month].include? period
+      type(:tag_score).url("tags/#{name}/top-askers/#{period}")
+    end
+
+    def wiki
+      type(:tag_wiki, :singular).url("tags/#{name}/wikis").request
+    end
+  end
+end

data/lib/serel/tag_score.rb

@@ -0,0 +1,7 @@
+module Serel
+  class TagScore < Base
+    attributes :score, :post_count
+    associations :user => :user
+    finder_methods :none
+  end
+end

data/lib/serel/tag_synonym.rb

@@ -0,0 +1,6 @@
+module Serel
+  class TagSynonym < Base
+    attributes :from_tag, :to_tag, :applied_count, :last_applied_date, :creation_date
+    finder_methods :none
+  end
+end

data/lib/serel/tag_wiki.rb

@@ -0,0 +1,7 @@
+module Serel
+  class TagWiki < Base
+    attributes :tag_name, :body, :excerpt, :body_last_edit_date, :excerpt_last_edit_date
+    associations :last_body_editor => :user, :last_excerpt_editor => :user
+    finder_methods :none
+  end
+end

data/lib/serel/timeline.rb

@@ -0,0 +1,7 @@
+module Serel
+  class Timeline < Base
+    attributes :timeline_type, :question_id, :post_id, :comment_id, :revision_guid, :up_vote_count, :down_vote_count, :creation_date
+    associations :user => :user, :owner => :user
+    finder_methods :every
+  end
+end

data/lib/serel/user.rb

@@ -0,0 +1,85 @@
+module Serel
+  class User < Base
+    attributes :user_id, :user_type, :creation_date, :display_name, :profile_image, :reputation, :reputation_change_day, :reputation_change_week, :reputation_change_month, :reputation_change_quarter, :reputation_change_year, :age, :last_access_date, :last_modified_date, :is_employee, :link, :website_url, :location, :account_id, :timed_penalty_date, :badge_counts, :question_counts, :answer_count, :up_vote_count, :down_vote_count, :about_me, :view_count, :accept_rate
+    alias :id :user_id
+    finder_methods :every
+
+    def self.moderators
+      url("users/moderators")
+    end
+
+    def self.elected_moderators
+      url("users/moderators/elected")
+    end
+
+    def answers
+      type(:answer).url("users/#{id}/answers")
+    end
+
+    def badges
+      type(:badge).url("users/#{id}/badges")
+    end
+
+    def comments(to_id = nil)
+      if to_id
+        type(:comment).url("users/#{id}/comments/#{to_id}")
+      else
+        type(:comment).url("users/#{id}/comments")
+      end
+    end
+
+    def favorites
+      type(:question).url("users/#{id}/favorites")
+    end
+
+    def mentioned
+      type(:comment).url("users/#{id}/mentioned")
+    end
+
+    def privileges
+      type(:privilege).url("users/#{id}/privileges")
+    end
+
+    def questions
+      type(:question).url("users/#{id}/questions")
+    end
+
+    def questions_featured
+      type(:question).url("users/#{id}/questions/featured")
+    end
+
+    def questions_no_answers
+      type(:question).url("users/#{id}/questions/no-answers")
+    end
+
+    def questions_unaccepted
+      type(:question).url("users/#{id}/questions/unaccepted")
+    end
+
+    def questions_unanswered
+      type(:question).url("users/#{id}/questions/unanswered")
+    end
+
+    def reputation
+      type(:reputation).url("users/#{id}/reputation")
+    end
+
+    def suggested_edits
+      type(:suggested_edit).url("users/#{id}/suggested-edits")
+    end
+
+    def tags
+      type(:tag).url("users/#{id}/tags")
+    end
+
+    def top_answers_on(*tags)
+      arg = tags.length > 1 ? tags.join(";") : tags.pop
+      type(:answer).url("users/#{id}/tags/#{arg}/top-answers")
+    end
+
+    def top_questions_on(*tags)
+      arg = tags.length > 1 ? tags.join(";") : tags.pop
+      type(:question).url("users/#{id}/tags/#{arg}/top-questions")
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: serel
+version: !ruby/object:Gem::Version
+  version: 1.0.0.rc1
+  prerelease: 6
+platform: ruby
+authors:
+- Thomas McDonald
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70120458988780 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70120458988780
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: &70120458987680 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70120458987680
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: &70120458986560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70120458986560
+description: 
+email: tom@conceptcoding.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/serel/access_token.rb
+- lib/serel/answer.rb
+- lib/serel/badge.rb
+- lib/serel/base.rb
+- lib/serel/comment.rb
+- lib/serel/event.rb
+- lib/serel/exts.rb
+- lib/serel/inbox.rb
+- lib/serel/info.rb
+- lib/serel/post.rb
+- lib/serel/privilege.rb
+- lib/serel/question.rb
+- lib/serel/relation.rb
+- lib/serel/reputation.rb
+- lib/serel/request.rb
+- lib/serel/response.rb
+- lib/serel/revision.rb
+- lib/serel/site.rb
+- lib/serel/suggested_edit.rb
+- lib/serel/tag.rb
+- lib/serel/tag_score.rb
+- lib/serel/tag_synonym.rb
+- lib/serel/tag_wiki.rb
+- lib/serel/timeline.rb
+- lib/serel/user.rb
+- lib/serel.rb
+- README.md
+homepage: http://serel.tom.is
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.12
+signing_key: 
+specification_version: 3
+summary: A Ruby library for the Stack Exchange API
+test_files: []
+has_rdoc: