brainstem 1.0.0.pre.1 → 1.0.0

data/lib/brainstem/api_docs/abstract_collection.rb

@@ -0,0 +1,116 @@
+require 'forwardable'
+require 'brainstem/concerns/optional'
+require 'brainstem/concerns/formattable'
+
+module Brainstem
+  module ApiDocs
+    class AbstractCollection
+      include Enumerable
+      extend Forwardable
+      include Concerns::Optional
+      include Concerns::Formattable
+
+      #
+      # Creates a new collection with all passed members. Very handy for
+      # reduce operations which should return a subset of members but retain
+      # the same utility.
+      #
+      def self.with_members(atlas, *members)
+        new(atlas).tap {|n| members.flatten.each { |m| n << m } }
+      end
+
+
+      def initialize(atlas, options = {})
+        self.atlas   = atlas
+        self.members = []
+        super options
+      end
+
+
+      attr_accessor :atlas
+
+      delegate :find_by_class => :atlas
+
+
+      #
+      # Handy accessor for extracting the last member of the collection.
+      #
+      def last
+        members[-1]
+      end
+
+
+      #
+      # Appends a pre-existing object to the collection.
+      #
+      def <<(*objects)
+        members.push(*objects.flatten)
+      end
+
+
+      #
+      # Iterates over each controller in the collection.
+      #
+      def each(&block)
+        members.each(&block)
+      end
+
+
+      #
+      # Returns a map of each member formatted as specified.
+      #
+      def formatted(format, options = {})
+        map { |member| member.formatted_as(format, options) }
+          .reject(&:empty?)
+      end
+
+
+      #
+      # Returns a list of each member's filename.
+      #
+      # We internally refer to `formatted_with_filename` here because we don't
+      # want to include any filenames of empty files (i.e. nodoc).
+      #
+      def filenames(format)
+        formatted_with_filename(format).map { |arr| arr[1] }
+      end
+
+
+      #
+      # Returns a map of each formatted member and its suggested filename.
+      #
+      def formatted_with_filename(format, options = {})
+        map { |member| [
+          member.formatted_as(format, options),
+          member.suggested_filename(format)
+        ] }
+          .reject { |(buffer, _)| buffer.empty? }
+      end
+
+
+      def each_formatted_with_filename(format, options = {}, &block)
+        formatted_with_filename(format, options)
+          .each { |args| block.call(*args) }
+      end
+
+
+      def each_formatted(format, options = {}, &block)
+        formatted(format, options)
+          .each { |args| block.call(*args) }
+      end
+
+
+      def each_filename(format, &block)
+        filenames(format).each { |args| block.call(*args) }
+      end
+
+
+
+      #########################################################################
+      protected
+      #########################################################################
+
+      attr_accessor :members
+    end
+  end
+end

data/lib/brainstem/api_docs/atlas.rb

