aws-sdk 1.0.0

data/lib/aws/sqs/queue_collection.rb

@@ -0,0 +1,105 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/model'
+require 'aws/sqs/queue'
+
+module AWS
+  class SQS
+
+    # Represents all the {Queue} objects in your account.
+    #
+    # If you have permission to access a queue created by another
+    # account, you can also use this collection to access that queue
+    # by URL.
+    #
+    # @example Printing the URLs of all queues
+    #   pp sqs.queues.map(&:url)
+    #
+    # @example Filtering queues by queue name prefix
+    #   pp sqs.queues.with_prefix("production_").map(&:url)
+    #
+    # @example Accessing a queue by URL
+    #   url = "http://sqs.us-east-1.amazonaws.com/123456789012/myqueue"
+    #   sqs.queues[url].send_message("HELLO")
+    class QueueCollection
+
+      include Model
+      include Enumerable
+
+      # @private
+      def initialize(opts = {})
+        @prefix = opts[:prefix]
+        super
+      end
+
+      # @return [String] The queue name prefix by which this
+      #   collection is filtered.
+      attr_reader :prefix
+
+      # Creates a new queue.
+      #
+      # @note If you delete a queue, you must wait at least 60
+      #   seconds before creating a queue with the same name.
+      #
+      # @param [String] name The name to use for the queue created.
+      #   Constraints: Maximum 80 characters; alphanumeric
+      #   characters, hyphens (-), and underscores (_) are allowed.
+      #
+      #   To successfully create a new queue, you must provide a
+      #   name that is unique within the scope of your own
+      #   queues. If you provide the name of an existing queue, a
+      #   new queue isn't created and an error isn't
+      #   returned. Instead, the request succeeds and the queue URL
+      #   for the existing queue is returned. Exception: if you
+      #   provide a value for +:default_visibility_timeout+ that is
+      #   different from the value for the existing queue, you
+      #   receive an error.
+      #
+      # @param [Hash] opts Additional options for creating the
+      #   queue.
+      #
+      # @option opts [Integer] :default_visibility_timeout The
+      #   visibility timeout (in seconds) to use for this queue.
+      #
+      # @return [Queue] The newly created queue.
+      #
+      def create(name, opts = {})
+        resp = client.create_queue(opts.merge(:queue_name => name))
+        Queue.new(resp.queue_url, :config => config)
+      end
+
+      # @yieldparam [Queue] queue Each {Queue} object in the collection.
+      def each(&block)
+        client.list_queues.queue_urls.each do |url|
+          queue = self[url]
+          yield(queue)
+        end
+      end
+
+      # @param [String] prefix The queue name prefix.
+      # @return [QueueCollection] A new collection representing only
+      #   the queues whose names start with the given prefix.
+      def with_prefix(prefix)
+        self.class.new(:prefix => prefix, :config => config)
+      end
+
+      # @return [Queue] The queue with the given URL.
+      def [](url)
+        Queue.new(url, :config => config)
+      end
+
+    end
+
+  end
+end

data/lib/aws/sqs/received_message.rb

