brainstem 1.0.0.pre.1 → 1.0.0

data/lib/brainstem/api_docs/presenter_collection.rb

@@ -0,0 +1,97 @@
+require 'active_support/inflector/inflections'
+require 'brainstem/api_docs/abstract_collection'
+require 'brainstem/api_docs/presenter'
+require 'brainstem/concerns/formattable'
+
+module Brainstem
+  module ApiDocs
+    class PresenterCollection < AbstractCollection
+      include Concerns::Formattable
+
+
+      def valid_options
+        super | [ :presenter_constant_lookup_method ]
+      end
+
+      attr_writer :presenter_constant_lookup_method
+
+
+      #
+      # Finds or creates a presenter with the given target class and appends it to the
+      # members list if it is new.
+      #
+      def find_or_create_from_target_class(target_class)
+        find_by_target_class(target_class) ||
+          create_from_target_class(target_class)
+      end
+      alias_method :find_or_create_by_target_class,
+                     :find_or_create_from_target_class
+
+
+      #
+      # Finds a presenter for the given class
+      #
+      def find_by_target_class(target_class)
+        find { |p| p.target_class == target_class }
+      end
+
+
+      #
+      # Creates a new +Presenter+ wrapper and appends it to the collection. If
+      # the constant lookup for the actual presenter class fails, returns nil.
+      #
+      def create_from_target_class(target_class)
+        ::Brainstem::ApiDocs::Presenter.new(atlas,
+          target_class: target_class,
+          const:        target_class_to_const(target_class)
+        ).tap { |p| self.<< p }
+      rescue KeyError
+        nil
+      end
+
+
+      def find_or_create_from_presenter_collection(target_class, const)
+          find_by_target_class(target_class) ||
+            create_from_presenter_collection(target_class, const)
+      end
+      alias_method :find_or_create_by_presenter_collection,
+                     :find_or_create_from_presenter_collection
+
+
+      def create_from_presenter_collection(target_class, const)
+        ::Brainstem::ApiDocs::Presenter.new(atlas,
+          target_class: target_class,
+          const:        const
+        ).tap { |p| self.<< p }
+      end
+
+
+      #########################################################################
+      private
+      #########################################################################
+
+      #
+      # Converts a target class into a presenter constant. Raises an error
+      # if not found.
+      #
+      def target_class_to_const(target_class)
+        presenter_constant_lookup_method.call(target_class.to_s)
+      end
+
+
+      #
+      # A callable method by which presenter constants can be looked up from
+      # their human name.
+      #
+      # In future, it might be worth unifying this method with `find_by_class`
+      # to reduce total surface.
+      #
+      def presenter_constant_lookup_method
+        @presenter_constant_lookup_method ||= \
+          Brainstem.presenter_collection.presenters.method(:fetch)
+      end
+
+
+    end
+  end
+end

data/lib/brainstem/api_docs/resolver.rb

@@ -0,0 +1,73 @@
+require 'brainstem/concerns/optional'
+
+#
+# The Resolver is responsible for taking a non-ApiDocs class and turning it
+# into an ApiDocs wrapper class (such as a Presenter, Controller, or Endpoint).
+#
+# It's useful for doing object lookups for associated objects where we only
+# have the original class or constant to look up the relationship.
+#
+module Brainstem
+  module ApiDocs
+    class Resolver
+      include Brainstem::Concerns::Optional
+
+
+      def valid_options
+        [
+          :presenter_constant_lookup_method,
+        ]
+      end
+
+      def initialize(atlas, options = {})
+        self.atlas = atlas
+        super options
+      end
+
+
+      attr_accessor :atlas,
+                    :presenter_constant_lookup_method
+
+
+      def find_by_class(klass)
+        if klass == :polymorphic
+          nil
+        elsif klass < ActiveRecord::Base
+          find_presenter_from_target_class(klass)
+        end
+      end
+
+
+      #########################################################################
+      private
+      #########################################################################
+
+      def find_presenter_from_target_class(klass)
+        const = presenter_target_class_to_const(klass)
+        atlas.presenters.find {|p| p.const == const }
+      rescue
+        nil
+      end
+
+
+      #
+      # Converts a class into a presenter constant. Raises an error
+      # if not found.
+      #
+      def presenter_target_class_to_const(target_class)
+        presenter_constant_lookup_method.call(target_class.to_s)
+      end
+
+
+      #
+      # A callable method by which presenter constants can be looked up from
+      # their human name.
+      #
+      def presenter_constant_lookup_method
+        @presenter_constant_lookup_method ||= \
+          Brainstem.presenter_collection.presenters.method(:fetch)
+      end
+    end
+  end
+end
+

