tagcrumbs 0.3.1

data/lib/tagcrumbs/requestor.rb

@@ -0,0 +1,140 @@
+module Tagcrumbs
+  # The Requestor class is used to make the actual requests to the Tagcrumbs web service 
+  # It uses the OAuth gem to make the requests.
+  
+  class Requestor    
+    attr_accessor :options, :response
+    
+    # A Requestor can have custom options. If no custom options are specified the general Tagcrumbs.options are used.
+    # You can use this to have a Requestor with different consumer tokens for example.
+    def initialize(options = {})
+      options.reverse_merge!(Tagcrumbs.options) 
+      self.options = options.with_indifferent_access
+    end
+    
+    # ================
+    # = OAuth Tokens =
+    # ================
+    
+    # Returns the OAuth consumer token
+    def consumer
+  		@consumer ||= ::OAuth::Consumer.new(options[:consumer_token], options[:consumer_secret], options[:consumer_options])
+  	end
+  	
+  	# Requests a Request Token from the web service or builds it from the options
+  	def request_token
+  	  return @request_token if defined?(@request_token)
+  	  
+  	  if options[:request_token] && options[:request_secret]
+  	    @request_token = ::OAuth::RequestToken.new(consumer, options[:request_token], options[:request_secret])
+	    else
+	      @request_token = consumer.get_request_token
+      end
+  	end
+  	
+  	# Exchanges a Request Token against an Access Token that has to be saved and used for all further calls to the webservice.
+  	def exchange_request_token!
+  		@access_token = request_token.get_access_token
+  	end
+    
+    # Returns the configured access token. Calls should be made with the get, post, put and delete methods, direct access to this
+    # should usually not be needed.
+  	def access_token
+  	  return @access_token if defined?(@access_token)
+  	  
+  	  if options[:access_token] && options[:access_secret]
+  	    @access_token = ::OAuth::AccessToken.new(consumer, options[:access_token], options[:access_secret])
+	    else
+	      nil
+      end
+  	end
+    
+    # ========
+    # = HTTP =
+    # ========
+  	
+  	# Create a custom request to the webservice
+  	# If an access token is configured it will be used to make webservice calls (3-legged oauth)
+  	# If a consumer is configured and it is a get request only it will make 2-legged oauth calls
+  	def request(http_method, path, query_string = {}, body = '', headers = {})
+  	  url = path_with_query_string(path, query_string)
+  	  arguments = body.present? ? [body, default_headers.merge(headers)] : [default_headers.merge(headers)]
+  	  
+  	  if access_token # 3-legged request with access token
+  	    response = self.access_token.request(http_method, url, *arguments)
+      elsif http_method == :get && consumer # 2-legged consumer only request
+        response = self.consumer.request(:get, url, nil, {}, *arguments)        
+      else
+        raise InvalidRequest.new("Setup the Access Token first or only make get requests with a valid consumer.")
+      end
+
+      handle_response(response)
+  	end
+  	
+  	# Create a get request on path, optionally pass a hash of query parameters
+  	# Can also be used with 2-legged oauth to request public resources
+  	def get(path, query_string = {})
+  	  request(:get, path, query_string)
+  	end
+  	
+  	# Post body to path, access_token needed
+  	def post(path, body='')
+  	  request(:post, path, {}, body)
+  	end
+  	
+  	# Put body to path, access_token needed
+  	def put(path, body='')
+  	  request(:put, path, {}, body)
+  	end
+  	
+  	# Delete a resource, access_token needed
+  	def delete(path)
+  	  request(:delete, path)
+  	end
+  	
+  	# Return the format of the response object
+  	def response_format
+      raise 'Request a resource first' unless response
+      
+      Tagcrumbs.supported_formats.each do |format, content_types|
+        return format if content_types.include?(response.content_type)
+      end
+      
+      :xml 
+    end
+  	
+  	private
+  	  # Build a URL from a path and a hash of query string parameters
+  	  def path_with_query_string(path, arguments = {})
+  	    if arguments.present?
+  	      path + '?' + arguments.to_param
+	      else
+	        path
+        end
+  	  end
+  	  
+  	  # Handle responses from the webservice, raise an error on unexpected HTTP response codes
+    	def handle_response(response)
+    	  self.response = response
+    	  case response.code
+    	    when '200', '201', '422': # ok, created, invalid
+            response
+          else
+            response.error!
+  	    end
+    	end
+  	  
+  	  # Set the Content-Type and Accept HTTP Headers to the correct values depending on format
+    	def default_headers(format = nil)
+    	  format ||= self.options[:format]
+        
+        raise UnsupportedFormat unless Tagcrumbs.supported_formats[format]
+      	  
+    	  {
+    	    "Content-Type" => Tagcrumbs.supported_formats[format].first,
+    	    "Accept" => Tagcrumbs.supported_formats[format].join(', ')
+    	  }
+    	end
+    
+  end
+end

