starwars 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ad657666a52a78f6326d5781ee9f1c12f19e5b54
-  data.tar.gz: 07fefe6fd93d76fb5bf6184093608379a7252147
+  metadata.gz: 8b3c2a3fcfdfe161e04b8f4e5680513ce45fb5ed
+  data.tar.gz: 2c0a63b841991f163d15156d2f42ec1644eb7320
 SHA512:
-  metadata.gz: 6b9c5802184691e8e1337a9048488e5b2d0fd8d258c799e9526fc065c7456d1f3bfff9a3ccc83a3a05d8978007ea55d661fae4f38f75dc91b8d36589034ce952
-  data.tar.gz: bda6c580a84b436c3eb057ee174de48f3253556eb13f227c140d5d92c23c60f09ced5d58088b97640ee233bbd3d1367714dbe7bfd04718a104c2557ec9a9d279
+  metadata.gz: 438b2c0f53551ed7bf5ee790bbe2bd052282f5838636ff4e4b1ec9c47c167f9ca9db11bfbddb9291eb520b7383bf52e4ea8f6a93ea0fa9be35a9a017199c15b6
+  data.tar.gz: 6638b91db1386184b23ed1f29d9841f3d2f177738126d289c496028560bdd6714ea70f7c4d5775e9c7a1adf9a0b5d8f0736970e2ab89512cb7256bdfb3dd1d50

data/.rubocop.yml

@@ -1,2 +1,2 @@
 Metrics/LineLength:
-  Max: 140
+  Max: 160

data/.travis.yml

@@ -19,6 +19,7 @@ matrix:
     - rvm: jruby-20mode
     - rvm: jruby-21mode
     - rvm: rbx-2
+    - rvm: jruby-19mode
   fast_finish: true
 branches:
   only: master

data/README.md

@@ -1,5 +1,9 @@
 # Starwars
 
