brainstem 1.0.0.pre.1 → 1.0.0

data/lib/brainstem/concerns/controller_param_management.rb

@@ -1,22 +1,43 @@
-# Provide `brainstem_model_name` and `brainstem_plural_model_name` in controllers for use when accessing the `params` hash.
+require 'active_support/concern'
+require 'active_support/inflector'
+
+# Provide `brainstem_model_name` and `brainstem_plural_model_name` in
+# controllers for use when accessing the `params` hash.
 
 module Brainstem
   module Concerns
     module ControllerParamManagement
       extend ActiveSupport::Concern
 
-      included do
-        class_attribute :brainstem_plural_model_name, :brainstem_model_name,
-                        instance_accessor: false, instance_reader: false, instance_writer: false
-      end
-
       def brainstem_model_name
-        self.class.brainstem_model_name.to_s.presence || controller_name.singularize
+        self.class.brainstem_model_name.to_s
       end
 
       def brainstem_plural_model_name
-        self.class.brainstem_plural_model_name.to_s.presence || brainstem_model_name.pluralize
+        self.class.brainstem_plural_model_name.to_s
+      end
+
+      module ClassMethods
+        def brainstem_model_name
+          @brainstem_model_name ||= controller_name.singularize
+        end
+
+        def brainstem_plural_model_name
+          @brainstem_plural_model_name ||= self.brainstem_model_name.pluralize
+        end
+
+        def brainstem_model_name=(name)
+          @brainstem_model_name = name
+        end
+
+        def brainstem_plural_model_name=(name)
+          @brainstem_plural_model_name = name
+        end
+
+        def brainstem_model_class
+          @brainstem_model_class ||= self.brainstem_model_name.classify.constantize
+        end
       end
     end
   end
-end
+end

data/lib/brainstem/concerns/formattable.rb

@@ -0,0 +1,38 @@
+require 'brainstem/api_docs'
+require 'active_support/inflector/inflections'
+
+
+module Brainstem
+  module Concerns
+    module Formattable
+      attr_writer :formatters
+
+
+      def valid_options
+        super | [ :formatters ]
+      end
+
+
+      def formatters
+        @formatters ||= ::Brainstem::ApiDocs::FORMATTERS[formatter_type]
+      end
+
+
+      def formatted_as(format, options = {})
+        formatters[format].call(self, options)
+      end
+
+
+      #
+      # Declares the type of formatter that should be used to format an entity
+      # of this class.
+      #
+      def formatter_type
+        self.class.to_s
+          .demodulize
+          .underscore
+          .to_sym
+      end
+    end
+  end
+end

data/lib/brainstem/concerns/inheritable_configuration.rb

@@ -1,10 +1,11 @@
+require 'active_support/concern'
 require 'brainstem/dsl/configuration'
 
 module Brainstem
   module Concerns
     module InheritableConfiguration
       extend ActiveSupport::Concern
-  
+
       module ClassMethods
         def configuration
           @configuration ||= begin
@@ -26,4 +27,4 @@ module Brainstem
       end
     end
   end
-end
+end

data/lib/brainstem/concerns/optional.rb