data/lib/tagcrumbs/resources/array.rb

@@ -0,0 +1,108 @@
+module Tagcrumbs
+  # Basically a regular Array that holds many Resources.
+  # Used to get collections from the webservice.
+  class Array < Resource
+    ATTRIBUTES = [:total_entries, :pages, :per_page, :page, :sort, :order, :next_page, :previous_page]
+    
+    attr_accessor :array
+    attr_reader *ATTRIBUTES
+    
+    # set instance variables and automatically convert them to real integers if they are an integer
+    ATTRIBUTES.each do |a|
+      define_method "#{a}=" do |value|
+        begin
+          typecasted_value = Integer(value)
+        rescue ArgumentError
+          typecasted_value = value
+        ensure
+          self.instance_variable_set("@#{a}", typecasted_value)
+        end
+      end
+    end
+        
+    def initialize
+      reset!
+    end
+    
+    # Reset the state of the Array
+    def reset!
+      super
+      @array = []  
+
+      true
+    end
+    
+    # Replace the Array with the next page of elements if there is one
+    def next_page!
+      reload(next_page) if next_page.present?
+    end
+    
+    # Replace the Array with the privious page of elements if there is one
+    def previous_page!
+      reload(previous_page) if previous_page.present?
+    end
+    
+    # Iterate over all pages
+    def each_page(args={})
+      begin
+        yield(self)
+      end while(args[:reverse] == true ? previous_page! : next_page!)
+    end
+    
+    # Iterate over all items with pagination
+    def each_page_each_item(args={})
+      self.each_page(args) do |array|
+        array.each do |item|
+          yield item
+        end
+      end
+      
+    end
+    
+    # Set the properties and typecast some attributes automatically
+    def properties=(properties)
+      super
+      
+      self.properties.each do |key, value|
+        send("#{key}=", value) if ATTRIBUTES.include?(key.to_sym)
+      end
+    end
+    
+    # delegate unkown methods to the underlying array
+    def method_missing(name, *args, &block)
+      if @array.respond_to?(name)
+        @array.send(name, *args, &block) 
+      else
+        super
+      end
+    end
+    
+    def inspect
+      @array.inspect
+    end
+    
+    # Load data into the object from a document
+    def initialize_from_document(parser, format = Tagcrumbs.options[:format])
+      parser = super
+                  
+      if self.loaded?
+        nodes = parser.nodes_with_name(parser.name.singularize)
+        return if nodes.blank?
+        
+        nodes.each do |node|
+          node_parser = Parser.new_for_format(node, parser.format)
+          node_type = node_parser.get_attribute('type')
+          
+          if node_type # a nested model
+            @array << Tagcrumbs.class_by_type(node_type).new_from_document(node, parser.format)
+          else # a nested node
+            @array << node_parser.get_value 
+          end
+        end
+      end
+    end
+
+
+    
+  end
+end

data/lib/tagcrumbs/resources/models/accessors.rb

