github_api 0.11.3 → 0.12.0

data/lib/github_api/api/actions.rb

@@ -1,19 +1,18 @@
 # encoding: utf-8
 
 module Github
+  # Core class responsible for api interface operations
   class API
-
     # Returns all API public methods for a given class.
-    def self.inherited(klass)
-      klass.class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+    def self.extend_with_actions(child_class)
+      child_class.class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
         def self.actions
-          self.new.api_methods_in(#{klass})
+          self.new.api_methods_in(#{child_class})
         end
         def actions
-          api_methods_in(#{klass})
+          api_methods_in(#{child_class})
         end
       RUBY_EVAL
-      super
     end
 
     def api_methods_in(klass)
@@ -45,6 +44,5 @@ module Github
       end
       args
     end
-
   end # API
 end # Github

data/lib/github_api/api/arguments.rb

@@ -0,0 +1,248 @@
+# encoding: utf-8
+
+module Github
+  class API
+    # A class responsible for handilng request arguments
+    class Arguments
+      include Normalizer
+      include ParameterFilter
+      include Validations
+
+      AUTO_PAGINATION = 'auto_pagination'.freeze
+
+      # Parameters passed to request
+      attr_reader :params
+
+      # The remaining unparsed arguments
+      attr_reader :remaining
+
+      # The request api
+      attr_reader :api
+
+      # Initialize an Arguments
+      #
+      # @param [Hash] options
+      #
+      # @option options [Array[String]] :required
+      #   arguments that must be present before request is fired
+      #
+      # @option options [Github::API] :api
+      #   the reference to the current api
+      #
+      # @api public
+      def initialize(options = {}, &block)
+        normalize! options
+
+        @api      = options.fetch('api')
+        @required = options.fetch('required', []).map(&:to_s)
+        @optional = options.fetch('optional', []).map(&:to_s)
+        @assigns  = {}
+
+        yield_or_eval(&block)
+      end
+
+      # Specify required attribute(s)
+      #
+      # @api public
+      def require(*attrs, &block)
+        attrs_clone = attrs.clone
+        @required = Array(attrs_clone)
+        self
+      end
+      alias :required :require
+
+      # Specify optional attribute(s)
+      #
+      # @api public
+      def optional(*attrs, &block)
+      end
+
+      # Hash like access to request arguments
+      #
+      # @param [String, Symbol] property
+      #   the property name
+      #
+      # @api public
+      def [](property)
+        @assigns[property.to_s]
+      end
+
+      def []=(property, value)
+        @assigns[property.to_s] = value
+      end
+
+      def method_missing(method_name, *args, &block)
+        if @assigns.key?(method_name.to_s)
+          self[method_name]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @assigns.key?(method_name) || super
+      end
+
+      # Parse arguments to allow for flexible api calls
+      #
+      # Arguments can be part of parameters hash or be simple string arguments.
+      #
+      # @api public
+      def parse(*args, &block)
+        options = ParamsHash.new(args.extract_options!)
+        normalize! options
+
+        if args.size.zero?  # Arguments are inside the parameters hash
+          parse_hash(options)
+        else
+          parse_array(*args)
+        end
+        @params    = options
+        @remaining = args[@required.size..-1]
+        extract_pagination(options)
+
+        yield_or_eval(&block)
+        self
+      end
+
+      # Remove unknown keys from parameters hash.
+      #
+      # = Parameters
+      #  :recursive - boolean that toggles whether nested filtering should be applied
+      #
+      def permit(keys, key=nil, options={})
+        filter! keys, (key.nil? ? params : params[key]), options if keys.any?
+        self
+      end
+
+      # Check if required keys are present inside parameters hash.
+      #
+      # @api public
+      def assert_required(required)
+        assert_required_keys required, params
+        self
+      end
+
+      # Check if parameters match expected values.
+      #
+      # @api public
+      def assert_values(values, key=nil)
+        assert_valid_values values, (key.nil? ? params : params[key])
+        self
+      end
+
+      private
+
+      # Parse array arguments and assign in order to required properties
+      #
+      # @param [Array[Object]] args
+      #
+      # @raise ArgumentError
+      #
+      # @return [nil]
+      #
+      # @api public
+      def parse_array(*args)
+        assert_presence_of(*args)
+        @required.each_with_index do |req, indx|
+          @assigns[req] = args[indx]
+        end
+        check_requirement!(*args)
+      end
+
+      # Remove required arguments from parameters and
+      # validate their presence(if not nil or empty string).
+      #
+      # @param [Hash[String]] options
+      #
+      # @return [nil]
+      #
+      # @api private
+      def parse_hash(options)
+        options.each { |key, val| remove_required(options, key, val) }
+        hash = update_required_from_global
+        check_requirement!(*hash.keys)
+      end
+
+      # Remove required property from hash
+      #
+      # @param [Hash[String]] options
+      #   the options to check
+      #
+      # @param [String] key
+      #   the key to remove
+      #
+      # @param [String] val
+      #   the value to assign
+      #
+      # @api private
+      def remove_required(options, key, val)
+        if @required.include?(key.to_s)
+          assert_presence_of(val)
+          options.delete(key)
+          @assigns[key.to_s] = val
+        end
+      end
+
+      # Update required property from globals if not present
+      #
+      # @return [Hash[String]]
+      #
+      # @api private
+      def update_required_from_global
+        @required.reduce({}) do |hash, property|
+          if @assigns.key?(property)
+            hash[property] = self[property]
+          elsif api_property?(property)
+            hash[property] = api.send(:"#{property}")
+            self[property] = hash[property]
+          end
+          hash
+        end
+      end
+
+      # Check if api has non-empty property
+      #
+      # @param [String] property
+      #   the property to check
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def api_property?(property)
+        api.respond_to?(:"#{property}") && api.send(:"#{property}")
+      end
+
+      # Check if required arguments are present.
+      #
+      #
+      def check_requirement!(*args)
+        args_length     = args.length
+        required_length = @required.length
+
+        if args_length < required_length
+          raise ArgumentError, "Wrong number of arguments " \
+            "(#{args_length} for #{required_length}). " \
+            "Expected `#{@required.join(', ')}` as required arguments, " \
+            "but got `#{args.join(", ")}`."
+        end
+      end
+
+      # Find auto_pagination parameter in options hash
+      #
+      def extract_pagination(options)
+        if (value = options.delete(AUTO_PAGINATION))
+          api.auto_pagination = value
+        end
+      end
+
+      # Evaluate a block
+      #
+      # @api privte
+      def yield_or_eval(&block)
+        return unless block
+        block.arity > 0 ? yield(self) : instance_eval(&block)
+      end
+    end # Arguments
+  end # Api
+end # Github

data/lib/github_api/api/config.rb

@@ -0,0 +1,107 @@
+# encoding: utf-8
+
+require 'github_api/api/config/property'
+require 'github_api/api/config/property_set'
+
+module Github
+
+  class API
+    # A base class for constructing api configuration
+    class Config
+
+      # Defines a property on an object's class or instance
+      #
+      # @example
+      #   class Configuration < Api::Config
+      #     property :adapter, default: :net_http
+      #     property :user, required: true
+      #   end
+      #
+      # @param [Symbol] name
+      #   the name of a property
+      #
+      # @param [#to_hash] options
+      #   the extra options
+      #
+      # @return [self]
+      #
+      # @api public
+      def self.property(name, options = {})
+        self.property_set << Property.new(name, options)
+        update_subclasses(name, options)
+        self
+      end
+
+      def self.update_subclasses(name, options)
+        if defined?(@subclasses) && @subclasses
+          @subclasses.each { |klass| klass.property(name, options) }
+        end
+      end
+
+      # Check if property is defined
+      #
+      # @param [Symbol] name
+      #   the name to check
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def self.property?(name)
+        property_set.include?(name)
+      end
+
+      class << self
+        attr_reader :property_set
+      end
+
+      instance_variable_set("@property_set", PropertySet.new(self))
+
+      def self.inherited(descendant)
+        super
+        (@subclasses ||= Set.new) << descendant
+        descendant.instance_variable_set('@property_set',
+          PropertySet.new(descendant, self.property_set.properties.dup))
+      end
+
+      def initialize(&block)
+        super(&block)
+      end
+
+      def property_names
+        self.class.property_set.properties.map(&:name)
+      end
+
+      def self.property_names
+        property_set.properties.map(&:name)
+      end
+
+      # Fetach all the properties and their values
+      #
+      # @return [Hash[Symbol]]
+      #
+      # @api public
+      def fetch(value = nil)
+        if value
+          self.class.property_set[value]
+        else
+          self.class.property_set.to_hash
+        end
+      end
+
+      # Provide access to properties
+      #
+      # @example
+      #   config.call do |config|
+      #     config.adapter = :net_http
+      #   end
+      #
+      # @return [self]
+      #
+      # @api private
+      def call(&block)
+        block.call(self) if block_given?
+        self
+      end
+    end # Config
+  end # Api
+end # Github

data/lib/github_api/api/config/property.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+
+module Github
+  class API
+    class Config
+
+      # Property objects provide an interface for configuration options
+      class Property
+
+        attr_reader :name
+        attr_reader :default
+        attr_reader :required
+
+        def initialize(name, options)
+          @name = name
+          @default = options.fetch(:default, nil)
+          @required = options.fetch(:required, nil)
+          @options = options
+        end
+
+        # @api private
+        def define_accessor_methods(properties)
+          properties.define_reader_method(self, self.name, :public)
+          properties.define_writer_method(self, "#{self.name}=", :public)
+        end
+      end # Property
+
+    end # Config
+  end # Api
+end # Github

data/lib/github_api/api/config/property_set.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+
+module Github
+  class API
+    class Config
+      # Class responsible for storing configuration properties
+      class PropertySet
+        include Enumerable
+
+        attr_reader :parent
+
+        attr_reader :properties
+
+        # Initialize an PropertySet
+        #
+        # @param [Object] parent
+        # @param [Set] properties
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def initialize(parent = nil, properties = Set.new)
+          @parent = parent
+          @properties = properties
+          @map = {}
+        end
+
+        # Iterate over properties
+        #
+        # @yield [property]
+        #
+        # @yieldparam [Property] property
+        #
+        # @return [self]
+        #
+        # @api public
+        def each
+          return to_enum unless block_given?
+          @map.each { |name, property| yield property if name.is_a?(Symbol) }
+          self
+        end
+
+        # Adds property to the set
+        #
+        # @example
+        #   properties_set << property
+        #
+        # @param [Property] property
+        #
+        # @return [self]
+        #
+        # @api public
+        def <<(property)
+          properties << property
+          update_map(property.name, property.default)
+          property.define_accessor_methods(self)
+          self
+        end
+
+        # Access property by name
+        #
+        # @api public
+        def [](name)
+          @map[name]
+        end
+        alias_method :fetch, :[]
+
+        # Set property value by name
+        #
+        # @api public
+        def []=(name, property)
+          update_map(name, property)
+        end
+
+        # Update map with index
+        #
+        # @api private
+        def update_map(name, property)
+          @map[name.to_sym] = @map[name.to_s.freeze] = property
+        end
+
+        # Convert properties to a hash of property names and
+        # corresponding values
+        #
+        # @api public
+        def to_hash
+          properties.each_with_object({}) do |property, props|
+            name = property.name
+            props[name] = self[name]
+          end
+        end
+
+        # Check if properties exist
+        #
+        # @api public
+        def empty?
+          @map.empty?
+        end
+
+        # @api private
+        def define_reader_method(property, method_name, visibility)
+          property_set = self
+          parent.send(:define_method, method_name) { property_set[property.name] }
+          parent.send(visibility, method_name)
+        end
+
+        # @api private
+        def define_writer_method(property, method_name, visibility)
+          property_set = self
+          parent.send(:define_method, method_name) do |value|
+            property_set[property.name]= value
+          end
+          parent.send(visibility, method_name)
+        end
+      end # PropertySet
+    end # Config
+  end # Api
+end # Github