wadl 0.1.2 → 0.1.3.1

data/lib/wadl/address.rb

@@ -0,0 +1,193 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  # The Address class keeps track of the user's path through a resource
+  # graph. Values for WADL parameters may be specified at any time using
+  # the bind method. An Address cannot be turned into a URI and header
+  # set until all required parameters have been bound to values.
+  #
+  # An Address object is built up through calls to Resource#address
+
+  class Address
+
+    attr_reader :path_fragments, :query_vars, :headers,
+                :path_params, :query_params, :header_params
+
+    def self.embedded_param_names(fragment)
+      fragment.scan(/\{(.+?)\}/).flatten
+    end
+
+    def initialize(path_fragments = [], query_vars = [], headers = {},
+                   path_params = {}, query_params = {}, header_params = {})
+      @path_fragments, @query_vars, @headers = path_fragments, query_vars, headers
+      @path_params, @query_params, @header_params = path_params, query_params, header_params
+    end
+
+    # Perform a deep copy.
+    def deep_copy
+      Address.new(
+        _deep_copy_array(@path_fragments),
+        _deep_copy_array(@query_vars),
+        _deep_copy_hash(@headers),
+        @path_params.dup,
+        @query_params.dup,
+        @header_params.dup
+      )
+    end
+
+    def to_s
+      "Address:\n"                                            <<
+      " Path fragments: #{@path_fragments.inspect}\n"         <<
+      " Query variables: #{@query_vars.inspect}\n"            <<
+      " Header variables: #{@headers.inspect}\n"              <<
+      " Unbound path parameters: #{@path_params.inspect}\n"   <<
+      " Unbound query parameters: #{@query_params.inspect}\n" <<
+      " Unbound header parameters: #{@header_params.inspect}\n"
+    end
+
+    alias_method :inspect, :to_s
+
+    # Binds some or all of the unbound variables in this address to values.
+    def bind!(args = {})
+      path_var_values   = args[:path]    || {}
+      query_var_values  = args[:query]   || {}
+      header_var_values = args[:headers] || {}
+
+      # Bind variables found in the path fragments.
+      path_params_to_delete = []
+
+      path_fragments.each { |fragment|
+        if fragment.respond_to?(:to_str)
+          # This fragment is a string which might contain {} substitutions.
+          # Make any substitutions available to the provided path variables.
+          self.class.embedded_param_names(fragment).each { |param_name|
+            value = path_var_values[param_name] || path_var_values[param_name.to_sym]
+
+            value = if param = path_params[param_name]
+              path_params_to_delete << param
+              param % value
+            else
+              Param.default.format(value, param_name)
+            end
+
+            fragment.gsub!("{#{param_name}}", value)
+          }
+        else
+          # This fragment is an array of Param objects (style 'matrix'
+          # or 'plain') which may be bound to strings. As substitutions
+          # happen, the array will become a mixed array of Param objects
+          # and strings.
+          fragment.each_with_index { |param, i|
+            if param.respond_to?(:name)
+              name = param.name
+
+              value = path_var_values[name] || path_var_values[name.to_sym]
+              value = param % value
+              fragment[i] = value if value
+
+              path_params_to_delete << param
+            end
+          }
+        end
+      }
+
+      # Delete any embedded path parameters that are now bound from
+      # our list of unbound parameters.
+      path_params_to_delete.each { |p| path_params.delete(p.name) }
+
+      # Bind query variable values to query parameters
+      query_var_values.each { |name, value|
+        param = query_params.delete(name.to_s)
+        query_vars << param % value if param
+      }
+
+      # Bind header variables to header parameters
+      header_var_values.each { |name, value|
+        param = header_params.delete(name.to_s)
+        headers[name] = param % value if param
+      }
+
+      self
+    end
+
+    def uri(args = {})
+      obj, uri = deep_copy.bind!(args), ''
+
+      # Build the path
+      obj.path_fragments.flatten.each { |fragment|
+        if fragment.respond_to?(:to_str)
+          embedded_param_names = self.class.embedded_param_names(fragment)
+
+          unless embedded_param_names.empty?
+            raise ArgumentError, %Q{Missing a value for required path parameter "#{embedded_param_names[0]}"!}
+          end
+
+          unless fragment.empty?
+            uri << '/' unless uri.empty? || uri =~ /\/\z/
+            uri << fragment
+          end
+        elsif fragment.required?
+          # This is a required Param that was never bound to a value.
+          raise ArgumentError, %Q{Missing a value for required path parameter "#{fragment.name}"!}
+        end
+      }
+
+      # Hunt for required unbound query parameters.
+      obj.query_params.each { |name, value|
+        if value.required?
+          raise ArgumentError, %Q{Missing a value for required query parameter "#{value.name}"!}
+        end
+      }
+
+      # Hunt for required unbound header parameters.
+      obj.header_params.each { |name, value|
+        if value.required?
+          raise ArgumentError, %Q{Missing a value for required header parameter "#{value.name}"!}
+        end
+      }
+
+      URIParts.new(uri, obj.query_vars, obj.headers)
+    end
+
+    private
+
+    def _deep_copy_hash(h)
+      h.inject({}) { |h, (k, v)| h[k] = v && v.dup; h }
+    end
+
+    def _deep_copy_array(a)
+      a.inject([]) { |a, e| a << (e && e.dup) }
+    end
+
+  end
+
+end