@@ -0,0 +1,184 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/model'
+
+module AWS
+  class SQS
+
+    # Represents a message received from an Amazon SQS Queue.
+    class ReceivedMessage
+
+      include Model
+
+      # @return [Queue] The queue from which this message was
+      #   received.
+      attr_reader :queue
+
+      # @return [String] The ID of the message.
+      attr_reader :id
+
+      # @return [String] A string associated with this specific
+      #   instance of receiving the message.
+      attr_reader :handle
+
+      # @return [String] The message's contents.
+      attr_reader :body
+
+      # @return [String] An MD5 digest of the message body.
+      attr_reader :md5
+
+      # @private
+      attr_reader :attributes
+
+      # @private
+      ATTRIBUTE_ALIASES = {
+        :sent_at => :sent_timestamp,
+        :receive_count => :approximate_receive_count,
+        :first_received_at => :approximate_first_receive_timestamp
+      }
+
+      # @private
+      def initialize(queue, id, handle, opts = {})
+        @queue = queue
+        @id = id
+        @handle = handle
+        @body = opts[:body]
+        @md5 = opts[:md5]
+        @attributes = opts[:attributes] || {}
+        super
+      end
+
+      # When SNS publishes messages to SQS queues the message body is
+      # formatted as a json message and then base 64 encoded.
+      # An easy way to work with SNS messages is to call this method:
+      #
+      #   sns_msg = message.as_sns_message
+      # 
+      #   sns_msg.topic
+      #   #=> <AWS::SNS::Topic ...>
+      #
+      #   sns_msg.to_h.inspect
+      #   #=> { :body => '...', :topic_arn => ... }
+      #
+      # @return [ReceivedSNSMessage]
+      def as_sns_message
+        ReceivedSNSMessage.new(body, :config => config)
+      end
+
+      # Deletes the message from the queue.  Even if the message is
+      # locked by another reader due to the visibility timeout
+      # setting, it is still deleted from the queue.  If you leave a
+      # message in the queue for more than 4 days, SQS automatically
+      # deletes it.
+      #
+      # If you use {Queue#poll} or {Queue#receive_message} in block
+      # form, the messages you receive will be deleted automatically
+      # unless an exception occurs while you are processing them.
+      # You can still use this method if you want to delete a
+      # message early and then continue processing it.
+      #
+      # @note It is possible you will receive a message even after
+      #   you have deleted it. This might happen on rare occasions
+      #   if one of the servers storing a copy of the message is
+      #   unavailable when you request to delete the message. The
+      #   copy remains on the server and might be returned to you
+      #   again on a subsequent receive request. You should create
+      #   your system to be idempotent so that receiving a
+      #   particular message more than once is not a problem.
+      #
+      # @return [nil]
+      def delete
+        client.delete_message(
+          :queue_url => queue.url, 
+          :receipt_handle => handle
+        )
+        nil
+      end
+
+      # Changes the visibility timeout of a specified message in a
+      # queue to a new value. The maximum allowed timeout value you
+      # can set the value to is 12 hours. This means you can't
+      # extend the timeout of a message in an existing queue to more
+      # than a total visibility timeout of 12 hours. (For more
+      # information visibility timeout, see {Visibility
+      # Timeout}[http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/IntroductionArticle.html#AboutVT]
+      # in the Amazon SQS Developer Guide.)
+      #
+      # For example, let's say the timeout for the queue is 30
+      # seconds, and you receive a message. Once you're 20 seconds
+      # into the timeout for that message (i.e., you have 10 seconds
+      # left), you extend it by 60 seconds by calling this method
+      # with +timeout+ set to 60 seconds. You have then changed the
+      # remaining visibility timeout from 10 seconds to 60 seconds.
+      #
+      # @note If you attempt to set the timeout to an amount more
+      #   than the maximum time left, Amazon SQS returns an
+      #   error. It will not automatically recalculate and increase
+      #   the timeout to the maximum time remaining.
+      #
+      # @note Unlike with a queue, when you change the visibility
+      #   timeout for a specific message, that timeout value is
+      #   applied immediately but is not saved in memory for that
+      #   message. If you don't delete a message after it is
+      #   received, the visibility timeout for the message the next
+      #   time it is received reverts to the original timeout value,
+      #   not the value you set with this method.
+      #
+      # @return Returns the timeout argument as passed.
+      #
+      def visibility_timeout=(timeout)
+        client.change_message_visibility(
+          :queue_url => queue.url,
+          :receipt_handle => handle,
+          :visibility_timeout => timeout
+        )
+        timeout
+      end
+
+      # @return [String] The AWS account number (or the IP address,
+      #   if anonymous access is allowed) of the sender.
+      def sender_id
+        attributes["SenderId"]
+      end
+
+      # @return [Time] The time when the message was sent.
+      def sent_timestamp
+        @sent_at ||=
+          (timestamp = attributes["SentTimestamp"] and
+           Time.at(timestamp.to_i / 1000.0)) || nil
+      rescue RangeError => e
+        p [timestamp, timestamp.to_i]
+      end
+      alias_method :sent_at, :sent_timestamp
+
+      # @return [Integer] The number of times a message has been
+      #   received but not deleted.
+      def approximate_receive_count
+        (count = attributes["ApproximateReceiveCount"] and
+         count.to_i) or nil
+      end
+      alias_method :receive_count, :approximate_receive_count
+
+      # @return [Time] The time when the message was first received.
+      def approximate_first_receive_timestamp
+        @received_at ||=
+          (timestamp = attributes["ApproximateFirstReceiveTimestamp"] and
+           Time.at(timestamp.to_i / 1000.0)) || nil
+      end
+      alias_method :first_received_at, :approximate_first_receive_timestamp
+
+    end
+
+  end
+end

