mss-sdk 1.0.0

data/lib/mss/core/xml/frame.rb

@@ -0,0 +1,245 @@
+# Copyright 2011-2013 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
+#
+#
+# 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 'base64'
+require 'date'
+require 'time'
+
+module MSS
+  module Core
+    module XML
+      class Frame
+
+        TRANSLATE_DIGITS = ['0123456789'.freeze, ('X'*10).freeze]
+
+        EASY_FORMAT = "XXXX-XX-XXTXX:XX:XX.XXXZ".freeze
+
+        DATE_PUNCTUATION = ['-:.TZ'.freeze, (' '*5).freeze]
+
+        def initialize root_frame, parent_frame, element_name, rules
+
+          @root_frame = root_frame
+          @parent_frame = parent_frame
+          @element_name = element_name
+          @rules = rules
+          @rules[:children] ||= {}
+
+          @data = {}.merge(rules[:defaults] || {})
+          @text = nil
+
+          # initialize values for child frames of special types (e.g.
+          # lists, maps, and forced elements)
+          known_child_frames.each do |child_frame|
+            context = data_context_for(child_frame)
+            if child_frame.list?
+              context[child_frame.ruby_name] = []
+            elsif child_frame.map?
+              context[child_frame.ruby_name] = {}
+            elsif child_frame.forced?
+              context[child_frame.ruby_name] = child_frame.value
+            end
+          end
+
+        end
+
+        attr_reader :root_frame
+        attr_reader :parent_frame
+        attr_reader :element_name
+        attr_reader :rules
+
+        def data
+          ignored? ? parent_frame.data : @data
+        end
+
+        def ruby_name
+          rules[:rename] || root_frame.inflect(element_name)
+        end
+
+        def rules_for child_element_name
+          rules[:children][child_element_name] || {}
+        end
+
+        # The list of child frames that have customizations (rules), all
+        # other children will be parsed using standard rules
+        def known_child_frames
+          rules[:children].keys.map {|name| build_child_frame(name) }
+        end
+
+        def build_child_frame element_name
+          # if element_name should be wrapped
+          #   build a frame for the wrapper
+          #   build a child frame from the wrapper
+          # else
+          Frame.new(root_frame, self, element_name, rules_for(element_name))
+        end
+
+        def consume_child_frame child_frame
+
+          child_frame.close
+
+          return if child_frame.ignored?
+
+          ruby_name = child_frame.ruby_name
+          value = child_frame.value
+          context = data_context_for(child_frame)
+
+          if child_frame.list?
+            context[ruby_name] << value
+          elsif map = child_frame.map?
+            context[ruby_name][child_frame.map_key] = child_frame.map_value
+          else
+            context[ruby_name] = value
+          end
+        end
+
+        def close
+          # some xml elements should be indexed at the root level
+          # The :index rule determines the name of this index
+          # and what keys the data should be indexed as (one element
+          # can be indexed under multiple keys).  The index value
+          # is always the element itself.
+          if index = @rules[:index]
+            index_keys_for(index) do |key|
+              root_frame.add_to_index(index[:name], key, data)
+            end
+          end
+        end
+
+        def index_keys_for index_opts, &block
+
+          # simple (single) key
+          if key = index_opts[:key]
+            yield(data[key])
+            return
+          end
+
+          # composite key, joined by ":"
+          if parts = index_opts[:keys]
+            composite_key = parts.map{|part| data[part] }.join(":")
+            yield(composite_key)
+            return
+          end
+
+          # multiple keys, collected from the given path
+          if path = index_opts[:key_path]
+            keys_from_path(data, path.dup, &block)
+            return
+          end
+
+          raise "missing require index rule option, :key, :keys or :key_path"
+
+        end
+
+        def keys_from_path data, path, &block
+
+          step = path.shift
+          value = data[step]
+
+          if path.empty?
+            yield(value)
+            return
+          end
+
+          if value.is_a?(Array)
+            value.each do |v|
+              keys_from_path(v, path.dup, &block)
+            end
+          else
+            keys_from_path(value, path.dup, &block)
+          end
+
+        end
+
+        def add_text chars
+          @text ||= ''
+          @text << chars
+        end
+
+        def value
+          if !data.empty?
+            data[:encoding] == 'base64' ?  Base64.decode64(@text.strip) : data
+          elsif @text.nil?
+            rules[:type] == :boolean ? false : nil
+          else
+            case rules[:type]
+            when nil, :string then @text
+            when :datetime    then datetime_like_value(DateTime, :civil)
+            when :time        then datetime_like_value(Time, :utc)
+            when :integer     then @text.to_i
+            when :float       then @text.to_f
+            when :boolean     then @text == 'true'
+            when :blob        then Base64.decode64(@text)
+            when :symbol      then Core::Inflection.ruby_name(@text).to_sym
+            else raise "unhandled type"
+            end
+          end
+        end
+
+        def ignored?
+          @rules[:ignore]
+        end
+
+        def forced?
+          @rules[:force]
+        end
+
+        def list?
+          @rules[:list]
+        end
+
+        def map?
+          @rules[:map]
+        end
+
+        def wrapped?
+          @rules[:wrap]
+        end
+        alias_method :wrapper, :wrapped?
+
+        protected
+
+        def map_key
+          data[root_frame.inflect(@rules[:map].first)]
+        end
+
+        def map_value
+          data[root_frame.inflect(@rules[:map].last)]
+        end
+
+        def data_context_for child_frame
+          if child_frame.wrapped?
+            data[child_frame.wrapper] ||= {}
+            data[child_frame.wrapper]
+          else
+            data
+          end
+        end
+
+        def datetime_like_value klass, parts_constructor
+          # it's way faster to parse this specific format manually
+          # vs. DateTime#parse, and this happens to be the format
+          # that MSS uses almost (??) everywhere.
+          if @text.tr(*TRANSLATE_DIGITS) == EASY_FORMAT
+            parts = @text.tr(*DATE_PUNCTUATION).chop.split.map {|p| p.to_i }
+            milliseconds = parts.pop
+            parts[-1] = parts[-1] + Rational(milliseconds, 1000)  #Ruby 1.8.7 compatibility
+            klass.send(parts_constructor, *parts)
+          else
+            # fallback in case we have to handle another date format
+            klass.parse(@text)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/mss/core/xml/frame_stack.rb