data/lib/brainstem/api_docs/sinks/abstract_sink.rb

@@ -0,0 +1,37 @@
+require 'brainstem/concerns/optional'
+
+module Brainstem
+  module ApiDocs
+    module Sinks
+      class AbstractSink
+        include Concerns::Optional
+
+
+        #
+        # Primary method for putting the atlas into the sink.
+        #
+        # @param [Brainstem::ApiDocs::Atlas] the atlas
+        #
+        def <<(atlas)
+          raise NotImplementedError
+        end
+
+
+        #######################################################################$
+        private
+        ########################################################################
+
+
+        #
+        # Whitelist of options which can be set on an instance.
+        #
+        # @return [Array<Symbol>] valid options
+        #
+        def valid_options
+          []
+        end
+
+      end
+    end
+  end
+end

data/lib/brainstem/api_docs/sinks/controller_presenter_multifile_sink.rb

@@ -0,0 +1,93 @@
+require 'brainstem/api_docs/sinks/abstract_sink'
+require 'fileutils'
+require 'forwardable'
+
+module Brainstem
+  module ApiDocs
+    module Sinks
+      class ControllerPresenterMultifileSink < AbstractSink
+        extend Forwardable
+
+        delegate [:controllers, :presenters] => :atlas
+
+
+        def <<(atlas)
+          self.atlas = atlas
+
+          write_controller_files
+          write_presenter_files
+        end
+
+
+        def valid_options
+          super | [ :write_method, :format, :write_path ]
+        end
+
+
+        attr_writer     :write_method,
+                        :write_path
+
+        attr_accessor   :atlas,
+                        :format
+
+
+        #######################################################################
+        private
+        #######################################################################
+
+        #
+        # Dumps each formatted controller to a file.
+        #
+        def write_controller_files
+          controllers.each_formatted_with_filename(
+            format,
+            include_actions: true,
+            &method(:write_buffer_to_file)
+          )
+        end
+
+
+        #
+        # Dumps each formatted presenter to a file.
+        #
+        def write_presenter_files
+          presenters.each_formatted_with_filename(format, &method(:write_buffer_to_file))
+        end
+
+
+        #
+        # Writes a given bufer to a filename within the base path.
+        #
+        def write_buffer_to_file(buffer, filename)
+          abs_path = File.join(write_path, filename)
+          assert_directory_exists!(abs_path)
+          write_method.call(abs_path, buffer)
+        end
+
+
+        #
+        # Asserts that a directory exists, creating it if it does not.
+        #
+        def assert_directory_exists!(path)
+          dir = File.dirname(path)
+          FileUtils.mkdir_p(dir) unless File.directory?(dir)
+        end
+
+
+        #
+        # Defines how we write out the files.
+        #
+        def write_method
+          @write_method ||= Proc.new do |name, buff|
+            File.write(name, buff, mode: 'w')
+          end
+        end
+
+
+        def write_path
+          @write_path ||= ::Brainstem::ApiDocs.write_path
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/api_docs/sinks/stdout_sink.rb