@@ -0,0 +1,252 @@
+module Tagcrumbs
+  module Accessors
+    def self.included(base)
+      base.class_eval do
+        extend(ClassMethods)
+        
+        # class variables that save the options for attributes and associations
+        class_inheritable_accessor :writeable_attributes_options
+        class_inheritable_accessor :readable_attributes_options
+        class_inheritable_accessor :has_one_associations_options
+        class_inheritable_accessor :has_many_associations_options
+        class_inheritable_accessor :can_be_options
+        
+        self.can_be_options ||= []
+        self.writeable_attributes_options ||= {}
+        self.readable_attributes_options ||= {}
+        self.has_one_associations_options ||= {}
+        self.has_many_associations_options ||= {}
+      end
+    end
+    
+    # The nodes contain the values that were read from the web service
+    def nodes
+      @nodes ||= {}
+    end
+    
+    # nodes_updates contain the changes that were done to nodes
+    def nodes_updates
+      @nodes_updates ||= {}
+    end
+    
+    # has_one_associations contain the related objects
+    def has_one_associations
+      @has_one_associations ||= {}
+    end
+    
+    # has_one_associations_updates contain updates of the related objects
+    def has_one_associations_updates
+      @has_one_associations_updates ||= {}
+    end
+    
+    # has_many_associations contains Arrays of further objects
+    def has_many_associations
+      @has_many_associations ||= {}
+    end
+    
+    # Restore back to the original state, discard any changes that were done after the object
+    # was loaded
+    def restore!
+      @nodes_updates = {}
+      @has_one_associations_updates = {}
+      
+      true
+    end
+    
+    # Set attributes with a hash
+    def attributes=(args={})
+      args.each do |k, v|
+        if respond_to?("#{k}=")
+          self.send("#{k}=", v)
+        end
+      end
+    end
+    
+    # Return all attributes dynamically, pass :modifiable_only => true to only return
+    # modifiable arguments
+    def attributes(args={})      
+      hash = {}
+
+      self.class.attributes(args).each do |k|
+        hash[k] =  send(k)
+      end
+      
+      hash
+    end
+    
+    # Nice output for console testing
+    def inspect
+      attributes_for_inspect = []
+      attributes.each{|k, v| attributes_for_inspect << "#{k}: #{attribute_for_inspect(v)}"}
+      "#<#{self.class} #{attributes_for_inspect.join(', ')}>"
+    end
+    
+    def attribute_for_inspect(value)
+      if value.is_a?(String) && value.length > 50
+        "#{value[0..50]}...".inspect
+      elsif value.is_a?(Date) || value.is_a?(Time)
+        %("#{value.iso8601}")
+      else
+        value.inspect
+      end
+    end
+    
+    # Returns the class name without modules
+    def class_name
+      self.class.to_s.split('::').last
+    end
+    
+    # Returns the URL to which a post request must be sent to create a new resource
+    def create_url
+      raise CreateImpossible unless can_be?(:created)
+      
+      # convention over configuration, can also be overwritten in subclasses
+      has_many_association_name = class_name.tableize 
+      
+      if Tagcrumbs.current_user.respond_to?(has_many_association_name) && Tagcrumbs.current_user.send(has_many_association_name) 
+        Tagcrumbs.current_user.send("#{has_many_association_name}_url")
+      else
+        raise CreateURLMissing
+      end
+    end
+    
+    # Can this object be :created, :updated or :destroyed?
+    def can_be?(method)
+      self.class.can_be_options.include?(method.to_sym)
+    end    
+
+    
+    module ClassMethods 
+      # Configure if objects of this class can be :created, :updated or :destroyed
+      def can_be(*args)
+        self.can_be_options = args
+      end
+           
+      # Returns an array of all the attributes of a class, pass :modifiable_only => true to only get modifiable attributes
+      def attributes(args = {})
+        if args[:modifiable_only]
+          writeable_attributes_options.keys + modifiable_has_one_associations_options.keys
+        else
+          writeable_attributes_options.keys + readable_attributes_options.keys + modifiable_has_one_associations_options.keys
+        end        
+      end
+
+      # Configure the writeable attributes of the class that will be sent to the server on a post or put
+      def writeable_attributes(*attributes)
+        attributes.each do |attribute|
+          define_method attribute do
+            if nodes_updates[attribute]
+              nodes_updates[attribute].value
+            elsif nodes[attribute]
+              nodes[attribute].value
+            else
+              nil
+            end
+          end
+          
+          define_method "#{attribute}=" do |value|
+            self.nodes_updates[attribute] = Node.new(attribute, value)
+          end
+
+          self.writeable_attributes_options[attribute] = nil
+        end
+      end
+      
+      # Configure attributes that are only readable and that cannot be changed by the client
+      def readable_attributes(*attributes)
+        attributes.each do |attribute|     
+          define_method attribute do
+            if nodes[attribute]
+              nodes[attribute].value
+            else
+              nil
+            end
+          end
+          
+          self.readable_attributes_options[attribute] = nil
+        end
+      end
+
+      # Configure a has_one relationship
+      # Pass :modifiable => true if this relationship can be modified.
+      # When the resource is sent to the webservice the resource_url of the object will be sent to identify it
+      def has_one(name, options={})      
+        options[:node_name] ||= name.to_s.underscore
+
+        self.has_one_associations_options[name] = options
+
+        define_method name do # define a reader that loads the association if not done already
+          if has_one_associations_updates[name]
+            has_one_associations_updates[name]
+          elsif !has_one_associations.has_key?(name)
+            nil
+          else
+            Proxy.new(has_one_associations[name]) # use a proxy to load objects as late as possible
+          end
+        end
+        
+        define_method "#{name}=" do |value|
+          self.has_one_associations_updates[name] = value
+        end
+        
+        # define a convenience url accessor method
+        define_method "#{name}_url" do
+          if has_one_associations_updates[name]
+            has_one_associations_updates[name].resource_url
+          elsif has_one_associations[name]
+            has_one_associations[name].resource_url
+          end
+        end
+        
+        # define aliases for tagcrumb
+        if name == :tagcrumb
+          define_method :placemark do
+            self.tagcrumb
+          end
+          
+          define_method :placemark= do |value|
+            self.tagcrumb = value
+          end
+        end
+      end
+      
+      # Configure a has_many association
+      def has_many(name, options={})      
+        options[:node_name] ||= name.to_s.underscore
+
+        self.has_many_associations_options[name] = options
+
+        define_method name do # define a reader that loads the association if not done already
+          if !has_many_associations.has_key?(name)
+            nil
+          else
+            Proxy.new(has_many_associations[name]) # use a proxy to load objects as late as possible
+          end
+        end
+        
+        # define a convenience url accessor method
+        define_method "#{name}_url" do
+          has_many_associations[name].resource_url if has_many_associations[name]
+        end
+      end
+      
+      # Return the names of all modifiable has one associations of the class
+      def modifiable_has_one_associations_options
+        hash = {}
+        
+        self.has_one_associations_options.each do |k, v|
+          hash[k] = v if v[:modifiable]
+        end
+        
+        hash
+      end
+      
+      # Return has_one and has_many options      
+      def association_options
+        has_one_associations_options.merge(has_many_associations_options)
+      end
+
+    end
+    
+  end
+end