data/lib/aws/sqs/received_sns_message.rb

@@ -0,0 +1,112 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/model'
+require 'time'
+
+module AWS
+  class SQS
+
+    # Represents message published from an {SNS::Topic} to an {SQS::Queue}.
+    class ReceivedSNSMessage
+
+      include Model
+
+      # @param [String] encoded_body The base64 encoded json string
+      #   from a message published by SNS.
+      # @param [Hash] options
+      def initialize encoded_body, options = {}
+        @encoded_body = encoded_body
+        super
+      end
+
+      # @return [String] Returns the Base64 encoded JSON hash as was
+      #   published by SNS.  See {#body} to get the decoded message
+      #   or {#to_h} to get the decoded JSON hash as a ruby hash.
+      def encoded_body
+        @encoded_body
+      end
+
+      # @return[String] Returns the decoded message as was published.
+      def body
+        to_h[:body]
+      end
+
+      # @return [String] Returns the ARN for the topic that published this
+      #   message.
+      def topic_arn
+        to_h[:topic_arn]
+      end
+
+      # @return [SNS::Topic] Returns the topic that published this message.
+      def topic
+        SNS::Topic.new(topic_arn, :config => config)
+      end
+
+      # @return [String] Returns the message type.
+      def message_type
+        to_h[:message_type]
+      end
+
+      # @return [String] Returns the calculated signature for the message.
+      def signature
+        to_h[:signature]
+      end
+
+      # @return [String] Returns the signature version.
+      def signature_version
+        to_h[:signature_version]
+      end
+
+      # @return [Time] Returns the time the message was published at by SNS.
+      #   by SNS.
+      def published_at
+        to_h[:published_at]
+      end
+
+      # @return [String] Returns the unique id of the SNS message.
+      def message_id
+        to_h[:message_id]
+      end
+
+      # @return [String] Returns the url for the signing cert.
+      def signing_cert_url
+        to_h[:signing_cert_url]
+      end
+
+      # @return [String] Returns the url you can request to unsubscribe message
+      #   from this queue.
+      def unsubscribe_url
+        to_h[:unsubscribe_url]
+      end
+
+      # @return [Hash] Returns the decoded message as a hash.
+      def to_h
+        data = JSON.parse(Base64.decode64(@encoded_body))
+        {
+          :body => data['Message'],
+          :topic_arn => data['TopicArn'],
+          :message_type => data['Type'],
+          :signature => data['Signature'],
+          :signature_version => data['SignatureVersion'],
+          :published_at => Time.parse(data['Timestamp']),
+          :message_id => data['MessageId'],
+          :signing_cert_url => data['SigningCertURL'],
+          :unsubscribe_url => data['UnsubscribeURL'],
+        }
+      end
+
+    end
+
+  end
+end

data/lib/aws/sqs/request.rb

@@ -0,0 +1,44 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/http/request'
+require 'aws/authorize_v2'
+
+module AWS
+  class SQS
+
+    # @private
+    class Request < AWS::Http::Request
+
+      include AuthorizeV2
+      
+      def path
+        full_url.path
+      end
+
+      def host
+        full_url.host
+      end
+
+      private
+      def full_url
+        if url_param = params.find { |p| p.name == "QueueUrl" }
+          URI.parse(url_param.value)
+        else
+          URI::HTTP.build(:host => @host, :path => '/')
+        end
+      end
+
+    end
+  end
+end

data/lib/aws/xml_grammar.rb

