flickrmocks 0.8.15 → 0.9.0

data/lib/flickr_mocks/api/options.rb

@@ -1,62 +1,80 @@
 module FlickrMocks
   class Api
-    def self.search_options(params)
-      return {
-        :tags => self.sanitize_tags(params[:search_terms]),
-        :user_id =>  params[:owner_id],
-        :per_page =>  self.sanitize_per_page(params),
-        :page =>  self.sanitize_page(params),
-        :license => self.default(:license),
-        :media => self.default(:media),
-        :extras => self.default(:extras),
-        :tag_mode => self.sanitize_tag_mode(params)
-      }
-    end
+    # encapsulates methods that extract options from user-specified hash. Module is
+    # used internally.
+    module Options
+      # returns parameter hash required for a flickr photo search. Sample usage:
+      #
+      #   self.search(:search_terms => 'iran', :tag_mode => 'any')
+      #
+      # Accepted options include:
+      #  :search_terms : comma string containing the flickr search tags. Sample string 'lyon,france"
+      #  :owner_id : id for the photo. (either :owner_id or :search_terms must be specified
+      #  :per_page : optional string containing the maximum number of items to return for a given page
+      #  :page : optional string containing page number for the results. When page number is <= 0, it returns 1.
+      #  :tag_mode : optional string containing how the tags for :search_terms should be interpreted. Can be either 'any' or 'all'
+      def self.search(params)
+        return {
+          :tags => Api::Sanitize.tags(params[:search_terms]),
+          :user_id =>  params[:owner_id],
+          :per_page =>  Api::Sanitize.per_page_hash(params),
+          :page =>  Api::Sanitize.page_hash(params),
+          :license => Api.default(:license),
+          :media => Api.default(:media),
+          :extras => Api.default(:extras),
+          :tag_mode => Api::Sanitize.tag_mode_hash(params)
+        }
+      end
 
-    def self.interesting_options(params)
-      return {
-        :date => self.sanitize_time(params),
-        :per_page => self.sanitize_per_page(params),
-        :page =>  self.sanitize_page(params),
-        :extras => self.default(:extras)
-      }
-    end
+      
+      # returns parameter hash that is supplied for a interesting photo search. Sample usage:
+      #
+      #   self.interesting(:date => '2010-10-10')
+      #
+      # Accepted options include:
+      #  :date : string of format 'YYYY-MM-DD'. Photos of this date are retrieved. If none supplied, yesterday's date is used.
+      #  :per_page : optional string containing the maximum number of items to return for a given page
+      #  :page : optional string containing page number for the results. When page number is <= 0, it returns 1.
+      #
+      def self.interesting(params)
+        return {
+          :date => Api::Sanitize.date_hash(params),
+          :per_page => Api::Sanitize.per_page_hash(params),
+          :page =>  Api::Sanitize.page_hash(params),
+          :extras => Api.default(:extras)
+        }
+      end
 
-    def self.photo_options(params)
-      {
-        :photo_id => params[:photo_id] || params[:id] || nil,
-        :secret => params[:photo_secret] || params[:secret] || nil
-      }
-    end
-
-    def self.author_options(params)
-      options = self.search_options(params)   
-      options.delete :tags
-      options
-    end
-
-    def self.search_params(params)
-      return {
-        :search_terms => self.sanitize_tags(params[:search_terms]),
-        :owner_id => self.sanitize_tags(params[:owner_id]),
-        :base_url => params[:base_url]
-      }
-    end
-
-    def self.interesting_params(params)
-      return {
-        :date => params[:date],
-        :base_url => params[:base_url]
-      }
-    end
+      # returns parameter hash for a single photo. Sample usage:
+      #
+      #  self.photo(:photo_id => '123')
+      #
+      # Accepted options include:
+      #  :photo_id : string containing photo_id of the photo.
+      #  :id : string containing photo id of the photo. It is an alias for :photo_id. If both are present :photo_id takes precedance.
+      #  :secret : optional string containing the secret for the photo. If supplied the query is slightly faster.
+      #  :photo_secret : optional string containing the secret for the photo. It is an alias for :secret. If both supplied, :secret takes precedance.
+      def self.photo(params)
+        {
+          :photo_id => params[:photo_id] || params[:id] || nil,
+          :secret => params[:photo_secret] || params[:secret] || nil
+        }
+      end
 