data/lib/tagcrumbs/resources/models/activity.rb

@@ -0,0 +1,19 @@
+module Tagcrumbs
+  # Activites are automatically created when other actions are performed on the website or with the webservice.
+  # They cannot be created or modified manually. However, it is possible to destroy an activity if you don't
+  # want it to be in your activity stream.
+  # The user of the activity is the actor who performed the activity, the subject is the social thing the action was performed upon.
+  # Sometimes there also is a secondary subject. The creation of a comment sets the subject to the comment and the secondary subject
+  # will be the placemark on which the comment was created.
+  # The event_type attribute shows what action happened and if a resource was modified or created.
+  class Activity < Model
+    can_be :destroyed
+    
+    readable_attributes :event_type, :created_at, :updated_at
+    
+    has_one :user
+    has_one :subject
+    has_one :secondary_subject
+    
+  end
+end

data/lib/tagcrumbs/resources/models/address.rb

@@ -0,0 +1,16 @@
+module Tagcrumbs
+  # Addresses are associated to Placemarks. They cannot be created or destroyed manually.
+  # They can only be updated. An address will be destroyed if the associated Placemark is
+  # destroyed.
+  #
+  # The city field contains a string that describes the city as it would stand in an address.
+  # It must not - but can - be the same as the associated city of the Placemark.
+  class Address < Model
+    can_be :updated
+    
+    writeable_attributes :street_address, :postal_code, :city, :state, :country
+    
+    has_one :tagcrumb
+    
+  end
+end

data/lib/tagcrumbs/resources/models/city.rb

@@ -0,0 +1,13 @@
+module Tagcrumbs
+  # A City somewhere on this planet. It has a name and a geoname and you can get more information about it with the geonames web service.
+  # It belongs to a state and a state belongs to a country, so that you can find out the associated admin areas.
+  class City < Place    
+    has_one :state
+    
+    # Search for a city by handing a string.
+    def self.search(q, args={})
+      super(q, args.merge(:for => :city))
+    end
+    
+  end
+end

data/lib/tagcrumbs/resources/models/comment.rb

@@ -0,0 +1,12 @@
+module Tagcrumbs
+  # Comments can be created on Placemarks. They can be destroyed for a certain timespan, afterwards it is no longer
+  # possible to destroy them.
+  class Comment < Model
+    can_be :created, :destroyed
+    
+    readable_attributes :created_at, :updated_at
+    writeable_attributes :text
+    
+    has_one :tagcrumb, :modifiable => true
+  end
+end

