module Brainstem

The Brainstem module itself contains a default_namespace class attribute and a few helpers that make managing PresenterCollections and their corresponding namespaces easier.

The Atlas is an object that makes the information from an introspector available in formatted and raw format.

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.

Per-endpoint holder for presenter and controller information.

A formatter is fundamentally just a function that, when +#call+ed, accepts an atlas and returns the whole or portion of its data in a readable format.

There are (informally) several types of formatters, and you should select among them appropriately when developing your own:

  1. Entity

    Turns a single data entity into its formatted version. For example, if
    formatting a Post object, call this formatter a
    +<Format>PostFormatter+.
  2. Collection

    Turns a collection of formatted data entities into a single unit.
    Usually this will involve concatenating and/or rejecting inappropriate
    output. For example, if you have a collection of Markdown strings from
    the MarkdownPostFormatter, you might want to generate the whole section
    of documentation by using a +MarkdownPostCollectionFormatter+.
  3. Aggregate

    A combination of entity and collection formatters. Knows how to turn a
    collection of unformatted entities into a single formatted document.
    Not as composable as the two used seperately, but far simpler. This
    should be named +MarkdownAggregatePostFormatter+.

At the time of writing, there is no actual requirement to use these naming conventions, but it is highly recommended for clarity of purpose.

Responsible for formatting each endpoint.

Responsible for formatting each endpoint.

This is a very simple DSL that makes generating a markdown document a bit easier.

Responsible for formatting each endpoint.

Responsible for formatting a response for an endpoint.

Responsible for formatting each endpoint.

Responsible for formatting each endpoint.

Wrapper for common presenter information lookups.

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.

General manager for CLI requests. Takes incoming user input and routes to a subcommand.

A Command is a callable object that acts as an entrypoint into the application logic. It is responsible for translating given options into specific enquiries.

Internally, it wraps an OptionParser instance returned through its +option_parser` method. The evaluation of this parser mutates the options hash. This is available to the call method on the instance, which is the primary point of application logic execution.

The GenerateApiDocsCommand is responsible for the construction and intermediation of the two primary components of automatic API doc generation.

It instantiates both a Builder, which is responsible for introspecting and validation of the host application, and also passes the Builder-generated data structure to the Sink, which is responsible for serializing the data structure to some store (likely transforming the data along the way).

Provide `brainstem_model_name` and `brainstem_plural_model_name` in controllers for use when accessing the `params` hash.

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

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).

Brainstem::PresenterValidator is a helper class that performs validity checks on a given presenter class.

Constants

VERSION

Public Class Methods

add_presenter_class(presenter_class, namespace, *klasses) click to toggle source

Helper method to quickly add presenter classes that are in a namespace. For example, +add_presenter_class(Api::V1::UserPresenter, “User”)+ would add UserPresenter to the PresenterCollection for the :v1 namespace as the presenter for the User class. @param [Brainstem::Presenter] presenter_class The presenter class that is being registered. @param [Array<String, Class>] klasses Classes that will be presented by the given presenter.

# File lib/brainstem.rb, line 50
def self.add_presenter_class(presenter_class, namespace, *klasses)
  presenter_collection(namespace).add_presenter_class(presenter_class, *klasses)
end
default_namespace() click to toggle source

The namespace that will be used by {presenter_collection} and {add_presenter_class} if none is given or implied. @return [String] the default namespace

# File lib/brainstem.rb, line 20
def self.default_namespace
  @default_namespace || "none"
end
default_namespace=(namespace) click to toggle source

Sets {default_namespace} to a new value. @param [String] namespace @return [String] the new default namespace

# File lib/brainstem.rb, line 14
def self.default_namespace=(namespace)
  @default_namespace = namespace
end
logger() click to toggle source

@return [Logger] The Brainstem logger. If Rails is loaded, defaults to the Rails logger. If Rails is not loaded, defaults to a STDOUT logger.

# File lib/brainstem.rb, line 55
def self.logger
  @logger ||= begin
    if defined?(Rails)
      Rails.logger
    else
      require "logger"
      Logger.new(STDOUT)
    end
  end
end
logger=(logger) click to toggle source

Sets a new Brainstem logger. @param [Logger] logger A new Brainstem logger. @return [Logger] The new Brainstem logger.

# File lib/brainstem.rb, line 69
def self.logger=(logger)
  @logger = logger
end
mysql_use_calc_found_rows() click to toggle source

Whether or not to use MYSQL_CALC_FOUND_ROWS to calculate the result set count instead of issuing two queries. @return [Boolean] the mysql_use_calc_found_rows setting

# File lib/brainstem.rb, line 33
def self.mysql_use_calc_found_rows
  @mysql_use_calc_found_rows || false
end
mysql_use_calc_found_rows=(bool) click to toggle source

Sets {mysql_use_calc_found_rows} to a new value. @param [Boolean] bool @return [Boolean] the new mysql_use_calc_found_rows setting

# File lib/brainstem.rb, line 27
def self.mysql_use_calc_found_rows=(bool)
  @mysql_use_calc_found_rows = bool
end
presenter_collection(namespace = nil) click to toggle source

@param [String] namespace @return [PresenterCollection] the {PresenterCollection} for the given namespace.

# File lib/brainstem.rb, line 39
def self.presenter_collection(namespace = nil)
  namespace ||= default_namespace
  @presenter_collection ||= {}
  @presenter_collection[namespace.to_s.downcase] ||= PresenterCollection.new
end
reset!() click to toggle source

Reset all PresenterCollection's Presenters, clear the known collections, and reset the default namespace. This is mostly intended for resetting between tests.

# File lib/brainstem.rb, line 75
def self.reset!
  if @presenter_collection
    @presenter_collection.each do |namespace, collection|
      collection.presenters.each do |klass, presenter|
        presenter.reset! if presenter.respond_to?(:reset!)
      end
    end
  end

  Brainstem::Presenter.reset!
  Brainstem::Presenter.reset_configuration!

  @presenter_collection = {}
  @default_namespace = nil
  @mysql_use_calc_found_rows = false
end