data/lib/wadl/application.rb

@@ -0,0 +1,71 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'rexml/document'
+require 'wadl'
+
+module WADL
+
+  class Application < HasDocs
+
+    in_document 'application'
+    has_one Resources
+    has_many HTTPMethod, RepresentationFormat, FaultFormat
+
+    def self.from_wadl(wadl)
+      wadl = wadl.read if wadl.respond_to?(:read)
+      doc = REXML::Document.new(wadl)
+
+      application = from_element(nil, doc.root, need_finalization = [])
+      need_finalization.each { |x| x.finalize_creation }
+
+      application
+    end
+
+    def find_resource(symbol, *args, &block)
+      resource_list.find_resource(symbol, *args, &block)
+    end
+
+    def resource(symbol)
+      resource_list.resource(symbol)
+    end
+
+    def find_resource_by_path(symbol, *args, &block)
+      resource_list.find_resource_by_path(symbol, *args, &block)
+    end
+
+    def finalize_creation
+      resource_list.resources.each { |r|
+        define_singleton(r, :id,   'resource_list.find_resource')
+        define_singleton(r, :path, 'resource_list.find_resource_by_path')
+      } if resource_list
+    end
+
+  end
+
+end

data/lib/wadl/cheap_schema.rb

@@ -0,0 +1,343 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  # A cheap way of defining an XML schema as Ruby classes and then parsing
+  # documents into instances of those classes.
+
+  class CheapSchema
+
+    @may_be_reference        = false
+    @contents_are_mixed_data = false
+
+    ATTRIBUTES = %w[names members collections required_attributes attributes]
+
+    class << self
+
+      attr_reader(*ATTRIBUTES)
+
+      def init
+        @names, @members, @collections = {}, {}, {}
+        @required_attributes, @attributes = [], []
+      end
+
+      def inherit(from)
+        init
+
+        ATTRIBUTES.each { |attr|
+          value = from.send(attr)
+          instance_variable_set("@#{attr}", value.dup) if value
+        }
+
+        %w[may_be_reference contents_are_mixed_data].each { |attr|
+          instance_variable_set("@#{attr}", from.instance_variable_get("@#{attr}"))
+        }
+      end
+
+      def inherited(klass)
+        klass.inherit(self)
+      end
+
+      def may_be_reference?
+        @may_be_reference
+      end
+
+      def in_document(element_name)
+        @names[:element]    = element_name
+        @names[:member]     = element_name
+        @names[:collection] = element_name + 's'
+      end
+
+      def as_collection(collection_name)
+        @names[:collection] = collection_name
+      end
+
+      def as_member(member_name)
+        @names[:member] = member_name
+      end
+
+      def contents_are_mixed_data
+        @contents_are_mixed_data = true
+      end
+
+      def has_one(*classes)
+        classes.each { |klass|
+          @members[klass.names[:element]] = klass
+          dereferencing_instance_accessor(klass.names[:member])
+        }
+      end
+
+      def has_many(*classes)
+        classes.each { |klass|
+          @collections[klass.names[:element]] = klass
+
+          collection_name = klass.names[:collection]
+          dereferencing_instance_accessor(collection_name)
+
+          # Define a method for finding a specific element of this
+          # collection.
+          class_eval <<-EOT, __FILE__, __LINE__ + 1
+            def find_#{klass.names[:element]}(*args, &block)
+              block ||= begin
+                name = args.shift.to_s
+                lambda { |match| match.matches?(name) }
+              end
+
+              auto_dereference = args.shift
+              auto_dereference = true if auto_dereference.nil?
+
+              match = #{collection_name}.find { |match|
+                block[match] || (
+                  #{klass}.may_be_reference? &&
+                  auto_dereference &&
+                  block[match.dereference]
+                )
+              }
+
+              match && auto_dereference ? match.dereference : match
+            end
+          EOT
+        }
+      end
+
+      def dereferencing_instance_accessor(*symbols)
+        define_dereferencing_accessors(symbols,
+          'd, v = dereference, :@%s; ' <<
+          'd.instance_variable_get(v) if d.instance_variable_defined?(v)',
+          'dereference.instance_variable_set(:@%s, value)'
+        )
+      end
+
+      def dereferencing_attr_accessor(*symbols)
+        define_dereferencing_accessors(symbols,
+          'dereference.attributes["%s"]',
+          'dereference.attributes["%s"] = value'
+        )
+      end
+
+      def has_attributes(*names)
+        has_required_or_attributes(names, @attributes)
+      end
+
+      def has_required(*names)
+        has_required_or_attributes(names, @required_attributes)
+      end
+
+      def may_be_reference
+        @may_be_reference = true
+
+        find_method_name = "find_#{names[:element]}"
+
+        class_eval <<-EOT, __FILE__, __LINE__ + 1
+          def dereference
+            return self unless href = attributes['href']
+
+            unless @referenced
+              p = self
+
+              until @referenced || !p
+                begin
+                  p = p.parent
+                end until !p || p.respond_to?(:#{find_method_name})
+
+                @referenced = p.#{find_method_name}(href, false) if p
+              end
+            end
+
+            dereference_with_context(@referenced) if @referenced
+          end
+        EOT
+      end
+
+      # Turn an XML element into an instance of this class.
+      def from_element(parent, element, need_finalization)
+        attributes = element.attributes
+
+        me = new
+        me.parent = parent
+
+        @collections.each { |name, klass|
+          me.instance_variable_set("@#{klass.names[:collection]}", [])
+        }
+
+        if may_be_reference? and href = attributes['href']
+          # Handle objects that are just references to other objects
+          # somewhere above this one in the hierarchy
+          href = href.dup
+          href.sub!(/\A#/, '') or warn "Warning: HREF #{href} should be ##{href}"
+
+          me.attributes['href'] = href
+        else
+          # Handle this element's attributes
+          @required_attributes.each { |name|
+            name = name.to_s
+
+            raise ArgumentError, %Q{Missing required attribute "#{name}" in element: #{element}} unless attributes[name]
+
+            me.attributes[name] = attributes[name]
+            me.index_key = attributes[name] if name == @index_attribute
+          }
+
+          @attributes.each { |name|
+            name = name.to_s
+
+            me.attributes[name] = attributes[name]
+            me.index_key = attributes[name] if name == @index_attribute
+          }
+        end
+
+        # Handle this element's children.
+        if @contents_are_mixed_data
+          me.instance_variable_set(:@contents, element.children)
+        else
+          element.each_element { |child|
+            if klass = @members[child.name] || @collections[child.name]
+              object = klass.from_element(me, child, need_finalization)
+
+              if klass == @members[child.name]
+                instance_variable_name = "@#{klass.names[:member]}"
+
+                if me.instance_variable_defined?(instance_variable_name)
+                  raise "#{name} can only have one #{klass.name}, but several were specified in element: #{element}"
+                end
+
+                me.instance_variable_set(instance_variable_name, object)
+              else
+                me.instance_variable_get("@#{klass.names[:collection]}") << object
+              end
+            end
+          }
+        end
+
+        need_finalization << me if me.respond_to?(:finalize_creation)
+
+        me
+      end
+
+      private
+
+      def define_dereferencing_accessors(symbols, getter, setter)
+        symbols.each { |name|
+          name = name.to_s
+
+          class_eval <<-EOT, __FILE__, __LINE__ + 1 unless name =~ /\W/
+            def #{name}; #{getter % name}; end
+            def #{name}=(value); #{setter % name}; end
+          EOT
+        }
+      end
+
+      def has_required_or_attributes(names, var)
+        names.each { |name|
+          var << name
+          @index_attribute ||= name.to_s
+          name == :href ? attr_accessor(name) : dereferencing_attr_accessor(name)
+        }
+      end
+
+    end
+
+    attr_accessor :index_key, :href, :parent
+    attr_reader :attributes
+
+    def initialize
+      @attributes, @contents, @referenced = {}, nil, nil
+    end
+
+    # This object is a reference to another object. This method returns
+    # an object that acts like the other object, but also contains any
+    # neccessary context about this object. See the ResourceAndAddress
+    # implementation, in which a dereferenced resource contains
+    # information about the parent of the resource that referenced it
+    # (otherwise, there's no way to build the URI).
+    def dereference_with_context(referent)
+      referent
+    end
+
+    # A null implementation so that foo.dereference will always return the
+    # "real" object.
+    def dereference
+      self
+    end
+
+    # Returns whether or not the given name matches this object.
+    # By default, checks the index key for this class.
+    def matches?(name)
+      index_key == name
+    end
+
+    def to_s(indent = 0)
+      klass = self.class
+
+      i = ' ' * indent
+      s = "#{i}#{klass.name}\n"
+
+      if klass.may_be_reference? and href = attributes['href']
+        s << "#{i} href=#{href}\n"
+      else
+        [klass.required_attributes, klass.attributes].each { |list|
+          list.each { |attr|
+            val = attributes[attr.to_s]
+            s << "#{i} #{attr}=#{val}\n" if val
+          }
+        }
+
+        klass.members.each_value { |member_class|
+          o = send(member_class.names[:member])
+          s << o.to_s(indent + 1) if o
+        }
+
+        klass.collections.each_value { |collection_class|
+          c = send(collection_class.names[:collection])
+
+          if c && !c.empty?
+            s << "#{i} Collection of #{c.size} #{collection_class.name}(s)\n"
+            c.each { |o| s << o.to_s(indent + 2) }
+          end
+        }
+
+        if @contents && !@contents.empty?
+          sep = '-' * 80
+          s << "#{sep}\n#{@contents.join(' ')}\n#{sep}\n"
+        end
+      end
+
+      s
+    end
+
+  end
+
+end
+
+# Simple backport for Ruby <= 1.8.5
+class Object  # :nodoc:
+  def instance_variable_defined?(sym); instance_eval("defined?(#{sym})"); end
+end unless Object.method_defined?(:instance_variable_defined?)