grape 0.8.0 → 0.9.0

data/lib/grape/api/helpers.rb

@@ -0,0 +1,7 @@
+module Grape
+  class API
+    module Helpers
+      include Grape::DSL::Helpers::BaseHelper
+    end
+  end
+end

data/lib/grape/dsl/callbacks.rb

@@ -0,0 +1,27 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module Callbacks
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def before(&block)
+          imbue(:befores, [block])
+        end
+
+        def before_validation(&block)
+          imbue(:before_validations, [block])
+        end
+
+        def after_validation(&block)
+          imbue(:after_validations, [block])
+        end
+
+        def after(&block)
+          imbue(:afters, [block])
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/configuration.rb

@@ -0,0 +1,27 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module Configuration
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        attr_writer :logger
+        attr_reader :settings
+
+        def logger(logger = nil)
+          if logger
+            @logger = logger
+          else
+            @logger ||= Logger.new($stdout)
+          end
+        end
+
+        # Add a description to the next namespace or function.
+        def desc(description, options = {})
+          @last_description = options.merge(description: description)
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/helpers.rb

@@ -0,0 +1,86 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module Helpers
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Add helper methods that will be accessible from any
+        # endpoint within this namespace (and child namespaces).
+        #
+        # When called without a block, all known helpers within this scope
+        # are included.
+        #
+        # @param [Module] new_mod optional module of methods to include
+        # @param [Block] block optional block of methods to include
+        #
+        # @example Define some helpers.
+        #
+        #     class ExampleAPI < Grape::API
+        #       helpers do
+        #         def current_user
+        #           User.find_by_id(params[:token])
+        #         end
+        #       end
+        #     end
+        #
+        def helpers(new_mod = nil, &block)
+          if block_given? || new_mod
+            mod = settings.peek[:helpers] || Module.new
+            if new_mod
+              inject_api_helpers_to_mod(new_mod) if new_mod.is_a?(BaseHelper)
+              mod.class_eval do
+                include new_mod
+              end
+            end
+            if block_given?
+              inject_api_helpers_to_mod(mod) do
+                mod.class_eval(&block)
+              end
+            end
+            set(:helpers, mod)
+          else
+            mod = Module.new
+            settings.stack.each do |s|
+              mod.send :include, s[:helpers] if s[:helpers]
+            end
+            change!
+            mod
+          end
+        end
+
+        protected
+
+        def inject_api_helpers_to_mod(mod, &block)
+          mod.extend(BaseHelper)
+          yield if block_given?
+          mod.api_changed(self)
+        end
+      end
+
+      # This module extends user defined helpers
+      # to provide some API-specific functionality
+      module BaseHelper
+        attr_accessor :api
+        def params(name, &block)
+          @named_params ||= {}
+          @named_params.merge! name => block
+        end
+
+        def api_changed(new_api)
+          @api = new_api
+          process_named_params
+        end
+
+        protected
+
+        def process_named_params
+          if @named_params && @named_params.any?
+            api.imbue(:named_params, @named_params)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/inside_route.rb