-    def self.commons_institutions_params(params)
-      return {
-        :per_page => params[:per_page] || params[:perpage],
-        :current_page => params[:current_page] || params[:page] || 1
-      }
+      # returns parameter hash used for searching for photos of a given author.  Sample usage:
+      #
+      #   self.search(:owner_id => '1234')
+      #
+      # Accepted options include:
+      #  :owner_id : id for the photo. (either :owner_id or :search_terms must be specified
+      #  :per_page : optional string containing the maximum number of items to return for a given page
+      #  :page : optional string containing page number for the results. When page number is <= 0, it returns 1.
+      def self.author(params)
+        options = Api::Options.search(params)
+        options.delete :tags
+        options
+      end
     end
   end
 
- 
 end

data/lib/flickr_mocks/api/sanitize.rb

@@ -1,29 +1,138 @@
 module FlickrMocks
   class Api
-    def self.sanitize_tags(value=nil)
-      value.nil? ? value : value.downcase.split(',').map.each do |v| v.strip end.join(',')
-    end
+    # helper methods that help to clean up user supplied values. Module is
+    # used internally.
+    module Sanitize
+      # returns a lowercase stripped version of the supplied comma separated string. Sample usage:
+      #
+      #  Api.sanitize_tags('Shiraz  , HeLLo goodbye, wow')
+      #  returns 'shiraz,hello goodbye,wow'
+      def self.tags(value=nil)
+        case value
+        when nil then
+          nil
+        when String then
+          value.downcase.split(',').map.each do |v| v.strip end.join(',')
+        else
+          raise ArgumentError
+        end
+      end
 
-    def self.sanitize_per_page(params={})
-      params[:per_page] || params[:perpage] || self.default(:per_page)
-    end
+      # returns lowercase stripped version of the supplied string stored in the :search_terms key of the
+      # supplied hash. Sample usage:
+      #
+      #  self.sanitize_tags(:search_terms => 'Shiraz  , HeLLo goodbye, wow')
+      #  returns 'shiraz,hello goodbye,wow'
+      def self.tags_hash(options={})
+        raise ArgumentError unless options.is_a?(Hash)
+        self.tags(options[:search_terms])
+      end
 
-    def self.sanitize_page(params={})
-      [nil,0,'0'].include?(params[:page]) ? '1' : params[:page].to_i.to_s
-    end
+      # returns the per page entry if supplied otherwise returns the default per page value.
+      # Sample usage:
+      #
+      #  self.per_page('10')
+      #  returns '10'
+      def self.per_page(value=nil)
+        case value
+        when String then
+          value.to_i > 0 ? value.to_i.to_s : Api.default(:per_page)
+        when Fixnum then
+          value > 0 ? value.to_i.to_s :  Api.default(:per_page)
+        when nil then
+          Api.default(:per_page)
+        else
+          raise ArgumentError
+        end
+      end
 
-    def self.sanitize_tag_mode(params={})
-      self.default(:flickr_tag_modes).include?(params[:tag_mode].to_s.downcase.strip) ?
-        params[:tag_mode].to_s.downcase.strip : self.default(:tag_mode)
-    end
+      # returns the per page entry stored in the :per_page key of the supplied options hash.
+      # Sample usage:
+      #
+      #  self.per_page_hash(:per_page => '10')
+      #  returns '10'
+      def self.per_page_hash(options={})
+          if options[:per_page]
+            self.per_page(options[:per_page])
+          elsif options[:perpage]
+            self.per_page(options[:perpage])
+          else
+            self.per_page(nil)
+          end
+      end
+
+      # returns the page number. Ensures that return value is string containing an integer
+      # greater than 0. When nonsensical page supplied, default page '1' is returned. Sample usage:
+      #
+      #   self.page('20')
+      #   returns '20'
+      def self.page(value={})
+        case value
+        when Fixnum then
+          value > 0 ? value.to_s : Api.default(:page)
+        when NilClass then
+          Api.default(:page)
+        when String
+          value.to_i > 0 ? value.to_i.to_s : Api.default(:page)
+        else
+          raise ArgumentError
+        end
+      end
+
+      # returns the page number contained in the :page key of the supplied hash. Sample usage:
+      #
+      #  self.page(:page => '20')
+      #  returns '20'
+      def self.page_hash(options={})
+          self.page(options[:page])
+      end
+
+      # returns tag mode. It ensures that a valid tag mode is returned. If an invalid
+      # tag_mode is supplied it returns the default tag mode 'all'. Sample usage:
+      #
+      #  self.tag_mode('any')
+      #  returns 'any'
+      def self.tag_mode(value=nil)
+        case value
+        when String then
+         Api.default(:possible_tag_modes).include?(value.to_s.downcase) ?
+           value.to_s.downcase : Api.default(:tag_mode)
+        when nil then
+          Api.default(:tag_mode)
+        else
+          raise ArgumentError
+        end
+      end
+
+      # returns tag_mode contained in the :tag_mode key of the supplied hash. Sample usage:
+      #
+      #   self.tag_mode(:tag_mode => 'any')
+      #   returns 'any'
+      def self.tag_mode_hash(options={})
+        self.tag_mode(options[:tag_mode].to_s.downcase.strip)
+      end
+
+      # returns a string of format YYYY-MM-DD. Accepts either a Time object or a string as
+      # an argument. If invalid date supplied the string corresponding to yesterday's date is returned.
+      # Sample usage:
+      #   self.date('2010-10-10')
+      #   returns => '2010-10-10'
+      def self.date(value=nil)
+        case value
+        when String then Api::Helpers.date(value)
+        when Time then value.strftime('%Y-%m-%d')
+        else Api::Helpers.date('yesterday')
+        end
+      end
 