@@ -0,0 +1,923 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/meta_utils'
+require 'aws/inflection'
+require 'rexml/document'
+
+begin
+  require 'nokogiri'
+rescue LoadError => e
+end
+
+module AWS
+
+  # @private
+  class XmlGrammar
+    
+    # @private
+    class Context
+
+      def initialize
+        @data = {}
+      end
+
+      def id
+        @data[:id]
+      end
+
+      def method_missing(m, *args)
+        key = m.to_sym
+
+        return super unless @data.key?(key)
+        @data[key]
+      end
+
+      def respond_to?(m)
+        @data.key?(m.to_sym) or super
+      end
+
+      def inspect
+        methods = @data.keys
+        "<Object #{methods.reject{|m| m =~ /=$/ }.join(', ')}>" 
+      end
+
+      # this gets called a LOT during response parsing, and having
+      # it be a public method is the fastest way to call it.
+      # Strictly speaking it should be private.
+      # @private
+      def __set_data__(getter, value)
+        @data[getter.to_sym] = value
+      end
+
+    end
+
+    # @private
+    class CustomizationContext < Hash
+
+      def initialize(element_name = nil)
+        self[:children] = {}
+
+        if element_name
+          self[:name] = element_name
+          recompute_accessors
+        end
+      end
+
+      def []=(name, value)
+        super
+        if respond_to?("changed_#{name}")
+          send("changed_#{name}", value)
+        end
+      end
+
+      def changed_boolean(value)
+        recompute_accessors
+      end
+
+      def changed_renamed(value)
+        recompute_accessors
+      end
+
+      def deep_copy(hash = self)
+        hash.inject(hash.class.new) do |copy,(key,value)|
+          if value.is_a?(CustomizationContext)
+            copy[key] = value.deep_copy
+          elsif value.is_a?(Hash)
+            copy[key] = deep_copy(value)
+          else
+            copy[key] = value
+          end
+          copy
+        end
+      end
+
+      private
+      def recompute_accessors
+        ruby_name = Inflection.ruby_name((self[:renamed] ||
+                                          self[:name]).to_s)
+        self[:getter] =
+          if self[:boolean] && ruby_name != "value"
+            "#{ruby_name}?"
+          else
+            ruby_name
+          end
+        self[:setter] = "#{ruby_name}="
+      end
+
+    end
+
+    # @private
+    class << self
+
+      def parse xml, options = {}
+
+        context = options[:context] || Context.new
+
+        if defined? Nokogiri
+          parser = Parser.new(context, customizations)
+          parser.extend(NokogiriAdapter)
+          xml = "<foo/>" if xml.empty?
+          Nokogiri::XML::SAX::Parser.new(parser).parse(xml.strip)
+        else
+          parser = Parser.new(context, customizations)
+          parser.extend(REXMLSaxParserAdapter)
+          REXML::Parsers::StreamParser.new(REXML::Source.new(xml), parser).parse
+        end
+
+        context
+
+      end
+
+      def simulate context = nil
+        StubResponse.new(customizations, context)
+      end
+
+      def customize config = nil, &block
+        grammar = Class.new(self)
+        grammar.customizations = customizations.deep_copy
+        grammar.config_eval(config) if config
+        grammar.module_eval(&block) if block_given?
+        grammar
+      end
+
+      def element element_name, &block
+        eval_customization_context(element_name, &block)
+      end
+
+      def add_method method_name, &block
+        format_value do |value|
+          MetaUtils.extend_method(value = super(value), method_name, &block)
+          value
+        end
+#           different strategey, slightly different behavior
+#           element(method_name.to_s) do
+#             format_value(&block)
+#             force
+#           end
+      end
+  
+      def ignore
+        @current[:ignored] = true
+      end
+
+      def rename new_name
+        @current[:renamed] = new_name.to_s
+      end
+
+      def force
+        @current[:forced] = true
+      end
+
+      def collect_values
+        @current[:collected] = true
+        @current[:initial_collection] = lambda { [] }
+        @current[:add_to_collection] =
+          lambda { |ary, val| ary << val }
+        force
+      end
+
+      def index(name, &block)
+        (@customizations[:index_names] ||= []) << name
+        @current[:indexed] = [name, block]
+      end
+
+      def boolean_value
+        @current[:boolean] = true
+        format_value {|value| super(value) == 'true' }
+      end
+      # required by the hash configuration method
+      alias_method :boolean, :boolean_value
+
+      TRANSLATE_DIGITS = ['0123456789'.freeze, ('X'*10).freeze]
+      EASY_FORMAT = "XXXX-XX-XXTXX:XX:XX.XXXZ".freeze
+      DATE_PUNCTUATION = ['-:.TZ'.freeze, (' '*5).freeze]
+
+      def datetime_value
+        datetime_like_value(DateTime, :civil)
+      end
+
+      def time_value
+        datetime_like_value(Time, :utc)
+      end
+      alias_method :timestamp, :time_value
+
+      def datetime_like_value(klass, parts_constructor)
+        format_value do |value|
+          value = super(value)
+          if value and value.tr(*TRANSLATE_DIGITS) == EASY_FORMAT
+
+            # it's way faster to parse this specific format manually
+            # vs. DateTime#parse, and this happens to be the format
+            # that AWS uses almost (??) everywhere.
+
+            parts = value.tr(*DATE_PUNCTUATION).
+              chop.split.map { |elem| elem.to_i }
+            klass.send(parts_constructor, *parts)
+          elsif value
+            # fallback in case we have to handle another date format
+            klass.parse(value)
+          else
+            nil
+          end
+        end
+      end
+
+      def integer_value
+        format_value do |value|
+          value = super(value)
+          value.nil? ? nil : value.to_i
+        end
+      end
+      # required by the hash configuration method
+      alias_method :integer, :integer_value
+      alias_method :long, :integer_value
+
+      def float_value
+        format_value do |value|
+          value = super(value)
+          value.nil? ? nil : value.to_f
+        end
+      end
+
+      alias_method :float, :float_value
+
+      def symbol_value
+        format_value do |value|
+          value = super(value)
+          ['', nil].include?(value) ? nil : Inflection.ruby_name(value).to_sym
+        end
+      end
+
+      def format_value &block
+        @current[:value_formatter] ||= ValueFormatter.new
+        @current[:value_formatter].extend_format_value(&block)
+      end
+
+      def list child_element_name = nil, &block
+        if child_element_name
+          ignore
+          parent_element_name = @current_name
+          element(child_element_name) do
+            rename(parent_element_name)
+            collect_values
+            yield if block_given?
+          end
+        else
+          collect_values
+        end
+      end
+
+      def map_entry(key, value)
+        collect_values
+        element(key) { rename :key }
+        element(value) { rename :value }
+        @current[:initial_collection] = lambda { {} }
+        @current[:add_to_collection] = lambda do |hash, entry|
+          hash[entry.key] = entry.value
+        end
+      end
+
+      def map entry_name, key, value
+        parent_element_name = @current_name
+        ignore
+        element(entry_name) do
+          rename(parent_element_name)
+          map_entry(key, value)
+        end
+      end
+
+      def wrapper method_name, options = {}, &blk
+        if block_given?
+          customizations =
+            eval_customization_context(method_name,
+                                       CustomizationContext.new(method_name),
+                                       &blk)
+          raise NotImplementedError.new("can't customize wrapped " +
+                                        "elements within the wrapper") unless
+            customizations[:children].empty?
+          @current[:wrapper_frames] ||= {}
+          @current[:wrapper_frames][method_name] = customizations
+        end
+
+        (options[:for] || []).each do |element_name|
+          element element_name do
+            @current[:wrapper] ||= []
+            @current[:wrapper] << method_name
+          end
+        end
+      end
+
+      def construct_value &block
+        @current[:construct_value] = block
+      end
+
+      def eql? other
+        self.customizations == other.customizations
+      end
+
+      protected
+      def initial_customizations(element_name = nil)
+        CustomizationContext.new(element_name)
+      end
+
+      protected
+      def eval_customization_context name, initial = nil, &block
+        current_name = @current_name
+        current = @current
+        parent = @parent
+        begin
+          @current_name = name
+          @parent = @current
+          initial ||= customizations_for(name)
+          @current = initial
+          yield if block_given?
+        ensure
+          @current_name = current_name
+          @current = current
+          @parent = parent
+        end
+
+        # will be modified to include the customizations defined in
+        # the block
+        initial
+      end
+
+      protected
+      def config_eval(config)
+        config.each do |item|
+          (type, identifier, args) = parse_config_item(item)
+          case type
+          when :method
+            validate_config_method(identifier)
+            validate_args(identifier, args)
+            send(identifier, *args)
+          when :element
+            element(identifier) do
+              config_eval(args)
+            end
+          end
+        end
+      end
+
+      protected
+      def validate_args(identifier, args)
+        arity = method(identifier).arity
+        if args.length > 0
+          raise "#{identifier} does not accept an argument" if
+            arity == 0
+        else
+          raise "#{identifier} requires an argument" unless
+            arity == 0 || arity == -1
+        end
+      end
+
+      protected
+      def parse_config_item(item)
+        case item
+        when Symbol
+          [:method, item, []]
+        when Hash
+          (method, arg) = item.to_a.first
+          if method.kind_of?(Symbol)
+            [:method, method, [arg].flatten]
+          else
+            [:element, method, arg]
+          end
+        end
+      end
+
+      protected
+      def validate_config_method(method)
+        allow_methods = %w(
+          rename attribute_name boolean integer long float list force
+          ignore collect_values symbol_value timestamp map_entry map
+        )
+        unless allow_methods.include?(method.to_s)
+          raise "#{method} cannot be used in configuration"
+        end
+      end
+
+      protected
+      def customizations
+        @customizations ||= CustomizationContext.new
+      end
+
+      protected
+      def customizations_for element_name
+        if @parent
+          @parent[:children][element_name] ||=
+            CustomizationContext.new(element_name)
+        else
+          customizations[:children][element_name] ||=
+            CustomizationContext.new(element_name)
+        end
+      end
+
+      protected
+      def customizations= customizations
+        @customizations = customizations
+        @current = customizations
+      end
+
+    end
+
+    # @private
+    class ValueFormatter
+
+      def extend_format_value &block
+        MetaUtils.extend_method(self, :format_value, &block)
+      end
+
+      def format_value value
+        value
+      end
+
+    end
+
+    # @private
+    class Parser
+
+      def initialize context, customizations
+        @context = context
+        @customizations = customizations
+      end
+
+      def start_element element_name, attrs
+
+        if @frame
+          @frame = @frame.build_child_frame(element_name)
+        else
+          @frame = RootFrame.new(@context, @customizations)
+        end
+
+        # consume attributes the same way we consume nested xml elements
+        attrs.each do |(attr_name, attr_value)|
+          attr_frame = @frame.build_child_frame(attr_name)
+          attr_frame.add_text(attr_value)
+          @frame.consume_child_frame(attr_frame)
+        end
+
+      end
+
+      def end_element name
+        @frame.close
+        if @frame.parent_frame
+          child_frame = @frame
+          parent_frame = @frame.parent_frame
+          parent_frame.consume_child_frame(child_frame)
+        end
+        @frame = @frame.parent_frame
+      end
+
+      def characters chars
+        @frame.add_text(chars) if @frame
+      end
+
+    end
+
+    module REXMLSaxParserAdapter
+
+        require 'rexml/streamlistener'
+      include REXML::StreamListener
+
+      def tag_start(name, attrs)
+        start_element(name, attrs)
+      end
+
+      def tag_end(name)
+        end_element(name)
+      end
+
+      def text(chars)
+        characters(chars)
+      end
+
+    end
+
+    module NokogiriAdapter
+
+      def xmldecl(*args); end
+      def start_document; end
+      def end_document; end
+      def start_element_namespace(name, attrs = [], prefix = nil, uri = nil, ns = [])
+        start_element(name, attrs.map { |att| [att.localname, att.value] })
+      end
+      def end_element_namespace(name, prefix = nil, uri = nil)
+        end_element(name)
+      end
+      def error(*args); end
+
+    end
+
+    # @private
+    class Frame
+
+      attr_reader :parent_frame
+
+      attr_reader :root_frame
+
+      attr_reader :element_name
+
+      attr_accessor :customizations
+
+      def initialize element_name, options = {}
+
+        @element_name = element_name
+        @context = options[:context]
+        @parent_frame = options[:parent_frame]
+        @root_frame = options[:root_frame]
+        @wrapper_frames = {}
+
+        if @parent_frame
+          @customizations = @parent_frame.customizations_for_child(element_name)
+        else
+          @customizations = options[:customizations]
+          @root_frame ||= self
+        end
+
+        if @root_frame == self and
+            indexes = @customizations[:index_names]
+          indexes.each do |name|
+            if context.kind_of?(Context)
+              context.__set_data__(name, {})
+            else
+              add_mutators(name)
+              context.send("#{name}=", {})
+            end
+          end
+        end
+
+        # we build and discard child frames here so we can know
+        # which children should always add a method to this
+        # frame's context (forced elements, like collected arrays)
+        @customizations[:children].keys.each do |child_element_name|
+          consume_initial_frame(build_child_frame(child_element_name))
+        end
+
+        if @customizations[:wrapper_frames]
+          @customizations[:wrapper_frames].keys.each do |method_name|
+            consume_initial_frame(wrapper_frame_for(method_name))
+          end
+        end
+
+      end
+
+      def build_child_frame(child_element_name)
+        Frame.new(child_element_name,
+                  :parent_frame => self,
+                  :root_frame => root_frame)
+      end
+
+      def consume_child_frame child_frame
+
+        return if child_frame.ignored?
+
+        if child_frame.wrapped?
+          child_frame.wrapper_methods.each do |method_name|
+            consume_in_wrapper(method_name, child_frame)
+          end
+        else
+          # forced child frames have already added mutators to this context
+          add_mutators_for(child_frame) unless child_frame.forced?
+
+          if child_frame.collected?
+            child_frame.add_to_collection(context.send(child_frame.getter),
+                                          child_frame.value)
+          else
+            invoke_setter(child_frame, child_frame.value)
+          end
+        end
+
+      end
+
+      def close
+        if indexed = @customizations[:indexed]
+          (name, block) = indexed
+          key = block.call(context)
+          [key].flatten.each do |k|
+            index(name)[k] = context
+          end
+        end
+      end
+
+      def add_text text
+        @text ||= ''
+        @text << text
+      end
+
+      def value
+        @customizations[:value_formatter] ?
+          @customizations[:value_formatter].format_value(default_value) :
+          default_value
+      end
+
+      def context
+        @context ||= (self.ignored? ? parent_frame.context : construct_context)
+      end
+
+      def setter
+        @customizations[:setter]
+      end
+
+      def getter
+        @customizations[:getter]
+      end
+
+      def initial_collection
+        @customizations[:initial_collection].call
+      end
+
+      def add_to_collection(collection, value)
+        @customizations[:add_to_collection].call(collection, value)
+      end
+
+      def index(name)
+        return root_frame.index(name) unless root_frame == self
+        context.send(name)
+      end
+
+      protected
+      def consume_initial_frame(child_frame)
+        if child_frame.forced?
+          add_mutators_for(child_frame)
+          if child_frame.collected?
+            invoke_setter(child_frame, child_frame.initial_collection)
+          else
+            # this allows nested forced elements to appear
+            invoke_setter(child_frame, child_frame.value)
+          end
+        end
+      end
+
+      protected
+      def construct_context
+        if @customizations[:construct_value]
+          instance_eval(&@customizations[:construct_value])
+        else
+          Context.new
+        end
+      end
+
+      protected
+      def consume_in_wrapper method_name, child_frame
+        wrapper_frame = wrapper_frame_for(method_name)
+        add_mutators(method_name)
+
+        # the wrapper consumes the unwrapped child
+        customizations = child_frame.customizations.merge(:wrapper => nil)
+        child_frame = child_frame.dup
+        child_frame.customizations = customizations
+
+        wrapper_frame.consume_child_frame(child_frame)
+        consume_child_frame(wrapper_frame)
+      end
+
+      protected
+      def wrapper_frame_for(method_name)
+        @wrapper_frames[method_name] ||=
+            Frame.new(method_name.to_s,
+                      :customizations => wrapper_customizations(method_name))
+      end
+
+      protected
+      def wrapper_customizations(method_name)
+        customizations = CustomizationContext.new(method_name)
+        customizations[:children] = @customizations[:children]
+        if wrapper_frames = @customizations[:wrapper_frames] and
+            additional = wrapper_frames[method_name]
+          additional[:children] = @customizations[:children].merge(additional[:children]) if
+            additional[:children]
+          customizations.merge!(additional)
+        end
+        customizations
+      end
+
+      protected
+      def invoke_setter(child_frame, value)
+        if context.kind_of?(Context)
+          context.__set_data__(child_frame.getter, value)
+        else
+          context.send(child_frame.setter, value)
+        end
+      end
+
+      protected
+      def add_mutators_for child_frame
+        return if context.kind_of?(Context)
+        add_mutators(child_frame.ruby_name,
+                     child_frame.setter,
+                     child_frame.getter)
+      end
+
+      protected
+      def add_mutators(variable_name,
+                       setter = nil,
+                       getter = nil)
+        return if context.kind_of?(Context)
+        variable_name = variable_name.to_s.gsub(/\?$/, '')
+        setter ||= "#{variable_name}="
+        getter ||= variable_name
+        return if context.respond_to?(getter) && context.respond_to?(setter)
+        MetaUtils.extend_method(context, setter) do |val|
+          instance_variable_set("@#{variable_name}", val)
+        end
+        MetaUtils.extend_method(context, getter) do
+          instance_variable_get("@#{variable_name}")
+        end
+      end
+
+      protected
+      def forced?
+        @customizations[:forced]
+      end
+
+      protected
+      def ignored?
+        @customizations[:ignored]
+      end
+
+      protected
+      def collected?
+        @customizations[:collected]
+      end
+
+      protected
+      def wrapped?
+        @customizations[:wrapper]
+      end
+
+      protected
+      def wrapper_methods
+        @customizations[:wrapper]
+      end
+
+      protected
+      def default_value
+        if
+          # TODO : move this out of the default value method
+          @context and
+          @context.respond_to?(:encoding) and
+          @context.encoding == 'base64'
+        then
+          Base64.decode64(@text.strip)
+        else
+          @context || @text
+        end
+      end
+
+      protected
+      def ruby_name
+        Inflection.ruby_name(@customizations[:renamed] || element_name)
+      end
+
+      protected
+      def customizations_for_child child_element_name
+        @customizations[:children][child_element_name] ||
+          CustomizationContext.new(child_element_name)
+      end
+
+      protected
+      def initial_customizations(element_name = nil)
+      end
+
+    end
+
+    # @private
+    class RootFrame < Frame
+
+      def initialize context, customizations
+        super('ROOT', :context => context, :customizations => customizations)
+      end
+
+    end
+
+    # @private
+    class StubResponse
+
+      def initialize customizations, context = nil
+        @customizations = customizations
+        stub_methods(customizations, context || self)
+      end
+
+      def inspect
+        methods = public_methods - Object.public_methods
+        "<Stub #{methods.collect{|m| ":#{m}" }.sort.join(', ')}>" 
+      end
+
+      # @private
+      private
+      def stub_methods customizations, context
+        add_wrappers_to_context(customizations, context)
+        add_child_elements_to_context(customizations, context)
+        add_indexes_to_context(customizations, context)
+      end
+
+      # @private
+      private
+      def add_wrappers_to_context customizations, context
+        wrappers(customizations) do |wrapper_name,wrapper_customizations|
+          MetaUtils.extend_method(context, wrapper_name) do
+            StubResponse.new(wrapper_customizations)
+          end
+        end
+      end
+
+      # @private
+      private
+      def add_child_elements_to_context customizations, context
+        without_wrapper(customizations) do |child_name,child_rules|
+
+          ruby_name = Inflection.ruby_name(child_rules[:renamed] || child_name)
+
+          # we stop at any collected elements
+          if child_rules[:collected]
+            MetaUtils.extend_method(context, ruby_name) { [] }
+            next
+          end
+
+          if child_rules[:construct_value] 
+            
+            MetaUtils.extend_method(context, ruby_name) do
+              child_rules[:construct_value].call
+            end
+
+          elsif child_rules[:children].empty? # has no child elements
+
+            unless child_rules[:ignored]
+
+              method_name = child_rules[:boolean] ? "#{ruby_name}?" : ruby_name
+              
+              MetaUtils.extend_method(context, method_name) do
+                if child_rules[:value_formatter]
+                  child_rules[:value_formatter].format_value('')
+                else
+                  nil
+                end
+              end
+            end
+
+          else # it has one or more child elements
+
+            if child_rules[:ignored]
+              stub_methods(child_rules, context)
+            else
+              MetaUtils.extend_method(context, ruby_name) do
+                StubResponse.new(child_rules)
+              end
+            end
+
+          end
+
+        end
+      end
+
+      # @private
+      def add_indexes_to_context(customizations, context)
+        if indexes = customizations[:index_names]
+          indexes.each do |index|
+            MetaUtils.extend_method(context, index) { {} }
+          end
+        end
+      end
+
+      # @private
+      def wrappers customizations, &block
+        wrappers = {}
+        customizations[:children].each_pair do |child_name,child_rules|
+          if child_rules[:wrapper]
+            wrapper_name = child_rules[:wrapper].first
+            wrappers[wrapper_name] ||= { :children => {} }
+            wrappers[wrapper_name][:children][child_name] = child_rules.merge(:wrapper => nil)
+          end
+        end
+
+        wrappers.each_pair do |wrapper_name, wrapper_customizations|
+          yield(wrapper_name, wrapper_customizations)
+        end
+      end
+
+      # @private
+      private
+      def without_wrapper customizations, &block
+        customizations[:children].each_pair do |child_name,child_rules|
+          unless child_rules[:wrapper]
+            yield(child_name, child_rules)
+          end
+        end
+      end
+
+    end
+
+  end
+end