+[![Coverage Status](https://coveralls.io/repos/moski/starwars/badge.png?branch=master)](https://coveralls.io/r/moski/starwars?branch=master)
+[![Build Status](https://travis-ci.org/moski/starwars.svg?branch=master)](https://travis-ci.org/moski/starwars)
+[![Inline docs](http://inch-ci.org/github/moski/starwars.svg?branch=master&style=flat)](http://inch-ci.org/github/moski/starwars)
+
 A Ruby interface for http://swapi.co/ - the Star Wars API
 ![Starwars](https://s3.amazonaws.com/f.cl.ly/items/1r2F2K460v1R2o011n1M/star-wars-evolution-evolution-funny.jpg)
 
@@ -26,29 +30,69 @@ Or install it yourself as:
 
     $ gem install starwars
 
+
+## Available Resources
+
+* `Starwars::Person` ([see docs](https://github.com/moski/starwars/blob/master/lib/starwars/resources/person.rb))
+* `Starwars::Film` ([see docs](https://github.com/moski/starwars/blob/master/lib/starwars/resources/film.rb))
+* `Starwars::Planet` ([see docs](https://github.com/moski/starwars/blob/master/lib/starwars/resources/planet.rb))
+* `Starwars::Specie` ([see docs](https://github.com/moski/starwars/blob/master/lib/starwars/resources/specie.rb))
+* `Starwars::Starship` ([see docs](https://github.com/moski/starwars/blob/master/lib/starwars/resources/starship.rb))
+* `Starwars::Vehicle` ([see docs](https://github.com/moski/starwars/blob/master/lib/starwars/resources/vehicle.rb))
+
 ## Usage
-    require "starwars"
-    luke = Starwars::Person.fetch(1)
-    puts luke.name
-    puts luke.height
 
-    falcon = Starwars::Spaceship.new(id: 10)
-    falcon.fetch
-    puts falcon.name
-    puts falcon.pilots
+All the resources defined above have 2 functions, `#fetch` and `#fetch_all` 
+
+## #Fetch
+
+`#fetch` is used to fetch a single resource via ID or Resource URL
+
+```ruby
+Starwars::Person.fetch(1).name
+Starwars::Person.fetch('http://swapi.co/api/people/3/').name
+```
+
+## #fetch_all
+
+`#fetch_all` is used to fetch all resources via pagination 
+
+```ruby
+planets = Starwars::Planet.fetch_all
+
+# to access the items use #items
+planets.items.map(&:name)
+planets.items.each{|item| p item.inspect}
+
+# you can also use #results instead of iteams
+planets.results.map(&:name)
+```
+
+## Pagination
+
+using `#fetch_all` will yield a pagination response:
+
+```ruby
+starships = Starwars::Starship.fetch_all
+p starships.number_of_pages
+p starships.last_page?
+p starships.next_page?
+```
+
+To iterate pages you can use the following interface:
+
+```ruby
+Starwars::Starship.fetch_all.each{|page|
+  p page.next
+  p page.previous
+  p page.results.size
+}
+```
 
-  you can also nest the quries, such as:
-    
-    falcon.pilots.each do |piolt|
-      puts piolt.fetch.name
-    end
+## Documentation
 
-  You can load a resouce by url:
+the gem is fairly documented. Browse the YARD [documentaion](http://rubydoc.info/gems/starwars/) for more information.
 
-    aldeeran = Starwars::Planet.new(url: 'http://swapi.co/api/planets/3/').fetch
-    puts aldeeran.name
-    puts aldeeran.residents
-    puts aldeeran.population
 
 ## Contributing
 
@@ -56,4 +100,4 @@ Or install it yourself as:
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+5. Create a new Pull Request

data/lib/starwars.rb

@@ -1,6 +1,7 @@
 require 'starwars/version'
 require 'starwars/base'
-require 'starwars/fetcher'
+require 'starwars/request'
+require 'starwars/cursor'
 
 # Avoid circuler require issues :(
 module Starwars
@@ -11,9 +12,17 @@ module Starwars
   class Vehicle < Starwars::Base; end
   class Starship < Starwars::Base; end
 end
-require 'starwars/planet'
-require 'starwars/person'
-require 'starwars/specie'
-require 'starwars/vehicle'
-require 'starwars/starship'
-require 'starwars/film'
+require 'starwars/resources/planet'
+require 'starwars/resources/person'
+require 'starwars/resources/specie'
+require 'starwars/resources/vehicle'
+require 'starwars/resources/starship'
+require 'starwars/resources/film'
+
+# Resources with pagination
+require 'starwars/resources/paginated/planets'
+require 'starwars/resources/paginated/films'
+require 'starwars/resources/paginated/people'
+require 'starwars/resources/paginated/species'
+require 'starwars/resources/paginated/starships'
+require 'starwars/resources/paginated/vehicles'

data/lib/starwars/base.rb

@@ -1,8 +1,7 @@
 require 'roar/json'
 require 'roar/client'
 require 'roar/coercion'
-require 'ostruct'
-require 'equalizer'
+require 'starwars/overrides/ostruct'
 require 'virtus'
 
 module Starwars
@@ -10,6 +9,10 @@ module Starwars
   # Base Class for fetching all the data from the remote api.
   # All Classes should inhert from this class.
   #
+  # Abstract base class for the different resources.
+  # Provides some helper methods for the resources.
+  #
+  # @abstract
   class Base < OpenStruct
     include Roar::JSON
     include Roar::Client
@@ -18,36 +21,137 @@ module Starwars
     BASE_URL = 'http://swapi.co/api'
     FORMAT = 'application/json'
 
+    #
+    # Class level methods for resources to fetch data from api
+    # @abstract
+    class << self
+      #
+      # Fetch an object by id or URL
+      # @param [String, Integer] param String for full resouce url or the resouce id
+      # @return [Person, Film, Planet, Specie, Starship, Vehicle]
+      # @example Fetch person by id
+      #   Starwars::Person.fetch(1)
+      #
+      # @example Fetch person by url
+      #   Starwars::Person.fetch("http://swapi.co/api/people/2/")
+      # @api public
+      def fetch(param)
+        object = new(url: link(param))
+        Starwars::Request.new(object.request_attributes).perform_request
+      end
+
+      #
+      # Fetch all resource data page by page
+      # @return [People, Films, Planets, Species, Starships, Vehicles]
+      # @example Fetch Planets page by page
+      #   Starwars::Planet.fetch_all.each do |page|
+      #     puts page.items.size
+      #   end
+      # @api public
+      def fetch_all
+        klass_name =  Starwars.const_get(name.split('::').last).const_get('RESOURCE_NAME')
+        object = Starwars.const_get("#{klass_name.capitalize}").new(url: "#{Starwars::Base::BASE_URL}/#{klass_name}/")
+        Starwars::Request.new(resource: object, uri: object.url, params: {}).perform_request
+      end
+
+      protected
+
+      #
+      # Generate a resource link based on the passed params
+      # @param [String, Integer] param String for full resouce url or the resouce id
+      # @return [String] resouce link
+      # @api private
+      def link(param)
+        if param.is_a? String
+          param
+        else
+          "#{Starwars::Base::BASE_URL}/#{const_get('RESOURCE_NAME')}/#{param}/"
+        end
+      end
+    end
+
+    # The time the resource was created
+    # @return [Time]
+    # @example
+    #   film.created
+    # @api public
+    property :created, type: Time
+
+    # The time the resource was edited
+    # @return [Time]
+    # @example
+    #   film.edited
+    # @api public
+    property :edited, type: Time
+
+    # The resource unique id
+    # @return [Integer]
+    # @example
+    #   film.id #=> 1
+    # @api public
+    property :id, type: Integer
+
+    # The hypermedia URL of this resource
+    # @return [String]
+    # @example
+    #   film.url #=> 'http://swapi.co/api/films/1/'
+    # @api public
+    property :url
+
+    #
+    # Overide the == method for any resource to check the ID and URL
+    # @param  [People, Films, Planets, Species, Starships, Vehicles] other
+    # @return [Boolean]
+    # @example If id's and urls are equal
+    #   Starwars::Planet.new(id: 1, url: "/some") == Starwars::Planet.new(id: 1, url: "/some") #=> true
+    # @example If id's and urls are equal
+    #   Starwars::Planet.new(id: 2, url: "/some") == Starwars::Planet.new(id: 1, url: "/some") #=> false
+    # @example If id's and urls are equal
+    #   Starwars::Planet.new(id: 1, url: "/some1") == Starwars::Planet.new(id: 1, url: "/some") #=> false
+    # @api public
     def ==(other)
       id == other.id && url == other.url
     end
 
-    def fetch(resource_name)
-      #
-      # If the url is set, then fetch using the resource url
-      #
+    #
+    # Fetch a resource if the ID or URL is set
+    # @return [Person, Film, Planet, Specie, Starship, Vehicle]
+    # @example Fetch person by id
+    #   Starwars::Person.new(id: 1).fetch
+    #
+    # @example Fetch person by url
+    #   Starwars::Person.new(url: "http://swapi.co/api/people/2/").fetch
+    # @api public
+    def fetch
+      Starwars::Request.new(request_attributes).perform_request
+    end
+
+    #
+    # Generate the Request initialize params
+    # @param [Hash] opts the options to create a Request with.
+    # @option opts [Person, Film, Planet, Specie, Starship, Vehicle] :resource
+    # @option opts [String] :uri resource uri
+    # @option opts [Hash] :params other params
+    # @return [Hash]
+    # @api private
+    def request_attributes(opts = {})
+      { resource: self, uri: link, params: {} }.merge(opts)
+    end
+
+    protected
+
+    #
+    # Generate a resource link from the URL or id
+    # @return [String] resource link
+    # @raise [Starwars::Error::ArgumentError] if no id or url
+    # @api private
+    def link
       if url
-        get(uri: url, as: FORMAT)
-      #
-      # Try to fetch using the resource name and ID
-      #
+        url
       elsif id
-        get(uri: "#{BASE_URL}/#{resource_name}/#{id}/", as: FORMAT)
+        "#{Starwars::Base::BASE_URL}/#{self.class::RESOURCE_NAME}/#{id}/"
       else
-        fail 'error'
-      end
-    end
-    class << self
-      def fetch(resources, id)
-        #
-        # Special case for person and people, instead of removing the s
-        #
-        if (resources == 'people')
-          resources = 'person'
-        else
-          resources.slice!(-1, 1)
-        end
-        Starwars.const_get(resources.capitalize).new(id: id).fetch
+        fail(Starwars::Error::ArgumentError.new('Please use id or url to fetch resouce', nil))
       end
     end
   end

data/lib/starwars/cursor.rb

@@ -0,0 +1,110 @@
+module Starwars
+  #
+  # A pagination container for starwars
+  #
+  class Cursor < Starwars::Base
+    include Enumerable
+
+    #
+    # including Enumerable adds a "count" method to the class
+    # and for some reason:
+    # property :count, as: number_of_pages
+    # is not working, i am not sure it's a roar thing or from the representable gem.
+    # As a workaround, lets create "number_of_pages" method that returns
+    # the count property
+    # @todo - check why as: is not working
+    property :count
+
+    #
+    # Next holds the URL for the next page. If there is no next page, next
+    # should be set to nil
+    property :next
+
+    #
+    # Previous holds the URL for the previous page. If there is no previous
+    # page previous should be set to nil
+    property :previous
+
+    # Results contains the results within the page.
+    #
+    collection :results
+
+    # A wrapper to get the pages count from the api
+    # @return [Integer]
+    # @example get the total number of pages
+    #   Starwars::Planet.fetch_all.number_of_pages
+    # @example get the total number of pages
+    #   Starwars::Starship.fetch_all.number_of_pages
+    # @api public
+    def number_of_pages
+      self[:count]
+    end
+
+    # A wrapper to get the results within a page
+    # @note This wrapper is needed to define the items alias method
+    # @return [Array]
+    # @example Return the items array within the page
+    #   Starwars::Planet.fetch_all.results
+    #   Starwars::Planet.fetch_all.items
+    # @api public
+    def results
+      self[:results]
+    end
+
+    # Checks wheather this is the last page
+    # @return [Boolean]
+    # @example are we at the last page?
+    #   Starwars::Planet.fetch_all.last_page?
+    # @api public
+    def last_page?
+      !next_page?
+    end
+
+    # Checks wheather this there is more pages
+    # @return [Boolean]
+    # @example do we have a next page?
+    #   Starwars::Planet.fetch_all.next_page?
+    # @api public
+    def next_page?
+      !self.next.nil?
+    end
+
+    # Returns the next page
+    # @return [Starwars::Base]
+    # @example fetch the next page
+    #   page = Starwars::Planet.fetch_all
+    #   page.next_page
+    # @api public
+    def next_page
+      return if last_page?
+      perform_request
+    end
+
+    # Yields the subsequent page responses to a given block
+    # @yieldparam [Starwars::Base] response
+    # @return [Enumerable, nil]
+    # @example fetch the next page
+    #   Starwars::Planet.fetch_all.each_page{|page| p page.items.map(&:name)}
+    #   Starwars::Planet.fetch_all.each{|page| p page.items.map(&:name)}
+    #   Starwars::Planet.fetch_all.each_with_index{|page, index|
+    #     p page.items.map(&:name)
+    #   }
+    # @api public
+    def each_page
+      return to_enum(__callee__) unless block_given?
+      yield(next_page) until last_page?
+    end
+
+    alias_method :each, :each_page
+    alias_method :items, :results
+
+    private
+
+    # Delegate to the request class to perform fetch data from remote server
+    # @return [People, Films, Planets, Species, Starships, Vehicles]
+    # @api private
+    def perform_request
+      Request.new(request_attributes(uri: self.next)).perform_request
+    end
+  end
+end