stacked 0.5.0 → 1.0.0.beta1

data/.gitignore

@@ -1,6 +1,9 @@
+.bundle
 .yardoc
 *.sw?
 .DS_Store
 coverage
 rdoc
 pkg
+notes.md
+stacked-*.gem

data/Gemfile

@@ -1 +1,3 @@
-gem 'httparty', '0.4.5'
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    stacked (1.0.0)
+      activesupport (~> 3.0.3)
+      httparty (~> 0.7.3)
+      i18n (~> 0.5.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.0.3)
+    addressable (2.2.3)
+    crack (0.1.8)
+    diff-lcs (1.1.2)
+    httparty (0.7.3)
+      crack (= 0.1.8)
+    i18n (0.5.0)
+    rake (0.8.7)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    webmock (1.6.2)
+      addressable (>= 2.2.2)
+      crack (>= 0.1.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 3.0.3)
+  bundler (~> 1.0)
+  httparty (~> 0.7.3)
+  i18n (~> 0.5.0)
+  rake (~> 0.8)
+  rspec (~> 2.4)
+  stacked!
+  webmock (~> 1.6.2)

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Ryan Bigg
+Copyright (c) 2009-2011 Ryan Bigg, Adam McDonald
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -1,37 +1,70 @@
-# Stacked - A Ruby wrapper for the Stack Overflow API (v0.5)
+# Stacked - A Ruby wrapper for the Stack Exchange API (v1.0)
 
