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:
-
Entity
Turns a single data entity into its formatted version. For example, if formatting a Post object, call this formatter a +<Format>PostFormatter+.
-
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+.
-
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
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
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
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
@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
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
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
@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 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