@@ -0,0 +1,84 @@
+# Copyright 2011-2013 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
+#
+#
+# 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.
+
+module MSS
+  module Core
+    module XML
+
+      # @api private
+      module FrameStack
+
+        # @param [Hash] rules A hash of parser rules.  These
+        #   rules are typically generated by an {XML::Grammar}.
+        def initialize rules
+          @frame = RootFrame.new(rules)
+        end
+
+        def sax_parse xml
+          raise NotImplementedError
+        end
+        protected :sax_parse
+
+        # Parses the xml string and returns a hash with the resutls.
+        # @param [String] xml
+        # @return [Hash]
+        def parse xml
+          sax_parse(xml)
+          @frame.value
+        end
+
+        # Increase the frame stack level by one.
+        # @param [String] element_name The name of the xml opening tag.
+        # @param [Hash] attributes A hash of xml element attributes.
+        # @return [nil]
+        def start_element element_name, attributes = {}
+          @frame = @frame.build_child_frame(element_name)
+          self.attributes(attributes)
+          nil
+        end
+
+        # Increase the frame stack level by one by treating
+        # xml element attributes as nested elements.
+        # @param [Hash] attributes A hash of attributes names to values.
+        # @return [nil]
+        def attributes attributes
+          attributes.each_pair 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
+          nil
+        end
+
+        # Pops the top frame off the stack.  When closing frames
+        # their final value is computed.
+        # @overload end_element
+        # @return [nil]
+        def end_element *ignored
+          parent = @frame.parent_frame
+          child = @frame
+          parent.consume_child_frame(child)
+          @frame = @frame.parent_frame
+          nil
+        end
+
+        # Adds text to the current frame.  Frames that only contain
+        # text and no child elements are leaf nodes and have
+        # raw string values.
+        def set_text text
+          @frame.add_text(text) if @frame
+        end
+
+      end
+    end
+  end
+end

data/lib/mss/core/xml/grammar.rb

