tagcrumbs-tagcrumbs 0.3.1

data/lib/tagcrumbs/parsers/json_parser.rb

@@ -0,0 +1,79 @@
+module Tagcrumbs
+  # A parser for JSON
+  class JsonParser < Parser
+    attr_accessor :_name # save the name of the json hash
+    
+    def initialize(parser_or_document)
+      if parser_or_document.is_a?(String)
+        tmp = JSON.parse(parser_or_document)
+        self._name = tmp.keys.first
+        self.document = tmp[self._name]
+      elsif(parser_or_document.is_a?(Tagcrumbs::JsonParser))
+        self.document = parser_or_document.document
+      else
+        self.document = parser_or_document
+      end
+
+      self.format = :json
+    end
+    
+    # Get a node with a specific name from the document
+    def get_node(name)
+      self.document[name.to_s]
+    end
+    
+    # Is this a stub and therefore only a "link" in the webservice or is a resource loaded?
+    def node_loaded?
+      badgerfish_json_loaded?
+    end
+    
+    # Get all child nodes with a specific name
+    def nodes_with_name(name)      
+      self.document[name] || []
+    end
+    
+    # Get all attributes from the badgerfish JSON that (all keys starting with '@')
+    def get_attributes
+      attributes_from_badgerfish_json
+    end
+    
+    # Get one attribute from the JSON
+    def get_attribute(attribute)
+      self.document["@#{attribute}"]
+    end
+    
+    # Get the value of an element ('$' key in badgerfish JSON)
+    def get_value
+      self.document['$']
+    end
+    
+    # Get the name of the current element
+    def name
+      _name || self.document.keys.select{|k| k.first != '@'}.first
+    end
+    
+    private
+    
+      def attributes_from_badgerfish_json
+        hash = {}
+
+        self.document.each do |k, v|
+          if k.first == '@'
+            hash[k[1..-1]] = v
+          end
+        end
+
+        hash
+      end
+
+      # is there anything else besides badgerfish style attributes?
+      def badgerfish_json_loaded?         
+        self.document.each do |k, v|
+          return true if k.first != '@'
+        end
+
+        false
+      end    
+  
+  end
+end

data/lib/tagcrumbs/parsers/parser.rb

@@ -0,0 +1,24 @@
+module Tagcrumbs
+  # Parser is an abstract class that provides common functions for all parsers and that helps to get a correct parser for 
+  # a specific format
+  class Parser
+    attr_accessor :document, :format
+    
+    # Create a parser for a specific format (xml or json)
+    # +document_or_parser+ can either be a Parser or a document, if it is a Parser it will be returned as it is,
+    # otherwise a parser will be created out of the document
+    def self.new_for_format(document_or_parser, format)
+      if document_or_parser.is_a?(Tagcrumbs::Parser) # allow to also pass a document right into the method
+        document_or_parser
+      else
+        case format
+          when :xml:  XmlParser.new(document_or_parser)
+          when :json: JsonParser.new(document_or_parser)
+          else
+            raise UnsupportedFormat
+        end
+      end
+    end
+    
+  end
+end

data/lib/tagcrumbs/parsers/xml_parser.rb

@@ -0,0 +1,54 @@
+module Tagcrumbs
+  class XmlParser < Parser
+    
+    def initialize(parser_or_document)
+      if parser_or_document.is_a?(String)
+        xml = Hpricot.XML(parser_or_document)
+        self.document = xml.root ? xml.root : xml
+      elsif(parser_or_document.is_a?(Tagcrumbs::XmlParser))
+        self.document = parser_or_document.document
+      else
+        self.document = parser_or_document
+      end
+      
+      self.format = :xml
+    end
+    
+    # Get a node with a specific name from the document
+    def get_node(name)
+      self.document.children_of_type(name.to_s).first
+    end
+    
+    # Does the document contain a resource or is it just a "link" in the webservice?
+    def node_loaded?
+      #self.document.innerText.present? 
+      !self.document.empty?
+    end
+    
+    # Get all children with name
+    def nodes_with_name(name)      
+      self.document.children_of_type(name)
+    end
+    
+    # Get all attributes
+    def get_attributes
+      self.document.attributes
+    end
+    
+    # Get one specific attribute
+    def get_attribute(attribute)
+      self.document.get_attribute(attribute)
+    end
+    
+    # Get the value of the tag
+    def get_value
+      self.document.innerHTML
+    end
+     
+    # Get the name of the document   
+    def name
+      self.document.name
+    end
+    
+  end
+end

data/lib/tagcrumbs/proxy.rb

@@ -0,0 +1,32 @@
+module Tagcrumbs
+  # The Proxy class is used in resource associations to delay loading of a resource for as long as possible.
+  # Some method calls are directly forwarded to the resource, for others the resource is loaded first from the webservice
+  # and afterwards the call is made.
+  # The Proxy tries to be as transparent as possible so that you basically never know that you have a proxy object instead of a real resource.
+  class Proxy
+    UNPROXIED_METHODS = [:reload, :resource_url, :properties, :loaded?, :class] # TODO: figure out what other methods might be needed?
+
+    instance_methods.each { |m| undef_method m unless m =~ /^__/ } # http://onestepback.org/index.cgi/Tech/Ruby/BlankSlate.rdoc
+
+    def initialize(object)
+      @object = object
+    end
+    
+    
+    # Forward all method calls to the proxied object, reload if necessary
+    def method_missing(method_name, *args, &block)
+      #puts "** Proxying #{method_name}. Loaded: #{@object.loaded?}"
+      
+      if @object.loaded? || UNPROXIED_METHODS.include?(method_name) #|| !@object.respond_to?(method_name) # having this doesn't allow first etc on arrays
+        @object.send(method_name, *args, &block)
+      else 
+        #puts "** Reloading"
+        @object.reload if @object.resource_url.present?
+        @object.send(method_name, *args, &block)
+      end
+      
+      
+    end
+  end
+  
+end

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