@@ -0,0 +1,227 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module InsideRoute
+      extend ActiveSupport::Concern
+
+      # A filtering method that will return a hash
+      # consisting only of keys that have been declared by a
+      # `params` statement against the current/target endpoint or parent
+      # namespaces
+      #
+      # @param params [Hash] The initial hash to filter. Usually this will just be `params`
+      # @param options [Hash] Can pass `:include_missing`, `:stringify` and `:include_parent_namespaces`
+      # options. `:include_parent_namespaces` defaults to true, hence must be set to false if
+      # you want only to return params declared against the current/target endpoint
+      def declared(params, options = {}, declared_params = nil)
+        options[:include_missing] = true unless options.key?(:include_missing)
+        options[:include_parent_namespaces] = true unless options.key?(:include_parent_namespaces)
+        if declared_params.nil?
+          declared_params = !options[:include_parent_namespaces] ? settings[:declared_params] :
+              settings.gather(:declared_params)
+        end
+
+        unless declared_params
+          raise ArgumentError, "Tried to filter for declared parameters but none exist."
+        end
+
+        if params.is_a? Array
+          params.map do |param|
+            declared(param || {}, options, declared_params)
+          end
+        else
+          declared_params.inject({}) do |hash, key|
+            key = { key => nil } unless key.is_a? Hash
+
+            key.each_pair do |parent, children|
+              output_key = options[:stringify] ? parent.to_s : parent.to_sym
+              if params.key?(parent) || options[:include_missing]
+                hash[output_key] = if children
+                                     declared(params[parent] || {}, options, Array(children))
+                                   else
+                                     params[parent]
+                                   end
+              end
+            end
+
+            hash
+          end
+        end
+      end
+
+      # The API version as specified in the URL.
+      def version
+        env['api.version']
+      end
+
+      # End the request and display an error to the
+      # end user with the specified message.
+      #
+      # @param message [String] The message to display.
+      # @param status [Integer] the HTTP Status Code. Defaults to default_error_status, 500 if not set.
+      def error!(message, status = nil, headers = nil)
+        self.status(status || settings[:default_error_status])
+        throw :error, message: message, status: self.status, headers: headers
+      end
+
+      # Redirect to a new url.
+      #
+      # @param url [String] The url to be redirect.
+      # @param options [Hash] The options used when redirect.
+      #                       :permanent, default false.
+      def redirect(url, options = {})
+        merged_options = { permanent: false }.merge(options)
+        if merged_options[:permanent]
+          status 301
+        else
+          if env['HTTP_VERSION'] == 'HTTP/1.1' && request.request_method.to_s.upcase != "GET"
+            status 303
+          else
+            status 302
+          end
+        end
+        header "Location", url
+        body ""
+      end
+
+      # Set or retrieve the HTTP status code.
+      #
+      # @param status [Integer] The HTTP Status Code to return for this request.
+      def status(status = nil)
+        if status
+          @status = status
+        else
+          return @status if @status
+          case request.request_method.to_s.upcase
+          when 'POST'
+            201
+          else
+            200
+          end
+        end
+      end
+
+      # Set an individual header or retrieve
+      # all headers that have been set.
+      def header(key = nil, val = nil)
+        if key
+          val ? @header[key.to_s] = val : @header.delete(key.to_s)
+        else
+          @header
+        end
+      end
+
+      # Set response content-type
+      def content_type(val = nil)
+        if val
+          header('Content-Type', val)
+        else
+          header['Content-Type']
+        end
+      end
+
+      # Set or get a cookie
+      #
+      # @example
+      #   cookies[:mycookie] = 'mycookie val'
+      #   cookies['mycookie-string'] = 'mycookie string val'
+      #   cookies[:more] = { value: '123', expires: Time.at(0) }
+      #   cookies.delete :more
+      #
+      def cookies
+        @cookies ||= Cookies.new
+      end
+
+      # Allows you to define the response body as something other than the
+      # return value.
+      #
+      # @example
+      #   get '/body' do
+      #     body "Body"
+      #     "Not the Body"
+      #   end
+      #
+      #   GET /body # => "Body"
+      def body(value = nil)
+        if value
+          @body = value
+        else
+          @body
+        end
+      end
+
+      # Allows you to make use of Grape Entities by setting
+      # the response body to the serializable hash of the
+      # entity provided in the `:with` option. This has the
+      # added benefit of automatically passing along environment
+      # and version information to the serialization, making it
+      # very easy to do conditional exposures. See Entity docs
+      # for more info.
+      #
+      # @example
+      #
+      #   get '/users/:id' do
+      #     present User.find(params[:id]),
+      #       with: API::Entities::User,
+      #       admin: current_user.admin?
+      #   end
+      def present(*args)
+        options = args.count > 1 ? args.extract_options! : {}
+        key, object = if args.count == 2 && args.first.is_a?(Symbol)
+                        args
+                      else
+                        [nil, args.first]
+                      end
+        entity_class = entity_class_for_obj(object, options)
+
+        root = options.delete(:root)
+
+        representation = if entity_class
+                           embeds = { env: env }
+                           embeds[:version] = env['api.version'] if env['api.version']
+                           entity_class.represent(object, embeds.merge(options))
+                         else
+                           object
+                         end
+
+        representation = { root => representation } if root
+        representation = (@body || {}).merge(key => representation) if key
+        body representation
+      end
+
+      # Returns route information for the current request.
+      #
+      # @example
+      #
+      #   desc "Returns the route description."
+      #   get '/' do
+      #     route.route_description
+      #   end
+      def route
+        env["rack.routing_args"][:route_info]
+      end
+
+      def entity_class_for_obj(object, options)
+        entity_class = options.delete(:with)
+
+        if entity_class.nil?
+          # entity class not explicitely defined, auto-detect from relation#klass or first object in the collection
+          object_class = if object.respond_to?(:klass)
+                           object.klass
+                         else
+                           object.respond_to?(:first) ? object.first.class : object.class
+                         end
+
+          object_class.ancestors.each do |potential|
+            entity_class ||= (settings[:representations] || {})[potential]
+          end
+
+          entity_class ||= object_class.const_get(:Entity) if object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
+        end
+
+        entity_class
+      end
+    end
+  end
+end

