Class | YARD::Server::Commands::Base
In: | lib/yard/server/commands/base.rb
Parent: | Object

This is the base command class used to implement custom commands for a server. A command will be routed to by the {Router} class and return a Rack-style response.

## Attribute Initializers

All attributes can be initialized via options passed into the {initialize} method. When creating a custom command, the {Adapter#options} will automatically be mapped to attributes by the same name on your class.

      class MyCommand < Base
        attr_accessor :myattr
      end

      Adapter.new(libs, {:myattr => 'foo'}).start

      # when a request comes in, cmd.myattr == 'foo'

## Subclassing Notes

To implement a custom command, override the {run} method, not {call}. In your implementation, you should set the body and status for requests. See details in the +run+ method documentation.

Note that if your command deals directly with libraries, you should consider subclassing the more specific {LibraryCommand} class instead.

@abstract @see run

### Methods

cache call new not_found redirect render run

### Attributes

adapter | [RW] | @return [Adapter] the server adapter
body | [RW] | @return [String] the response body. Defaults to empty string.
caching | [RW] | @return [Boolean] whether to cache
command_options | [RW] | @return [Hash] the options passed to the command‘s constructor
headers | [RW] | @return [Hash{String => String}] response headers
path | [RW] | @return [String] the path after the command base URI
request | [RW] | @return [Request] request object
status | [RW] | @return [Numeric] status code. Defaults to 200 per request

### Public Class methods

new(opts = {})

Creates a new command object, setting attributes named by keys in the options hash. After initialization, the options hash is saved in {command_options} for further inspection.

@example Creating a Command

      cmd = DisplayObjectCommand.new(:caching => true, :library => mylib)
      cmd.library # => mylib
      cmd.command_options # => {:caching => true, :library => mylib}

@param [Hash] opts the options hash, saved to {command_options}

      after initialization.

### Public Instance methods

call(request)

The main method called by a router with a request object.

@note This command should not be overridden by subclasses. Implement

      the callback method {#run} instead.

@param [Adapter Dependent] request the request object @return [Array(Number,Hash,Array<String>)] a Rack-style response

      of status, headers, and body wrapped in an array.

run()

Subclass this method to implement a custom command. This method should set the {status} and {body}, and optionally modify the {headers}. Note that +status+ defaults to 200.

@example A custom command

      class ErrorCommand < Base
        def run
          self.body = 'ERROR! The System is down!'
          self.status = 500
          self.headers['Conten-Type'] = 'text/plain'
        end
      end

@abstract @return [void]

### Protected Instance methods

cache(data)

Override this method to implement custom caching mechanisms for

@example Caching to memory

      $memory_cache = {}
      def cache(data)
        $memory_cache[path] = data
      end

@param [String] data the data to cache @return [String] the same cached data (for chaining) @see StaticCaching

not_found()

Sets the body and headers (but not status) for a 404 response. Does nothing if the body is already set.

@return [void]

redirect(url)

Sets the headers and status code for a redirection to a given URL @param [String] url the URL to redirect to @raise [FinishRequest] causes the request to terminate.

render(object = nil)

Renders a specific object if provided, or a regular template rendering if object is not provided.

@todo This method is dependent on +options+, it should be in {LibraryCommand}. @param [CodeObjects::Base, nil] object calls {CodeObjects::Base#format} if

      an object is provided, or {Templates::Engine.render} if object is nil. Both
      receive +#options+ as an argument.

@return [String] the resulting output to display

[Validate]