-    def self.sanitize_time(params={})
-      date = params[:date]
-      case date
-      when Time then date.strftime('%Y-%m-%d')
-      when String then self.time(date)
-      else self.time('yesterday')
+      # returns string of format YYYY-MM-DD corresponding to the value stored in the :date
+      # key of the options hash. Sample usage:
+      #
+      #  self.date_hash(:date => '2010-10-10')
+      #  returns '2010-10-10'
+      def self.date_hash(options={})
+        self.date(options[:date])
       end
     end
   end
-end
+end

data/lib/flickr_mocks/fixtures.rb

@@ -2,6 +2,12 @@ require 'ostruct'
 require 'singleton'
 
 module FlickrMocks
+  # contains fixtures for various FlickRaw responses. This class is used internally.
+  # For stubbing FlickrRaw APIs for your Rspec 2.0 please refer to the
+  # FlickrMocks::Stubs class. This is a singleton class. To access the singleton
+  # class instance you can call:
+  #
+  #   Fixtures.instance
   class Fixtures
     include Singleton
     attr_accessor :photos,:interesting_photos,:author_photos,:photo,:photo_details,
@@ -25,9 +31,9 @@ module FlickrMocks
       @empty_photos = load_fixture(:empty_photos)
 
       @expected_methods = load_fixture(:expected_methods)
-
     end
 
+    # returns directory where fixtures are stored.
     def self.repository
       File.expand_path(File.dirname(__FILE__) + '/../../spec/fixtures') + '/'
     end

data/lib/flickr_mocks/flickraw/custom_clone.rb

@@ -1,7 +1,9 @@
 module FlickrMocks
 
+  # module is included in classes that wrap the FlickRaw::Response and FlickRaw::ResponseList
+  # objects. Module is used internally.
   module CustomClone
-
+    # special ruby method that overrides Ruby's cloning method. 
     def initialize_copy(orig)
       super
       cloned = @h.clone

data/lib/flickr_mocks/flickraw/custom_compare.rb

@@ -1,6 +1,10 @@
 module FlickrMocks
 
+  # module that contains methods that contain custom '==' check. This module is
+  # used internally and is included in the FlickrMocks::Models.
   module CustomCompare
+    # custom equality method that is added in various classes to override Ruby's default
+    # '==' behavior
     def ==(other)
       return false if other.nil?
       return false unless other.is_a?(self.class)

data/lib/flickr_mocks/flickraw/custom_marshal.rb

@@ -1,12 +1,16 @@
 module FlickrMocks
 
+  # contains custom methods that allow the marshaling of FlickRaw::Response and
+  # FlickRaw::ResponseList objects. FlickRaw responses contain singleton methods that
+  # can not be marshaled by default. This module is used internally
   module CustomMarshal
 
-    def self.included(base)
+    def self.included(base) 
       base.extend ClassMethods
     end
     
-    module ClassMethods
+    module ClassMethods    
+      # used to un-marshal FlickRaw responses
       def _load(string)
         data = Marshal.load(string)
         type = data.delete('flickr_type')
@@ -14,6 +18,7 @@ module FlickrMocks
       end
     end
 
+    # used to marshal FlickRaw responses
     def _dump(level)
       result = marshal_flickraw(self)
       result["flickr_type"] = self.flickr_type