data/lib/grape/dsl/middleware.rb

@@ -0,0 +1,33 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module Middleware
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Apply a custom middleware to the API. Applies
+        # to the current namespace and any children, but
+        # not parents.
+        #
+        # @param middleware_class [Class] The class of the middleware you'd like
+        #   to inject.
+        def use(middleware_class, *args, &block)
+          arr = [middleware_class, *args]
+          arr << block if block_given?
+          imbue(:middleware, [arr])
+        end
+
+        # Retrieve an array of the middleware classes
+        # and arguments that are currently applied to the
+        # application.
+        def middleware
+          settings.stack.inject([]) do |a, s|
+            a += s[:middleware] if s[:middleware]
+            a
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/parameters.rb

@@ -0,0 +1,79 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module Parameters
+      extend ActiveSupport::Concern
+
+      def use(*names)
+        named_params = @api.settings[:named_params] || {}
+        options = names.last.is_a?(Hash) ? names.pop : {}
+        names.each do |name|
+          params_block = named_params.fetch(name) do
+            raise "Params :#{name} not found!"
+          end
+          instance_exec(options, &params_block)
+        end
+      end
+      alias_method :use_scope, :use
+      alias_method :includes, :use
+
+      def requires(*attrs, &block)
+        orig_attrs = attrs.clone
+
+        opts = attrs.last.is_a?(Hash) ? attrs.pop : nil
+
+        if opts && opts[:using]
+          require_required_and_optional_fields(attrs.first, opts)
+        else
+          validate_attributes(attrs, opts, &block)
+
+          block_given? ? new_scope(orig_attrs, &block) :
+              push_declared_params(attrs)
+        end
+      end
+
+      def optional(*attrs, &block)
+        orig_attrs = attrs
+
+        validations = {}
+        validations.merge!(attrs.pop) if attrs.last.is_a?(Hash)
+        validations[:type] ||= Array if block_given?
+        validates(attrs, validations)
+
+        block_given? ? new_scope(orig_attrs, true, &block) :
+            push_declared_params(attrs)
+      end
+
+      def mutually_exclusive(*attrs)
+        validates(attrs, mutual_exclusion: true)
+      end
+
+      def exactly_one_of(*attrs)
+        validates(attrs, exactly_one_of: true)
+      end
+
+      def at_least_one_of(*attrs)
+        validates(attrs, at_least_one_of: true)
+      end
+
+      def group(*attrs, &block)
+        requires(*attrs, &block)
+      end
+
+      def params(params)
+        params = @parent.params(params) if @parent
+        if @element
+          if params.is_a?(Array)
+            params = params.flat_map { |el| el[@element] || {} }
+          elsif params.is_a?(Hash)
+            params = params[@element] || {}
+          else
+            params = {}
+          end
+        end
+        params
+      end
+    end
+  end
+end