mss-sdk 1.0.0

data/lib/mss/core/data.rb

@@ -0,0 +1,251 @@
+# 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
+
+    # Data is a light wrapper around a Ruby hash that provides
+    # method missing access to the hash contents.
+    #
+    # ## Method Missing Access
+    #
+    # You can access hash content with methods if their keys
+    # are symbols.
+    #
+    #     data = MSS::Core::Data.new({ :a => 1, :b => 2, :c => true })
+    #     data.a #=> 1
+    #     data.b #=> 2
+    #     data.c #=> true
+    #     data.d #=> raises NoMethodError
+    #
+    # ## Boolean Methods
+    #
+    # Given the structure above you can also use question-mark methods.
+    #
+    #     data.c? #=> true
+    #     data.d? #=> raises NoMethodError
+    #
+    # ## Nested Hashes
+    #
+    # If the data contains nested hashes you can chain methods into
+    # the structure.
+    #
+    #     data = MSS::Core::Data.new(:a => { :b => { :c => 'abc' }})
+    #     data.a.b.c #=> 'abc'
+    #
+    # ## Nested Arrays
+    #
+    # Arrays are wrapped in {Data::List} objects.  They ensure any
+    # data returned is correctly wrapped so you can continue using
+    # method-missing access.
+    #
+    #     data = MSS::Core::Data.new(
+    #      :people => [
+    #        {:name => 'john'},
+    #        {:name => 'jane'},
+    #     ]})
+    #
+    #     data.people[0].name #=> 'john'
+    #     data.people[1].name #=> 'jane'
+    #
+    #     data.people.map(&:name) #=> ['john','jane']
+    #
+    class Data
+
+      module MethodMissingProxy
+
+        # @api private
+        def id
+          self[:id] || self.id
+        end
+
+        def [] index_or_key
+          Data.cast(@data[index_or_key])
+        end
+
+        # @return [Boolean] Returns true if the passed object equals
+        #   the wrapped array.
+        def eql? other
+          if other.is_a?(MethodMissingProxy)
+            @data == other._data
+          else
+            @data == other
+          end
+        end
+        alias_method :==, :eql?
+
+        def dup
+          Data.cast(@data.dup)
+        end
+        alias_method :clone, :dup
+
+        protected
+
+        def method_missing *args, &block
+          if block_given?
+            return_value = @data.send(*args) do |*values|
+              yield(*values.flatten.map{|v| Data.cast(v) })
+            end
+            Data.cast(return_value)
+          else
+            Data.cast(@data.send(*args))
+          end
+        end
+
+        def _data
+          @data
+        end
+
+      end
+
+      include MethodMissingProxy
+
+      def method_missing method_name, *args, &block
+        if
+          args.empty? and !block_given? and
+          key = _remove_question_mark(method_name) and
+          @data.has_key?(key)
+        then
+          Data.cast(@data[key])
+        else
+          super
+        end
+      end
+
+      # @param [Hash] data The ruby hash of data you need wrapped.
+      def initialize data
+        @data = data
+      end
+
+      # @return [Hash] Returns contents of this Data object as a raw hash.
+      def to_hash
+        @data
+      end
+      alias_method :to_h, :to_hash
+
+      # @return [Array]
+      def to_a
+        @data.to_a
+      end
+      alias_method :to_ary, :to_a
+
+      # @param [String,Symbol] method_name
+      # @return [Boolean] Returns true if this data object will
+      #   respond to the given method name.
+      def respond_to? method_name
+        @data.key?(_remove_question_mark(method_name)) or
+          @data.respond_to?(method_name)
+      end
+
+      # Returns an inspection string from the wrapped data.
+      #
+      #     data = MSS::Core::Data.new({ :a => 1, :b => 2, :c => true })
+      #     data.inspect #=> '{:a=>1, :b=>2, :c=>true}'
+      #
+      # @return [String]
+      #
+      def inspect
+        @data.inspect
+      end
+
+      # @api private
+      def kind_of? klass
+        if klass == Hash
+          true
+        else
+          super
+        end
+      end
+      alias_method :is_a?, :kind_of?
+
+      protected
+
+      def _remove_question_mark method_name
+        case method_name
+        when Symbol then method_name.to_s.sub(/\?$/, '').to_sym
+        when String then method_name.sub(/\?$/, '')
+        else method_name
+        end
+      end
+
+      class << self
+
+        # Given a hash, this method returns a {Data} object.  Given
+        # an Array, this method returns a {Data::List} object.  Everything
+        # else is returned as is.
+        #
+        # @param [Object] value The value to conditionally wrap.
+        #
+        # @return [Data,Data::List,Object] Wraps hashes and lists with
+        #   Data and List objects, all other objects are returned as
+        #   is.
+        #
+        def cast value
+          case value
+          when Hash then Data.new(value)
+          when Array then Data::List.new(value)
+          else value
+          end
+        end
+
+      end
+
+      class List
+
+        include MethodMissingProxy
+
+        # @param [Array] array
+        def initialize array
+          @data = array
+        end
+
+        # @return [String] Returns the inspection string for the
+        #   wrapped array.
+        def inspect
+          @data.inspect
+        end
+
+        # @return [Array] Returns the contents of this Data::List as
+        #   a raw array.
+        def to_ary
+          @data
+        end
+        alias_method :to_a, :to_ary
+
+        # #inject works on Core::Data::List in in 1.8.7 and 1.9.3, but not
+        # in 1.9.2 unless we define it like so.
+        # @api private
+        def inject *args, &block
+          @data.inject(*args) do |obj,value|
+            yield(Data.cast(obj),Data.cast(value))
+          end
+        end
+
+        # @api private
+        def kind_of? klass
+          if klass == Array
+            true
+          else
+            super
+          end
+        end
+        alias_method :is_a?, :kind_of?
+
+        # @api private
+        def empty?
+          @data.empty?
+        end
+
+      end
+    end
+  end
+end