data/lib/tagcrumbs/resources/models/country.rb

@@ -0,0 +1,15 @@
+module Tagcrumbs
+  # A Country is a Place and has a name. It contains many states and the states contain many cities.
+  # You can filter Tagcrumbs by country. You can find out more information about the country by querying the geonames webservice.
+  
+  class Country < Place
+  
+    has_many :states
+    
+    # Search a country by a string
+    def self.search(q, args={})
+      super(q, args.merge(:for => :country))
+    end
+    
+  end
+end

data/lib/tagcrumbs/resources/models/fanship.rb

@@ -0,0 +1,12 @@
+module Tagcrumbs
+  # A Fanship is the association between a User and a Fan.
+  # It cannot be created or destroyed, it only shows who is "following" you.
+  class Fanship < Model
+    
+    readable_attributes :created_at, :updated_at
+    
+    has_one :user
+    has_one :fan
+    
+  end
+end

data/lib/tagcrumbs/resources/models/favorite.rb

@@ -0,0 +1,22 @@
+module Tagcrumbs
+  # Instead of creating a brand new Placemark you can create a Favorite instead of a Placemark that is somewhere nearby
+  # and describes the place already that you wanted to describe.
+  
+  # If you set subscribe to true you will automatically subscribe to updates of this Placemark.
+  class Favorite < Tagcrumb
+    can_be :created, :updated, :destroyed
+        
+    writeable_attributes  :tag_list, :private, :subscribe
+    readable_attributes   :created_at, :updated_at
+    
+    has_one :user
+     
+    has_one :tagcrumb, :modifiable => true
+    
+    # Find favorites and pass in additional filter options. The options are documented in Tagcrumb.
+    def self.find(args={})
+      super(args.merge(:tagcrumb_type => :favorite))
+    end
+    
+  end
+end

data/lib/tagcrumbs/resources/models/filter.rb

@@ -0,0 +1,32 @@
+module Tagcrumbs
+  # A Filter is a saved set of "find" criterias that can be easily accessed by a user multiple times later on.
+  # == Filter criteria:
+  # private: 
+  #   - true: only show private Placemarks
+  #   - false: only show public Placemarks
+  #   - nil: show private and public Placemarks
+  # tagcrumb_type:
+  #   - Placemark: only show Placemarks
+  #   - Favorite: only show Favorites
+  #   - nil: show Placemarks and Favorites
+  # tag_list: only show Tagcrumbs that are tagged with all of the tags in the comma-separated list 
+  # since: all Tagcrumbs since this point of time
+  # until: all Tagcrumbs until this point of time (can be combined with since)
+  # from: you, everybody, fans, friends, recommendations
+  
+  class Filter < Model
+    can_be :created, :updated, :destroyed
+    
+    readable_attributes  :created_at, :updated_at, :permalink
+    writeable_attributes :name, :private, :tagcrumb_type, :tag_list, :middle_of_nowhere, :from, :within, :since, :until
+    
+    has_one :user
+    
+    has_one :monitored_user, :modifiable => true
+    has_one :city, :modifiable => true
+    has_one :state, :modifiable => true
+    has_one :country, :modifiable => true
+    
+    has_many :tagcrumbs
+  end
+end

data/lib/tagcrumbs/resources/models/flag.rb

@@ -0,0 +1,10 @@
+module Tagcrumbs
+  # A Flag is used to mark a Placemark to be against the Terms of Service. It can only be created and not read, destroyed or
+  # updated afterwards. 
+  class Flag < Model
+    can_be :created
+    
+    writeable_attributes :reason
+    
+  end
+end

data/lib/tagcrumbs/resources/models/friendship.rb

@@ -0,0 +1,12 @@
+module Tagcrumbs
+  # A Friendship can be created or destroyed and lets you "follow" other Users
+  class Friendship < Model
+    can_be :created, :destroyed
+    
+    readable_attributes :created_at, :updated_at
+    
+    has_one :user
+    has_one :friend, :modifiable => true
+
+  end
+end

data/lib/tagcrumbs/resources/models/geoname.rb

@@ -0,0 +1,8 @@
+module Tagcrumbs
+  # Cities, States and Countries are connected to a Geoname. You can get more information about a place by querying the 
+  # geonames webservice with the geonameid of the place.
+  class Geoname < Model
+    readable_attributes :geonameid, :latitude, :longitude
+    
+  end
+end