@@ -0,0 +1,43 @@
+#
+# This module is used in lieu of an dependency on optional kwargs. Any symbol
+# included in the array of +#valid_options+ will be whitelisted from passed
+# options and sent to the instance on initialization.
+#
+# In this simple way, we can make classes accept options, whitelist which
+# are acceptable, and set them without having to manually extend our
+# initializer.
+#
+# In order to use this, your constructor must have an argument named +options+
+# that defaults to an empty hash. Additionally, for each option you define, you
+# should define an accessor or at least a writer.
+#
+# You may also implement a +#valid_options+ method. It is recommended that you
+# make this the union of the superclass's +valid_options+ method and this
+# class's options so that inherited options are preserved:
+#
+# @example
+#     def valid_options
+#       super | [ :your_options_here ]
+#     end
+#
+module Brainstem
+  module Concerns
+    module Optional
+
+      #
+      # The options that should be extracted and sent to the class on
+      # initialization.
+      #
+      # @return [Array<Symbol>] valid options
+      #
+      def valid_options
+        [ ]
+      end
+
+
+      def initialize(options = {})
+        options.slice(*valid_options).each {|k, v| self.send("#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/brainstem/concerns/presenter_dsl.rb

@@ -9,6 +9,8 @@ require 'brainstem/dsl/fields_block'
 require 'brainstem/dsl/associations_block'
 
 
+require 'active_support/core_ext/array/extract_options'
+
 module Brainstem
   module Concerns
     module PresenterDSL
@@ -36,6 +38,18 @@ module Brainstem
           AssociationsBlock.new(configuration, &block)
         end
 
+        def title(str, options = { nodoc: false })
+          configuration[:title] = options.merge(info: str)
+        end
+
+        def description(str, options = { nodoc: false })
+          configuration[:description] = options.merge(info: str)
+        end
+
+        def nodoc!
+          configuration[:nodoc] = true
+        end
+
         # Declare a helper module or block whose methods will be available in dynamic fields and associations.
         def helper(mod = nil, &block)
           if mod
@@ -47,9 +61,14 @@ module Brainstem
           end
         end
 
+
         # @overload default_sort_order(sort_string)
         #   Sets a default sort order.
-        #   @param [String] sort_string The sort order to apply by default while presenting. The string must contain the name of a sort order that has explicitly been declared using {sort_order}. The string may end in +:asc+ or +:desc+ to indicate the default order's direction.
+        #   @param [String] sort_string The sort order to apply by default
+        #     while presenting. The string must contain the name of a sort order
+        #     that has explicitly been declared using {sort_order}. The string
+        #     may end in +:asc+ or +:desc+ to indicate the default order's
+        #     direction.
         #   @return [String] The new default sort order.
         # @overload default_sort_order
         #   @return [String] The default sort order, or nil if one is not set.
@@ -58,31 +77,70 @@ module Brainstem
           configuration[:default_sort_order]
         end
 
-        # @overload sort_order(name, order)
+
+        #
+        # @overload sort_order(name, order, options)
         #   @param [Symbol] name The name of the sort order.
-        #   @param [String] order The SQL string to use to sort the presented data.
-        # @overload sort_order(name, &block)
-        #   @yieldparam scope [ActiveRecord::Relation] The scope representing the data being presented.
-        #   @yieldreturn [ActiveRecord::Relation] A new scope that adds ordering requirements to the scope that was yielded.
-        #   Create a named sort order, either containing a string to use as ORDER in a query, or with a block that adds an order Arel predicate to a scope.
+        #   @param [String] order The SQL string to use to sort the presented
+        #     data.
+        #   @param [Hash] options
+        #   @option options [String] :info Docstring for the sort order
+        #   @option options [Boolean] :nodoc Whether this sort order be
+        #     included in the generated documentation
+        #
+        # @overload sort_order(name, options, &block)
+        #   @yieldparam scope [ActiveRecord::Relation] The scope representing
+        #     the data being presented.
+        #   @yieldreturn [ActiveRecord::Relation] A new scope that adds
+        #     ordering requirements to the scope that was yielded.
+        #
+        #   Create a named sort order, either containing a string to use as
+        #   ORDER in a query, or with a block that adds an order Arel predicate
+        #   to a scope.
+        #
         # @raise [ArgumentError] if neither an order string or block is given.
-        def sort_order(name, order = nil, &block)
+        #
+        def sort_order(name, *args, &block)
+          valid_options = %w(info nodoc)
+          options       = args.extract_options!
+                            .select { |k, v| valid_options.include?(k.to_s) }
+          order         = args.first
+
           raise ArgumentError, "A sort order must be given" unless block_given? || order
-          configuration[:sort_orders][name] = (block_given? ? block : order)
+          configuration[:sort_orders][name] = options.merge({
+            value: (block_given? ? block : order)
+          })
         end
 
+
+        #
         # @overload filter(name, options = {})
-        #   @param [Symbol] name The name of the scope that may be applied as a filter.
-        #   @option options [Object] :default If set, causes this filter to be applied to every request. If the filter accepts parameters, the value given here will be passed to the filter when it is applied.
+        #   @param [Symbol] name The name of the scope that may be applied as a
+        #     filter.
+        #   @option options [Object] :default If set, causes this filter to be
+        #     applied to every request. If the filter accepts parameters, the
+        #     value given here will be passed to the filter when it is applied.
+        #   @option options [String] :info Docstring for the filter.
+        #
         # @overload filter(name, options = {}, &block)
         #   @param [Symbol] name The filter can be requested using this name.
-        #   @yieldparam scope [ActiveRecord::Relation] The scope that the filter should use as a base.
-        #   @yieldparam arg [Object] The argument passed when the filter was requested.
-        #   @yieldreturn [ActiveRecord::Relation] A new scope that filters the scope that was yielded.
+        #   @yieldparam scope [ActiveRecord::Relation] The scope that the
+        #     filter should use as a base.
+        #   @yieldparam arg [Object] The argument passed when the filter was
+        #     requested.
+        #   @yieldreturn [ActiveRecord::Relation] A new scope that filters the
+        #     scope that was yielded.
+        #
         def filter(name, options = {}, &block)
-          configuration[:filters][name] = [options, (block_given? ? block : nil)]
+          valid_options = %w(default info include_params nodoc)
+          options.select! { |k, v| valid_options.include?(k.to_s) }
+
+          configuration[:filters][name] = options.merge({
+            value: (block_given? ? block : nil)
+          })
         end
 
+
         def search(&block)
           configuration[:search] = block
         end
@@ -104,6 +162,9 @@ module Brainstem
           configuration.nest!(:filters)
           configuration.nest!(:sort_orders)
           configuration.nest!(:associations)
+          configuration.nonheritable!(:title)
+          configuration.nonheritable!(:description)
+          configuration.nonheritable!(:nodoc)
         end
       end
     end

data/lib/brainstem/controller_methods.rb

@@ -1,15 +1,18 @@
 require 'brainstem/concerns/controller_param_management'
 require 'brainstem/concerns/error_presentation'
+require 'brainstem/concerns/controller_dsl'
 
 module Brainstem
 
-  # ControllerMethods are intended to be included into controllers that will be handling requests for presented objects.
-  # The present method will pass through +params+, so that any allowed and requested includes, filters, sort orders
-  # will be applied to the presented data.
+  # ControllerMethods are intended to be included into controllers that will be
+  # handling requests for presented objects.  The present method will pass
+  # through +params+, so that any allowed and requested includes, filters, sort
+  # orders will be applied to the presented data.
   module ControllerMethods
     extend ActiveSupport::Concern
     include Concerns::ControllerParamManagement
     include Concerns::ErrorPresentation
+    include Concerns::ControllerDSL
 
     # Return a Ruby hash that contains models requested by the user's params and allowed
     # by the +name+ presenter's configuration.

data/lib/brainstem/dsl/association.rb

@@ -5,15 +5,18 @@ module Brainstem
     class Association
       include Brainstem::Concerns::Lookup
 
-      attr_reader :name, :target_class, :description, :options
+      attr_reader :name, :target_class, :options
 
-      def initialize(name, target_class, description, options)
+      def initialize(name, target_class, options)
         @name = name.to_s
         @target_class = target_class
-        @description = description
         @options = options
       end
 
+      def description
+        options[:info].presence
+      end
+
       def method_name
         if options[:dynamic] || options[:lookup]
           nil

data/lib/brainstem/dsl/associations_block.rb

@@ -2,9 +2,12 @@ module Brainstem
   module Concerns
     module PresenterDSL
       class AssociationsBlock < BaseBlock
-        def association(name, target_class, *args)
-          description, options = parse_args(args)
-          configuration[:associations][name] = DSL::Association.new(name, target_class, description, block_options.merge(options))
+        def association(name, target_class, options = {})
+          configuration[:associations][name] = DSL::Association.new(
+            name,
+            target_class,
+            block_options.merge(format_options(options))
+          )
         end
       end
     end

data/lib/brainstem/dsl/base_block.rb

@@ -20,10 +20,8 @@ module Brainstem
           klass.new(new_config, block_options.merge(new_options), &block)
         end
 
-        def parse_args(args)
-          options = args.last.is_a?(Hash) ? args.pop : {}
-          description = args.shift
-          [description, options]
+        def format_options(options)
+          options.symbolize_keys
         end
       end
     end

data/lib/brainstem/dsl/conditional.rb

@@ -1,13 +1,17 @@
 module Brainstem
   module DSL
     class Conditional
-      attr_reader :name, :type, :action, :description
+      attr_reader :name, :type, :action, :options
 
-      def initialize(name, type, action, description)
+      def initialize(name, type, action, options = {})
         @name = name
         @type = type
         @action = action
-        @description = description
+        @options = options
+      end
+
+      def description
+        options[:info].presence
       end
 
       def matches?(model, helper_instance = Object.new, conditional_cache = { model: {}, request: {} })

data/lib/brainstem/dsl/conditionals_block.rb

@@ -2,12 +2,12 @@ module Brainstem
   module Concerns
     module PresenterDSL
       class ConditionalsBlock < BaseBlock
-        def request(name, action, description = nil)
-          configuration[:conditionals][name] = DSL::Conditional.new(name, :request, action, description)
+        def request(name, action, options = {})
+          configuration[:conditionals][name] = DSL::Conditional.new(name, :request, action, format_options(options))
         end
 
-        def model(name, action, description = nil)
-          configuration[:conditionals][name] = DSL::Conditional.new(name, :model, action, description)
+        def model(name, action, options = {})
+          configuration[:conditionals][name] = DSL::Conditional.new(name, :model, action, format_options(options))
         end
       end
     end

data/lib/brainstem/dsl/configuration.rb

@@ -1,18 +1,38 @@
 require 'active_support/hash_with_indifferent_access'
+require 'forwardable'
 
 # A hash-like object that accepts a parent configuration object that defers to
 # the parent in the absence of one of its own keys (thus simulating inheritance).
 module Brainstem
   module DSL
     class Configuration
+      extend Forwardable
 
       # Returns a new configuration object.
       #
       # @params [Object] parent_configuration The parent configuration object
       #   which the new configuration object should use as a base.
       def initialize(parent_configuration = nil)
-        @parent_configuration = parent_configuration || ActiveSupport::HashWithIndifferentAccess.new
-        @storage = ActiveSupport::HashWithIndifferentAccess.new
+        @parent_configuration  = parent_configuration || ActiveSupport::HashWithIndifferentAccess.new
+        @storage               = ActiveSupport::HashWithIndifferentAccess.new
+
+        #
+        # Nonheritable keys are a bit peculiar: they make the lookup for a key
+        # specified as nonheritable to return no result when it falls back to
+        # the parent configuration.
+        #
+        # These keys themselves are inheritable; in this way, a class that
+        # descends from another will keep the same behaviour as its superclass
+        # without necessarily having the same data. Or to put it another way,
+        # if you have specified that 'title' is not inheritable in a
+        # superclass's configuration, that is a property of that class, and
+        # descendent classes should behave the same way.
+        #
+        # It is also unlikely that subclasses will modify the list of
+        # nonheritable keys.
+        parent_nh_keys = parent_configuration &&
+          parent_configuration.nonheritable_keys
+        @nonheritable_keys = InheritableAppendSet.new(parent_nh_keys)
       end
 
       def [](key)
@@ -40,12 +60,161 @@ module Brainstem
         @storage[key] ||= InheritableAppendSet.new
       end
 
+
+      #
+      # Marks a key in the configuration as nonheritable, which means that the key:
+      #
+      # - will appear in the list of keys for this object;
+      # - will return its value when fetched from this object;
+      # - will be included in the +to_h+ output from this object;
+      # - will be included when iterating with +#each+ from this object;
+      #
+      # - will not appear in the list of keys for any child object;
+      # - will return +nil+ when fetched from any child object;
+      # - will not be included in the +#to_h+ output from any child object;
+      # - will not be included when iterating with +#each+ from any child object.
+      #
+      # @param [Symbol,String] key the key to append to the list of nonheritable
+      #   keys
+      #
+      def nonheritable!(key)
+        key = key.to_s
+        self.nonheritable_keys << key unless self.nonheritable_keys.include?(key)
+      end
+
+
+      attr_accessor :nonheritable_keys
+
+
+      #
+      # Returns the keys in this configuration object that are visible to child
+      # configuration objects (i.e. heritable keys).
+      #
+      # @return [Array] keys
+      #
+      def keys_visible_to_children
+        keys - nonheritable_keys.to_a
+      end
+
+
+      #
+      # Returns a hash of this object's storage, less those pairs that are
+      # not visible to children.
+      #
+      # @return [Hash] the hash, less nonheritable pairs.
+      #
+      def pairs_visible_to_children
+        to_h.select {|k, v| keys_visible_to_children.include?(k.to_s) }
+      end
+
+
+      #
+      # Returns the union of all keys in this configuration plus those that are
+      # heritable in the parent.
+      #
+      # @return [Array] keys
+      #
       def keys
-        @parent_configuration.keys | @storage.keys
+        if @parent_configuration.respond_to?(:keys_visible_to_children)
+          @parent_configuration.keys_visible_to_children | @storage.keys
+        else
+          @parent_configuration.keys | @storage.keys
+        end
+      end
+
+
+      #
+      # Returns a list of nonheritable keys for the parent configuration, if
+      # the parent configuration actually keeps track of it. Otherwise returns
+      # an empty array.
+      #
+      # @return [Array<String>] the list of nonheritable keys in the
+      #   parent configuration.
+      #
+      def parent_nonheritable_keys
+        if @parent_configuration.respond_to?(:nonheritable_keys)
+          @parent_configuration.nonheritable_keys
+        else
+          []
+        end
+      end
+
+
+      #
+      # Returns whether a key is nonheritable in this configuration object's
+      # parent configuration.
+      #
+      # Is of arity -1 so it can be easily passed to methods that yield
+      # either a key, or a key/value tuple.
+      #
+      # @param [Symbol,String] key the key to check for nonheritability.
+      #
+      def key_nonheritable_in_parent?(*key)
+        parent_nonheritable_keys.include?(key.first.to_s)
+      end
+
+
+      #
+      # An inversion of +key_nonheritable_in_parent+. Returns true if the
+      # key is not marked as nonheritable in the parent configuration.
+      #
+      # Is of arity -1 so it can be easily passed to methods that yield
+      # either a key, or a key/value tuple.
+      #
+      # @param [Symbol,String] key the key to check for heritability.
+      #
+      def key_inheritable_in_parent?(*key)
+        !key_nonheritable_in_parent?(key.first.to_s)
+      end
+
+
+      #
+      # Returns a hash of this object's storage merged over the heritable pairs
+      # of its parent configurations.
+      #
+      # @return [Hash] the merged hash
+      #
+      def to_h
+        if @parent_configuration.respond_to?(:pairs_visible_to_children)
+          @parent_configuration.pairs_visible_to_children.merge(@storage)
+        else
+          @parent_configuration.to_h.merge(@storage)
+        end
+      end
+
+
+      #
+      # Returns the value for the given key, or if it could not be found:
+      #   - Raises a +KeyError+ if not passed a default or a block;
+      #   - Returns the default if it is passed a default but no block;
+      #   - Calls and returns the block if passed a block but no default;
+      #   - Calls the block with the default and returns the block if passed a
+      #       default and a block.
+      #
+      # @params [Symbol,String] key the key to look up
+      # @params [Object] default the default to return
+      # @params [Proc] block the block to call
+      #
+      # @see http://ruby-doc.org/core-2.2.1/Hash.html#method-i-fetch
+      #
+      def fetch(key, default = nil, &block)
+        val = get!(key)
+        return val if val
+
+        if default && !block_given?
+          default
+        elsif block_given?
+          default ? block.call(default) : block.call
+        else
+          raise KeyError
+        end
       end
 
+
       def has_key?(key)
-        @storage.has_key?(key) || @parent_configuration.has_key?(key)
+        @storage.has_key?(key) ||
+          (@parent_configuration.has_key?(key) &&
+           key_inheritable_in_parent?(key))
       end
 
       def length
@@ -58,7 +227,7 @@ module Brainstem
         end
       end
 
-      delegate :empty?, to: :keys
+      delegate :empty? => :keys
 
       private
 
@@ -67,14 +236,19 @@ module Brainstem
       # Retrieves the value stored at key.
       #
       # - If +key+ is already defined, it returns that;
+      # - If +key+ in the parent is marked as nonheritable, it returns
+      #   +nil+;
       # - If +key+ in the parent is a +Configuration+, returns a new
       #   +Configuration+ with the parent set;
       # - If +key+ in the parent is an +InheritableAppendSet+, returns a new
       #   +InheritableAppendSet+ with the parent set;
       # - Elsewise returns the parent configuration's value for the key.
+      #
       def get!(key)
         @storage[key] || begin
-          if @parent_configuration[key].is_a?(Configuration)
+          if key_nonheritable_in_parent?(key)
+            nil
+          elsif @parent_configuration[key].is_a?(Configuration)
             @storage[key] = Configuration.new(@parent_configuration[key])
           elsif @parent_configuration[key].is_a?(InheritableAppendSet)
             @storage[key] = InheritableAppendSet.new(@parent_configuration[key])
@@ -87,6 +261,8 @@ module Brainstem
       # An Array-like object that provides `push`, `concat`, `each`, `empty?`, and `to_a` methods that act the combination
       # of its own entries and those of a parent InheritableAppendSet, if present.
       class InheritableAppendSet
+        extend Forwardable
+
         def initialize(parent_array = nil)
           @parent_array = parent_array || []
           @storage = []
@@ -105,8 +281,8 @@ module Brainstem
           @parent_array.to_a + @storage
         end
 
-        delegate :each, :empty?, to: :to_a
+        delegate [:each, :empty?, :include?] => :to_a
       end
     end
   end
-end
+end