@@ -0,0 +1,158 @@
+require 'forwardable'
+require 'brainstem/api_docs/resolver'
+require 'brainstem/api_docs/exceptions'
+require 'brainstem/api_docs/endpoint_collection'
+require 'brainstem/api_docs/controller_collection'
+require 'brainstem/api_docs/presenter_collection'
+require 'brainstem/concerns/optional'
+
+#
+#
+# The Atlas is an object that makes the information from an introspector
+# available in formatted and raw format.
+#
+module Brainstem
+  module ApiDocs
+    class Atlas
+      extend Forwardable
+      include Concerns::Optional
+
+
+      def initialize(introspector, options = {})
+        self.endpoints          = EndpointCollection.new(self)
+        self.controllers        = ControllerCollection.new(self)
+        self.presenters         = ::Brainstem::ApiDocs::PresenterCollection.new(self)
+        self.resolver           = Resolver.new(self)
+
+        self.controller_matches = []
+        self.introspector       = introspector
+
+        super options
+
+        parse_routes!
+        extract_presenters!
+        validate!
+      end
+
+
+      attr_accessor :endpoints,
+                    :controllers,
+                    :presenters,
+                    :resolver
+
+
+      delegate :find_by_class => :resolver
+
+
+      #########################################################################
+      private
+      #########################################################################
+
+
+      #
+      # Lists valid options that may be passed on instantiation.
+      #
+      def valid_options
+        super | [ :controller_matches ]
+      end
+
+
+      #
+      # Ensures the atlas is valid before allowing consumers to make requests
+      # of it.
+      #
+      def validate!
+        raise InvalidAtlasError, "Atlas is not valid." unless valid?
+      end
+
+
+      #
+      # Set and read the introspector.
+      #
+      attr_accessor :introspector
+
+
+      #
+      # Holds +Regexp+s which each controller name must match in order to be
+      # included in the list of endpoints.
+      #
+      attr_accessor :controller_matches
+
+
+      #
+      # Returns a list of all routes that pass the user's filtering.
+      #
+      def allowed_routes
+        introspector.routes.keep_if(&method(:allow_route?))
+      end
+
+
+      #
+      # Constructs +Endpoint+ and +Controller wrappers per route.
+      #
+      def parse_routes!
+        allowed_routes.each do |route|
+          if (endpoint = endpoints.find_from_route(route))
+            endpoint.merge_http_methods!(route[:http_methods])
+          else
+            controller  = controllers.find_or_create_from_route(route)
+            endpoint    = endpoints.create_from_route(route, controller)
+
+            controller.add_endpoint(endpoint)
+          end
+        end
+      end
+
+
+      #
+      # Extracts declared presents for each endpoint and converts it into a
+      # Presenter wrapper object.
+      #
+      def extract_presenters!
+        valid_presenter_pairs.each do |target_class, const|
+          presenter = presenters.find_or_create_from_presenter_collection(target_class, const)
+
+          endpoints
+            .select do |ep|
+              declared_presented_class = ep.declared_presented_class
+              !declared_presented_class.nil? && declared_presented_class.to_s == target_class
+            end
+              .each {|ep| ep.presenter = presenter }
+        end
+      end
+
+
+      #
+      # Returns a list of valid +target_class_to_s => PresenterConst+ pairs,
+      # determining validity by whether they descend from the base presenter.
+      #
+      # @return [Hash{String => Class}] valid pairs
+      #
+      def valid_presenter_pairs
+        Brainstem.presenter_collection.presenters.select do |target_class, const|
+          introspector.presenters.include? const
+        end
+      end
+
+
+      #
+      # Whether this Atlas is valid (i.e. if it has at least one endpoint).
+      #
+      # @return [Boolean] if the atlas is valid
+      #
+      def valid?
+        endpoints.count > 0
+      end
+
+
+      #
+      # Returns whether a route's controller passes the limiting regexp passed to the
+      # generation command.
+      #
+      def allow_route?(route)
+        introspector.controllers.include?(route[:controller]) &&
+          controller_matches.all? { |regexp| route[:controller].to_s =~ regexp }
+      end
+    end
+  end
+end

data/lib/brainstem/api_docs/builder.rb

@@ -0,0 +1,167 @@
+require 'brainstem/api_docs/introspectors/rails_introspector'
+require 'brainstem/concerns/optional'
+require 'brainstem/api_docs/atlas'
+require 'active_support/core_ext/hash/slice'
+
+#
+# This class describes the main API surface for generating API documentation.
+# The command-line utility provided with Brainstem is basically just a thin
+# veneer over top of this class.
+#
+# You can use this to programmatically generate the API docs, or to browse them
+# while inside a REPL.
+#
+module Brainstem
+  module ApiDocs
+    class Builder
+      include Brainstem::Concerns::Optional
+
+
+      def valid_options
+        [
+          :introspector_method,
+          :atlas_method,
+
+          :args_for_introspector,
+          :args_for_atlas
+        ]
+      end
+
+
+      #
+      # @param [Hash] options
+      # @option options [Proc] :introspector_method Proc of arity one that
+      #   returns an Introspector (an object that introspects into
+      #   the host application, seeking its routes, controllers, and
+      #   presenters).
+      # @option options [Hash] :args_for_introspector Additional arguments to
+      #   be passed to the introspector on creation.
+      # @option options [Hash] :args_for_atlas Additional arguments to be passed
+      #   to the atlas on creation.
+      # @option options [Proc,Object] :introspector_method A method that
+      #   returns an introspector when called.
+      # @option options [Proc,Object] :atlas_method A method that returns an Atlas-like
+      #   object when called.
+      #
+      # @see Brainstem::ApiDocs::Introspectors::AbstractIntrospector
+      # @see Brainstem::ApiDocs::Introspectors::RailsIntrospector
+      #
+      def initialize(options = {})
+        super
+
+        build_introspector!
+        build_atlas!
+      end
+
+
+      #
+      # Builds an introspector.
+      #
+      def build_introspector!
+        self.introspector = introspector_method.call(args_for_introspector)
+      end
+
+
+      #
+      # Builds an atlas.
+      #
+      def build_atlas!
+        self.atlas = atlas_method.call(introspector, args_for_atlas)
+      end
+
+
+      #
+      # Arguments to be passed to the introspector on creation.
+      #
+      # @see Brainstem::ApiDocs::Introspectors::AbstractIntrospector
+      # @see Brainstem::ApiDocs::Introspectors::RailsIntrospector
+      #
+      def args_for_introspector
+        @args_for_introspector ||= {}
+      end
+
+
+      #
+      # Allows passing args to the introspector if - for example - you are
+      # using a custom base controller class.
+      #
+      attr_writer :args_for_introspector
+
+
+      #
+      # Arguments to be passed to the atlas on creation.
+      #
+      # @see Brainstem::ApiDocs::Atlas
+      #
+      def args_for_atlas
+        @args_for_atlas ||= {}
+      end
+
+
+      #
+      # Allows passing args to the atlas if - for example - you are
+      # specifying match terms for the allowable controller set.
+      #
+      attr_writer :args_for_atlas
+
+
+      #
+      # A method which returns the introspector which extracts information
+      # about the Brainstem-powered API from the host application.
+      #
+      # Stored as a proc because it's impossible to inject an instantiated
+      # object and have it receive args from this class. This is less important
+      # in this specific circumstance but is kept for uniformity with
+      # +atlas_method+.
+      #
+      # @return [Proc] a proc of arity 1 which takes an options hash and
+      #   returns an introspector
+      #
+      def introspector_method
+        @introspector_method ||=
+          Introspectors::RailsIntrospector.method(:with_loaded_environment)
+      end
+
+
+      #
+      # Allows setting the introspector_method if - for example - you are using
+      # Brainstem on a Sinatra app and you need to customize how lookups for
+      # presenters, controllers, and routes are performed.
+      #
+      attr_writer :introspector_method
+
+
+      #
+      # Holds a reference to the constructed introspector.
+      #
+      attr_accessor :introspector
+
+
+      #
+      # A proc of arity 1..2 which takes an introspector and optional options,
+      # and which returns a new Atlas.
+      #
+      # Passed an introspector.
+      #
+      # @return [Proc] a method to return an atlas
+      #
+      def atlas_method
+        @atlas_method ||= Atlas.method(:new)
+      end
+
+
+      #
+      # Allows setting the introspector_method if - for example - you are using
+      # an alternative formatter and the requisite information is not present
+      # in the +Endpoint+ objects.
+      #
+      attr_writer :atlas_method
+
+
+      #
+      # Holds a reference to the constructed atlas.
+      #
+      attr_accessor :atlas
+    end
+  end
+end