data/lib/mss/core/deprecations.rb

@@ -0,0 +1,83 @@
+# 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
+
+    # A utility module that provides a class method that wraps
+    # a method such that it generates a deprecation warning when called.
+    # Given the following class:
+    #
+    #     class Example
+    #
+    #       def do_something
+    #       end
+    #
+    #     end
+    #
+    # If you want to deprecate the `#do_something` method, you can extend
+    # this module and then call `deprecated` on the method (after it
+    # has been defined).
+    #
+    #     class Example
+    #
+    #       extend MSS::Core::Deprecations
+    #
+    #       def do_something
+    #       end
+    #
+    #       def do_something_else
+    #       end
+    #
+    #       deprecated :do_something
+    #
+    #     end
+    #
+    # The `#do_something` method will continue to function, but will
+    # generate a deprecation warning when called.
+    #
+    # @api private
+    module Deprecations
+
+      # @param [Symbol] method The name of the deprecated method.
+      #
+      # @option options [String] :message The warning message to issue
+      #   when the deprecated method is called.
+      #
+      # @option options [Symbol] :use The name of an use
+      #   method that should be used.
+      #
+      def deprecated method, options = {}
+
+        deprecation_msg = options[:message] || begin
+          msg = "DEPRECATION WARNING: called deprecated method `#{method}' "
+          msg << "of #{self.name}"
+          msg << ", try calling #{options[:use]} instead" if options[:use]
+          msg
+        end
+
+        alias_method(:"deprecated_#{method}", method)
+
+        warned = false # we only want to issue this warning once
+
+        define_method(method) do |*args,&block|
+          unless warned
+            warn(deprecation_msg)
+            warned = true
+          end
+          send("deprecated_#{method}", *args, &block)
+        end
+      end
+
+    end
+  end
+end

data/lib/mss/core/endpoints.rb

@@ -0,0 +1,36 @@
+# 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 'json'
+
+module MSS
+  module Core
+    # Provides a read-only interface to the bundled endpoints.json file.
+    module Endpoints
+
+      def hostname(region, endpoint_prefix)
+        region = endpoints["regions"][region] || {}
+        endpoint = region[endpoint_prefix] || {}
+        endpoint["hostname"]
+      end
+      module_function :hostname
+
+      def endpoints
+        @endpoints ||= begin
+          JSON.parse(File.read(File.join(MSS::ROOT, 'endpoints.json')))
+        end
+      end
+      module_function :endpoints
+
+    end
+  end
+end