@@ -0,0 +1,306 @@
+# Copyright 2011-2013 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
+#
+#
+# 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.
+
+module MSS
+  module Core
+    module XML
+
+      # A class that simplifies building XML {Parser} rules.  This is also
+      # a compatability layer between the old and new formats of the api
+      # config.
+      class Grammar
+
+        def initialize rules = {}, options = {}
+          @rules = rules
+          @context = @rules
+          @element_name = 'xml'
+          @inflect_rename = options.key?(:inflect_rename) ?
+            options[:inflect_rename] : true
+        end
+
+        # Parses the XML with the rules provided by the current grammar.
+        # This method is meant to provide backwards compatability with
+        # the old XmlGrammar class that handled rules and parsing.
+        # @param [String] xml
+        # @return [Data] Returns a hash-like parsed response.
+        def parse xml
+          Data.new(Parser.parse(xml, rules))
+        end
+
+        # @return [Hash] Returns a hash of rules defined by this grammar.
+        attr_reader :rules
+
+        # Returns a new grammar (leaving the current one un-modified) with
+        # the given customizations applied.  Customizations can be given in
+        # a hash-form or in a block form.
+        #
+        # @example Block-form customizations
+        #
+        #   grammar.customize do
+        #     element "EnumElement" do
+        #       symbol_value
+        #       list
+        #     end
+        #   end
+        #
+        # @example Hash-form customizations
+        #
+        #   grammar.customize "EnumElement" => [:symbol_value, :list]
+        #
+        # @return [Grammar] Returns a grammar with the given customizations
+        #   applied.
+        #
+        def customize customizations = nil, &block
+          opts = { :inflect_rename => @inflect_rename }
+          self.class.customize(customizations, @rules, opts, &block)
+        end
+
+        # Applies customizations to the current grammar, not returning
+        # a new grammar.
+        def customize! customizations = nil, &block
+          apply_customizations(customizations) if customizations
+          instance_eval(&block) if block_given?
+          self
+        end
+
+        def self.customize customizations = nil, rules = {}, opts = {}, &block
+          grammar = self.new(deep_copy(rules), opts)
+          grammar.send(:apply_customizations, customizations) if customizations
+          grammar.instance_eval(&block) if block_given?
+          grammar
+        end
+
+        def self.parse xml
+          self.new.parse(xml)
+        end
+
+        protected
+
+        # Performs a deep copy of the rules hash so that it can be
+        # customized without chaning the parent grammar.
+        def self.deep_copy rules
+          rules.inject({}) do |copy,(key,value)|
+            copy[key] = value.is_a?(Hash) ? deep_copy(value) : value
+            copy
+          end
+        end
+
+        def apply_customizations customizations
+          customizations.each do |item|
+            (type, identifier, args) = parse_customization_item(item)
+            case type
+            when :method
+              validate_config_method(identifier)
+              validate_args(identifier, args)
+              send(identifier, *args)
+            when :element
+              element(identifier) do
+                apply_customizations(args)
+              end
+            end
+          end
+        end
+
+        def parse_customization_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
+
+        def validate_config_method(method)
+          allow_methods = %w(
+            rename attribute_name boolean integer long float list force string
+            ignore collect_values symbol_value timestamp map_entry map blob
+            enum position
+          )
+          unless allow_methods.include?(method.to_s)
+            raise "#{method} cannot be used in configuration"
+          end
+        end
+
+        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
+
+        def inflect value
+          Inflection.ruby_name(value.to_s).to_sym
+        end
+
+        # customization methods
+
+        def element element_name, &block
+
+          parent_context = @context
+          parent_element_name = @element_name
+
+          @context = context_for_child(element_name)
+
+          @element_name = element_name
+
+          begin
+            if block_given?
+              block.arity == 1 ? yield(parent_element_name) : yield
+            end
+          ensure
+            @context = parent_context
+            @element_name = parent_element_name
+          end
+
+        end
+
+        def ignore
+          @context[:ignore] = true
+        end
+
+        def rename new_name
+          if @inflect_rename
+            @context[:rename] = inflect(new_name)
+          else
+            @context[:rename] = new_name
+          end
+        end
+
+        def force
+          @context[:force] = true
+        end
+
+        def collect_values
+          @context[:list] = true
+        end
+
+        def index index_name, options = {}
+          @context[:index] = options.merge(:name => index_name)
+        end
+
+        def default_value name, value
+          @context[:defaults] ||= {}
+          @context[:defaults][name] = value
+        end
+
+        def list child_element_name = nil, &block
+          if child_element_name
+            ignore
+            element(child_element_name) do |parent_element_name|
+              rename(parent_element_name)
+              collect_values
+              yield if block_given?
+            end
+          else
+            collect_values
+          end
+        end
+
+        def map_entry key_element_name, value_element_name
+          @context[:map] = [key_element_name, value_element_name]
+        end
+
+        def map map_element_name, key_element_name, value_element_name
+          ignore
+          element(map_element_name) do |parent_element_name|
+            rename(parent_element_name)
+            map_entry(key_element_name, value_element_name)
+          end
+        end
+
+        def wrapper method_name, options = {}, &block
+          options[:for].each do |child|
+            context_for_child(child)[:wrap] = method_name
+          end
+        end
+
+        def construct_value &block
+          raise 'remove the need for this'
+        end
+
+        def boolean_value
+          @context[:type] = :boolean
+        end
+        alias_method :boolean, :boolean_value
+
+        def blob_value
+          @context[:type] = :blob
+        end
+        alias_method :blob, :blob_value
+
+        def datetime_value
+          @context[:type] = :datetime
+        end
+        alias_method :datetime, :datetime_value
+
+        def time_value
+          @context[:type] = :time
+        end
+        alias_method :timestamp, :time_value
+        alias_method :time, :time_value
+
+        def string_value
+          @context[:type] = :string
+        end
+        alias_method :string, :string_value
+
+        def integer_value
+          @context[:type] = :integer
+        end
+        alias_method :integer, :integer_value
+        alias_method :long, :integer_value
+
+        def float_value
+          @context[:type] = :float
+        end
+        alias_method :float, :float_value
+
+        def symbol_value
+          @context[:type] = :symbol
+        end
+        alias_method :symbol, :symbol_value
+
+        def eql? other
+          other.is_a?(Grammar) and self.rules == other.rules
+        end
+        alias_method :==, :eql?
+        public :==
+
+        def enum *args; end
+        def position *args; end
+        def http_trait *args; end
+        alias_method :http_header, :http_trait
+        alias_method :http_uri_label, :http_trait
+        alias_method :http_payload, :http_trait
+        alias_method :http_status, :http_trait
+
+
+        protected
+        def context_for_child child_element_name
+          @context[:children] ||= {}
+          @context[:children][child_element_name] ||= {}
+          @context[:children][child_element_name]
+        end
+
+      end
+    end
+  end
+end