-This library is built around the Stack Overflow (private) API [described here][http://blog.stackoverflow.com/2010/03/stack-overflow-api-private-beta-starts/]. I am under the impression that it covers all the API methods described in [this comprehensive listing][http://dev.meta.stackoverflow.com/questions/34594/overall-api-method-list], but equally aware that this is a first draft and I am likely to make a mistake or four.
+# Note: This code is being actively developed and will be merged with master when ready.
+
+While a lot of the core code has remained unchanged, this fork has went through many updates to get it working with the latest version (1.0) of the Stack Exchange API. Many thanks to radar for this initial work on this project.
 
 ## Installation
 
-To install stacked:
+    # Currently installs outdated version of the gem
+    # sudo gem install stacked
 
-    sudo gem install stacked
+## Usage
 
-To use it:
+Stacked is configurable to work with any of the Stack Exchange sites. When setting up the client, just specify the site you wish to access, the API version number, and your api key. By default, Stacked will access Stack Overflow API version 1.0. Note: You must still supply your own api key in the config.
 
-    require 'stacked'
-    Stacked::Question.all
+    # Access Stack Overflow API v1.0
+    Stacked::Client.configure do |config|
+      config.api_key = 'yourapikey'
+    end
     
-To report breakages: http://github.com/radar/stacked/issues.
-
-## Some notes
-
-Methods that are designed to take options in the API are designed that way in the wrapper also, as you'd expect. Take for example +Stacked::Question.all+ which you can pass any options you wish:
+    # Access Server Fault API v1.0
+    Stacked::Client.configure do |config|
+      config.site    = 'serverfault.com',
+      config.version = '1.0',
+      config.api_key = 'yourapikey'
+    end
 
-     Stacked::Question.all(:pagesize => 10)
+Methods that are designed to take options in the API are designed that way in the wrapper also, as you'd expect. For more details, read the Stack Overflow API [documentation](http://api.stackoverflow.com/1.0/help).
 
-In this example the amount of questions returned is limited to 10. 
-
-Other options include:
-
-* page - Specify the page when paginating through a collection.
-* body - Set this to true to return the body of the objects you're receiving. By default set to false for questions and answers.
-* comments - Set this to true to include the comments in the objects you're receiving.
-* fromdate - An integer timestamp of the time you wish to search from (default: 30 days ago, 90 days for reputation).
-* todate - An integer timestamp of the time you wish to search to (default: now)
-* tagged - A list of tags to scope this find by. Effective only on question methods.
+    require 'stacked'
+    
+    # - - Questions / Answers / Comments
+    
+    # Setup the client
+    Stacked::Client.configure do |config|
+      config.api_key = 'yourapikey' # required
+    end
+    
+    # Returns 30 (default page size) questions based on activity (default sort option)
+    Stacked::Question.all
+    
+    # Returns questions tagged with 'ruby', including the question body and comments
+    Stacked::Question.all(:tagged => 'ruby', :body => true, :comments => true)
+    
+    # Returns a individual question by id
+    question = Stacked::Question.find(151338)
+    
+    # Returns paged answers for the question
+    answers = question.answers
+    
+    # Returns paged comments for the question
+    comments = question.comments
+    
+    # You can also specify multiple ids as an array for all find requests
+    questions = Stacked::Question.find([151338, 4579074])
+    
+    # Returns paged questions based on search criteria
+    Stacked::Question.search(:intitle => 'github', :tagged => 'ruby')
+    
+    # - - Users
 
-There may be some options I have missed from this list. This is why it's a first draft. So you can tell me I'm missing options, then I can add them and make it a second draft. And so on.
+    # Returns the specified user
+    skeet = Stacked::User.find(22656)
+    
+    # Returns all badges awarded to the user
+    skeet.badges
+     
+## Documentation
 
-     
+For additional details, checkout the latest generated [documentation](http://raid5.github.com/stacked).

data/Rakefile

@@ -1,51 +1,12 @@
 require 'rubygems'
 require 'rake'
+require 'bundler'
+Bundler::GemHelper.install_tasks
 
 begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "stacked"
-    gem.summary = %Q{Ruby wrapper for the Stack Overflow API}
-    gem.description = %Q{Ruby wrapper for the Stack Overflow API}
-    gem.email = "ryan@getup.org.au"
-    gem.homepage = "http://github.com/radar/stacked"
-    gem.authors = ["Ryan Bigg"]
-    gem.add_development_dependency "rspec"
-    gem.add_dependency('httparty', '~> 0.4.5')
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
+  require 'rspec/core/rake_task'
+  [:spec, :rcov].each { |task| RSpec::Core::RakeTask.new(task) }
+  task :default => :spec
 rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end
-
-Jeweler::GemcutterTasks.new
-
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
-end
-
-Spec::Rake::SpecTask.new(:rcov) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
-
-task :spec => :check_dependencies
-
-task :default => :spec
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION')
-    version = File.read('VERSION')
-  else
-    version = ""
-  end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "stacked #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+  raise 'RSpec could not be loaded. Run `bundle install` to get all development dependencies.'
 end

data/genddoc.sh

@@ -4,8 +4,11 @@ rm -rf ../stacked-doc &&
 mkdir -p ../stacked-doc &&
 mv doc/* ../stacked-doc &&
 git checkout gh-pages &&
-rm -rf * &&
+cd .. &&
+rm -rf stacked/* &&
+cd stacked/ &&
 mv ../stacked-doc/* . &&
+rm -rf ../stacked-doc &&
 git add . &&
 git commit -m "Updated documentation." &&
 git push origin gh-pages &&

data/lib/stacked.rb

@@ -5,8 +5,9 @@ rescue LoadError
   Bundler.setup!
 end
 
-require 'active_support'
+require 'active_support/all'
 
+# The Stacked module.
 module Stacked
   # TODO: Use this coupled with autoload_under when AS 3.0 becomes "stable":
   # extend ActiveSupport::Autoload
@@ -20,23 +21,24 @@ module Stacked
   # Instead of:
   #
   # autoload :Base, 'stacked/base'
-  class << self
-    def autoload(klass)
-      super(klass, "stacked/#{klass.to_s.underscore}")
-    end
-  end
+  extend ActiveSupport::Autoload
+  
+  autoload :Client
   autoload :Answer
   autoload :Base
   autoload :Badge
   autoload :Comment
-  autoload :Posttimeline
+  autoload :PostTimeline
+  autoload :Parser
   autoload :Question
-  autoload :Reputation
+  autoload :RepChange
   autoload :Tag
   autoload :User
-  autoload :Usertimeline
+  autoload :UserTimeline
 
+  # NotImplemented::StandardError class.
   class NotImplemented < StandardError
+    # Default message for trying to call all/find on unsupported resources.
     def message
       "The requested action is not available in the API."
     end

data/lib/stacked/answer.rb

@@ -1,43 +1,26 @@
 module Stacked
+  # Stacked::Answer class.
   class Answer < Base
-    attr_accessor :accepted,
-                  :answer_id,
-                  :body,
-                  :comments,
-                  :community_owned,
-                  :creation_date,
-                  :down_vote_count,
-                  :last_edit_date,
-                  :owner_display_name,
-                  :owner_user_id,
-                  :question_id,
-                  :score,
-                  :title,
-                  :up_vote_count,
-                  :view_count
-
+    
     class << self
       def all(*args)
         raise Stacked::NotImplemented
       end
     end
     
-    # A Stacked::User object representing the owner of the answer.
-    def owner
-      @owner ||= User.find(owner_user_id)
+    # Comments for the answer.
+    def comments(options={})
+      parse_comments(request(singular(answer_id) + "/comments", options))
+    end
+    
+    # Helper method for creating Stacked::User object when initializing new Stacked::Answer objects.
+    def owner=(attributes)
+      @owner = User.new(attributes)
     end
    
     # A Stacked::Question object representing the question the answer is in response to.
     def question
       @question ||= Question.find(question_id)
     end
-
-    alias_method :created_at, :creation_date
-    alias_method :updated_at, :last_edit_date
-    alias_method :id, :answer_id
-    alias_method :up_votes, :up_vote_count
-    alias_method :views, :view_count
-    alias_method :user, :owner
   end
-
 end

data/lib/stacked/badge.rb

@@ -1,17 +1,21 @@
 module Stacked
+  # Stacked::Badge class.
   class Badge < Base
-    attr_accessor :award_count,
-                  :badge_id,
-                  :class,
-                  :description,
-                  :name
-
-    collection :tags
-
-    alias_method :id, :badge_id
-
     class << self
-      alias_method :name, :all
+      # All users who have been awarded the specific badge.
+      def find(id, options = {})
+        parse_users(request(singular(id), options))
+      end
+
+      # All standard, non-tag-based badges.
+      def name(options={})
+        records(path + "/name", options)
+      end
+      
+      # All tag-based badges
+      def tags(options={})
+        records(path + "/tags", options)
+      end
     end
 
   end

data/lib/stacked/base.rb

@@ -1,9 +1,11 @@
 require 'httparty'
-require 'pathname'
+require 'zlib'
 
 module Stacked
+  # Stacked::Base class.
   class Base
     include HTTParty
+    extend Stacked::Parser
 
     delegate :request, :singular, :parse, :to => "self.class"
 
@@ -11,17 +13,32 @@ module Stacked
       
       # Return the stats provided by the API.
       def stats
-        request(base + "stats")["stats"]
+        request(base + "stats")["statistics"].first
       end
       
-      # All the first group (depends on pagesize) of records for current class.
+      # All the of records for current class (depends on pagesize).
       def all(options = {})
         records(path, options)
       end
 
-      # A single record belonging to the current class.
-      def find(id, options={})
-        self.new(request(singular(id), options)[resource.singularize])
+      # A single (or multiple depending on number of ids) record belonging to the current class.
+      def find(*args)
+        # Determine ids (single or multiple)
+        ids = []
+        if args.first.instance_of? Fixnum
+          ids << args.first
+        elsif args.first.instance_of? Array
+          ids.concat(args.first)
+        end
+
+        # Options hash supplied? Merge in options
+        options = {}
+        if args.last.instance_of? Hash
+          options.merge!(args.last)
+        end
+        
+        recs = records(path_with_ids(ids), options)
+        recs.size == 1 ? recs.first : recs
       end
       
       # All records for a given request path.
@@ -29,50 +46,37 @@ module Stacked
         parse(request(p, options)[resource])
       end
 
-      # Raw Hash of request.
+      # Makes request to StackExchange server and decodes it from gzip.
       def request(p = path, options = {})
-        get(p, :query => { :key => key }.merge!(options))
-      end
-
-      # Define collection methods, such as newest.
-      def collection(*names)
-        # Forgive me Matz for I have sinned.
-        for name in names
-          eval <<-EVAL
-            def self.#{name}(options = {})
-              records(path + "#{name}", options)
-            end
-          EVAL
-        end
-      end
-
-      # Defines association methods for things such as comments on questions.
-      def association(assoc)
-        instance_eval do
-          assoc = assoc.to_s
-          define_method("#{assoc}=") do |records|
-            instance_variable_set("@#{assoc}", records.map { |record| "Stacked::#{assoc.classify}".constantize.new(record) })
-          end
-
-          define_method(assoc) { instance_variable_get("@#{assoc}") }
-        end
+        result = StringIO.new(get(p, :query => { :key => key }.merge!(options)).body)
+        JSON.parse(Zlib::GzipReader.new(result).read)
       end
 
       # The path to the singular resource.
       def singular(id)
-        path + id.to_s
+        path + '/' + id.to_s
+      end
+      
+      # The path to either a singular or multiple resources.
+      def path_with_ids(ids)
+        path + '/' + ids.join(';')
+      end
+      
+      # Convert a user result into a collection of Stacked::User objects.
+      def parse_users(result)
+        parse(result['users'], "Stacked::User".constantize)
       end
 
       private
 
-      # The root URL of the API,
+      # The root URL of the API.
       def base
-        Pathname.new("http://api.stackoverflow.com/0.5/")
+        Stacked::Client.base_url
       end
 
-      # The key to let us in.
+      # The api key to let us in.
       def key
-        "knockknock"
+        Stacked::Client.api_key
       end
       
       # Convert the records into actual objects.
@@ -82,9 +86,7 @@ module Stacked
 
       # The path to this particular part of the API.
       # Example if the class is Stacked::Question:
-      #
-      # http://api.stackoverflow.com/0.5/questions
-      
+      #   http://api.stackoverflow.com/1.0/questions
       def path
         base + resource
       end
@@ -94,66 +96,31 @@ module Stacked
         self.to_s.demodulize.downcase.pluralize
       end
     end
-
-    # Convert an answers result into a collection of Stacked::Answer objects.
-    def parse_answers(result)
-      parse_type(result, "answer")
-    end
-
-    # Convert a badges result into a collection of Stacked::Badge objects.
-    def parse_badges(result)
-      parse_type(result, "badge")
-    end
-
-    # Convert a comments result into a collection of Stacked::Comment objects.
-    def parse_comments(result)
-      parse_type(result, "comment")
-    end
-
-    # Convert a post timeline result into a collection of Stacked::Posttimeline objects.
-    def parse_post_timeline(result)
-      parse_type(result, "posttimeline")
-    end
-
-    # Convert a questions result into a collection of Stacked::Question objects.
-    def parse_questions(result)
-      parse_type(result, "question")
-    end
-
-    # Convert a reputation result into a collection of Stacked::Reputation objects.
-    def parse_reputations(result)
-      parse_type(result, "reputation")
-    end
-
-    # Convert a tags result into a collection of Stacked::Tag objects.
-    def parse_tags(result)
-      parse_type(result, "tag")
-    end
-    
-    # Convert a user timeline result into a collection of Stacked::Usertimeline objects.
-    def parse_user_timeline(result)
-      parse_type(result, "usertimeline")
-    end
     
-    # Converts the specified result into objects of the +type+ class.
-    def parse_type(result, type)
-      parse(result[type.pluralize], "Stacked::#{type.classify}".constantize)
+    # Builds attr_accessor for each attribute found in the reponse.
+    def define_attributes(hash={})
+      hash.each_pair do |key, value|
+        self.class.send(:attr_writer, key) unless respond_to?("#{key}=".to_sym)
+        self.class.send(:attr_reader, key) unless respond_to?("#{key}".to_sym)
+        send "#{key}=".to_sym, value
+      end
     end
 
     public
 
-    # Finds a post based on the +post_type+ and +post_id+
-    def post
-      "Stacked::#{post_type.classify}".constantize.find(post_id)
-    end
-
     # Creates a new object of the given class based on the attributes passed in.
-    def initialize(attributes)
-      # p self
-      # p attributes.keys.sort.map { |t| t.to_sym }
+    def initialize(attributes={})
+      define_attributes(attributes)
+      
       attributes.each do |k, v|
-        self.send("#{k}=", v)
+        attr_sym = "#{k}=".to_sym
+        self.send(attr_sym, v) if self.respond_to?(attr_sym)
       end
     end
+    
+    # Finds a post based on the +post_type+ and +post_id+
+    def post
+      "Stacked::#{post_type.classify}".constantize.find(post_id)
+    end
   end
 end