data/lib/flickr_mocks/flickraw/flickraw.rb

@@ -1,11 +1,17 @@
+
+# adds custom cloning, marshaling and compare methods to the FlickRaw::Response
+# and FlickRaw::ResponseList class. These additional methods help in testing
+# the FlickrMocks models.
 module FlickRaw
 
+  # adds custom cloning, marshaling and compare methods to FlickRaw::Response class
   class Response
     include FlickrMocks::CustomMarshal
     include FlickrMocks::CustomCompare
     include FlickrMocks::CustomClone
   end
 
+  # adds custom cloning, marshaling and compare methods to FlickRaw::ResponseList class
   class ResponseList
     include FlickrMocks::CustomMarshal
     include FlickrMocks::CustomCompare

data/lib/flickr_mocks/helpers.rb

@@ -1,16 +1,21 @@
 module FlickrMocks
+  # contains various helper methods for comparing and marshaling FlickRaw::Response and
+  # ResponseList objects.
   module Helpers
-
     class << self
+      # returns the file extension used to store the marshaled FlickRaw fixtures
       def extension
         ".marshal"
       end
 
+      # returns the file name for the marshaled FlickRaw fixture
       def fname_fixture(symbol)
         raise RunTimeError unless symbol.is_a? Symbol
         symbol.to_s + extension
       end
 
+      # compares two FlickRaw::Response or two FlickRaw::ResponseList.
+      # It recursively checks the internal state of these two objects.
       def equivalent?(a,b)
         return false if a.class != b.class
         case a
@@ -30,6 +35,7 @@ module FlickrMocks
         end
       end
 
+      # saves the marshaled version of the supplied object into a file
       def dump(response,file)
         begin
           f  = File.open(file,'w')
@@ -39,6 +45,7 @@ module FlickrMocks
         end
       end
 
+      # returns the un-marshaled contents of the user-specified file
       def load(file)
         begin
           f=File.open(file,'r')

data/lib/flickr_mocks/models/commons_institution.rb

@@ -1,45 +1,55 @@
 
 module FlickrMocks
-  class CommonsInstitution
-    def initialize(object)
-      self.delegated_to_object = object
-    end
-    
-    def launch_date
-      @delegated_to_object.date_launch
-    end
+  module Models
+    class CommonsInstitution
+      def initialize(object)
+        self.delegated_to_object = object
+      end
 
-    def owner_id
-      @delegated_to_object.nsid
-    end
-    alias :owner :owner_id
+      # returns the launch date for the commons institution
+      def launch_date
+        @delegated_to_object.date_launch
+      end
 
-    def owner_name
-      @delegated_to_object.name
-    end
+      # returns the Owner id for the commons institution
+      def owner_id
+        @delegated_to_object.nsid
+      end
+      alias :owner :owner_id
 
-    def  flickr_url
-      get_url(:flickr)
-    end
+      # returns name of the commons institution
+      def owner_name
+        @delegated_to_object.name
+      end
 
-    def site_url
-      get_url(:site)
-    end
-    
-    def license_url
-      get_url(:license)
-    end
+      # returns flickr web address for the institution
+      def  flickr_url
+        get_url(:flickr)
+      end
 
-    def ==(other)
-      @delegated_to_object == other.instance_eval('@delegated_to_object')
-    end
+      # returns external web address for the institution
+      def site_url
+        get_url(:site)
+      end
 
-    def initialize_copy(orig)
-      super
-      @delegated_to_object = @delegated_to_object.clone
-    end
-    
-    private
+      # returns the url that describes the licensing
+      def license_url
+        get_url(:license)
+      end
+
+      # returns true if supplied object is equivalent to self
+      def ==(other)
+        @delegated_to_object == other.instance_eval('@delegated_to_object')
+      end
+
+      # customizes the cloning behavior of the object. Internal state of cloned object
+      # will not point to original object. 
+      def initialize_copy(orig) 
+        super
+        @delegated_to_object = @delegated_to_object.clone
+      end
+
+      private
       def delegated_to_object=(object)
         raise ArgumentError, "Expected object of class FlickRaw::Response but received #{object.class}" unless object.class == FlickRaw::Response
         @delegated_to_object = object
@@ -52,5 +62,6 @@ module FlickrMocks
       def get_url_index(type)
         @delegated_to_object.urls.map do |url| url['type'].to_sym end.find_index(type.to_sym)
       end
+    end
   end
 end