data/lib/brainstem/api_docs/controller.rb

@@ -0,0 +1,122 @@
+require 'brainstem/concerns/optional'
+require 'brainstem/concerns/formattable'
+require 'active_support/inflector'
+require 'brainstem/api_docs/endpoint_collection'
+require 'forwardable'
+
+module Brainstem
+  module ApiDocs
+    class Controller
+      extend Forwardable
+      include Concerns::Optional
+      include Concerns::Formattable
+
+
+      def initialize(atlas, options = {})
+        self.atlas     = atlas
+        self.endpoints = EndpointCollection.new(atlas)
+        super options
+        yield self if block_given?
+      end
+
+
+      attr_accessor :const,
+                    :name,
+                    :endpoints,
+                    :filename_pattern,
+                    :atlas
+
+
+      attr_writer   :filename_pattern,
+                    :filename_link_pattern
+
+
+      def valid_options
+        super | [
+          :const,
+          :name,
+          :formatters,
+          :filename_pattern,
+          :filename_link_pattern
+        ]
+      end
+
+
+      #
+      # Adds an existing endpoint to its endpoint collection.
+      #
+      def add_endpoint(endpoint)
+        self.endpoints << endpoint
+      end
+
+
+      def suggested_filename(format)
+        filename_pattern
+          .gsub('{{namespace}}', const.to_s.deconstantize.underscore)
+          .gsub('{{name}}', name.to_s.split("/").last)
+          .gsub('{{extension}}', extension)
+      end
+
+
+      def suggested_filename_link(format)
+        filename_link_pattern
+          .gsub('{{name}}', name.to_s)
+          .gsub('{{extension}}', extension)
+      end
+
+
+      def extension
+        @extension ||= Brainstem::ApiDocs.output_extension
+      end
+
+
+      def filename_pattern
+        @filename_pattern ||= Brainstem::ApiDocs.controller_filename_pattern
+      end
+
+
+      def filename_link_pattern
+        @filename_link_pattern ||= Brainstem::ApiDocs.controller_filename_link_pattern
+      end
+
+
+      delegate :configuration => :const
+      delegate :find_by_class => :atlas
+
+
+      def default_configuration
+        configuration[:_default]
+      end
+
+
+      def nodoc?
+        default_configuration[:nodoc]
+      end
+
+
+      def title
+        contextual_documentation(:title) || const.to_s.demodulize
+      end
+
+
+      def description
+        contextual_documentation(:description) || ""
+      end
+
+
+      #
+      # Returns a key if it exists and is documentable.
+      #
+      def contextual_documentation(key)
+        default_configuration.has_key?(key) &&
+          !default_configuration[key][:nodoc] &&
+          default_configuration[key][:info]
+      end
+
+
+      def valid_sorted_endpoints
+        endpoints.sorted_with_actions_in_controller(const)
+      end
+    end
+  end
+end