@@ -0,0 +1,44 @@
+require 'brainstem/api_docs/sinks/abstract_sink'
+
+module Brainstem
+  module ApiDocs
+    module Sinks
+      class StdoutSink < AbstractSink
+
+        #
+        # Writes the output using stdout.puts.
+        #
+        def <<(output)
+          puts_method.call(output)
+        end
+
+
+        ########################################################################
+        private
+        ########################################################################
+
+
+        def valid_options
+          super | [ :puts_method ]
+        end
+
+
+        #
+        # Storage for holding the writing method.
+        #
+        attr_writer :puts_method
+
+
+        #
+        # Callable method for writing data to a buffer (by default stdout).
+        #
+        # @return [Proc] a method which writes data to a buffer when called.
+        #
+        def puts_method
+          @puts_method ||= $stdout.method(:puts)
+        end
+
+      end
+    end
+  end
+end

data/lib/brainstem/cli.rb

@@ -0,0 +1,146 @@
+# Require all CLI commands.
+Dir.glob(File.expand_path('../cli/**/*.rb', __FILE__)).each { |f| require f }
+require 'brainstem/concerns/optional'
+
+
+#
+# General manager for CLI requests. Takes incoming user input and routes to a
+# subcommand.
+module Brainstem
+  class Cli
+    include Concerns::Optional
+
+    EXECUTABLE_NAME = 'brainstem'
+
+    #
+    # Convenience for instantiating and calling the Cli object.
+    #
+    # @return [Brainstem::Cli] the created instance
+    #
+    def self.call(args, options = {})
+      new(args, options).call
+    end
+
+
+    #
+    # Creates a new instance of the Cli to respond to user input.
+    #
+    # Input is expected to be the name of the subcommand, followed by any
+    # additional arguments.
+    #
+    def initialize(args, options = {})
+      super options
+
+      self._args              = args.dup.freeze
+      self.requested_command  = args.shift
+    end
+
+
+    #
+    # Routes to an application endpoint depending on given options.
+    #
+    # @return [Brainstem::Cli] the instance
+    #
+    def call
+      if requested_command && commands.has_key?(requested_command)
+        self.command_method = commands[requested_command].method(:call)
+      end
+
+      command_method.call(_args.drop(1))
+
+      self
+    end
+
+
+    #
+    # Holds a copy of the initial given args for debugging purposes.
+    #
+    attr_accessor :_args
+
+
+    #
+    # Storage for the extracted command.
+    #
+    attr_accessor :requested_command
+
+
+    ################################################################################
+    private
+    ################################################################################
+
+
+    #
+    # A whitelist of valid options that can be applied to the instance.
+    #
+    # @returns [Array<String>]
+    #
+    def valid_options
+      super | [
+        :log_method
+      ]
+    end
+
+
+    #
+    # A basic routing table where the keys are the command to invoke, and where
+    # the value is a callable object or class that will be called with the
+    # +command_options+.
+    #
+    # @return [Hash] A hash of +'command' => Callable+
+    #
+    def commands
+      { 'generate' => Brainstem::CLI::GenerateApiDocsCommand }
+    end
+
+
+    #
+    # Retrieves the help text and subs any placeholder values.
+    #
+    def help_text
+      @help_text ||= File.read(File.expand_path('../help_text.txt', __FILE__))
+        .gsub('EXECUTABLE_NAME', EXECUTABLE_NAME)
+    end
+
+
+    #
+    # Stores the method we should call to run the user command.
+    #
+    attr_writer :command_method
+
+
+    #
+    # Reader for the method to invoke. By default, will output the help text
+    # when called.
+    #
+    # @return [Proc] An object responding to +#call+ that is used as the main
+    # point execution.
+    #
+    def command_method
+      @command_method ||= Proc.new do
+        # By default, serve help.
+        log_method.call(help_text)
+      end
+    end
+
+
+    #
+    # Stores the method we should use to log messages.
+    #
+    attr_writer :log_method
+
+
+    #
+    # Reader for the method to log. By default, will print to stdout when
+    # called.
+    #
+    # We return a proc here because it's much tricker to make assertions
+    # against stdout than it is to allow ourselves to inject a proc.
+    #
+    # @return [Proc] An object responding to +#call+ that is used to print
+    # information.
+    #
+    def log_method
+      @log_method ||= $stdout.method(:puts)
+    end
+  end
+end