data/lib/mss/core/xml/parser.rb

@@ -0,0 +1,69 @@
+# Copyright 2011-2013 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
+#
+#
+# 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.
+
+module MSS
+  module Core
+    module XML
+      class Parser
+
+        # @param [Hash] rules A has of xml parsing rules.  Generally
+        #   rules will come from an xml grammar.
+        def initialize rules = {}
+          @rules = rules
+        end
+
+        # @return [Hash] Returns the rules for this xml parser that define
+        #   how it should transform the XMl into Ruby.
+        attr_reader :rules
+
+        # @param [String] xml An XML document string to parse.
+        # @return [Hash] Returns a hash of parsed xml data.
+        def parse xml
+          xml = '<xml/>' if xml.nil? or xml.empty?
+          sax_handler.parse(xml)
+        end
+
+        # @return [Hash] Returns a hash of mostly empty placeholder data.
+        def simulate
+          XML::Stub.simulate(rules)
+        end
+
+        # @param [String] xml An XML document string to parse.
+        # @param [Hash] rules A has of xml parsing rules.  Generally
+        #   rules will come from an xml grammar.
+        # @return [Hash] Returns a hash of parsed xml data.
+        def self.parse xml, rules = {}
+          self.new(rules).parse(xml)
+        end
+
+        protected
+
+        # There are three handlers, nokogiri is the fastest, followed
+        # by libxml-ruby.  Lastly (by a long shot) is REXML.  REXML
+        # is the only library that does not  rely on a native
+        # extension.
+        #
+        # Currently you can not choose your xml sax handler, and the only
+        # we express a gem dependency on is nokogiri.
+        #
+        def sax_handler
+          begin
+            SaxHandlers::Nokogiri.new(rules)
+          rescue NameError, LoadError
+            SaxHandlers::REXML.new(rules)
+          end
+        end
+
+      end
+    end
+  end
+end