# Class: YARD::Server::Adapter Abstract

Inherits:
  Object
  - Object
  - YARD::Server::Adapter
  show all

Defined in:
  lib/yard/server/adapter.rb

## Overview

This class is abstract.

This class implements the bridge between the Router and the server backend for a specific server type. YARD implements concrete adapters for WEBrick and Rack respectively, though other adapters can be made for other server architectures.

## Subclassing Notes

To create a concrete adapter class, implement the #start method to initiate the server backend.

Since:

- 0.6.0

## Direct Known Subclasses

RackAdapter, WebrickAdapter

## Instance Attribute Summary collapse

- #document_root ⇒ String

  The location where static files are located, if any.

- #libraries ⇒ Hash{String=>Array<LibraryVersion>}

  A map of libraries.

- #options ⇒ Hash

  Options passed and processed by adapters.

- #router ⇒ Router

  The router object used to route URLs to commands.

- #server_options ⇒ Hash

  A set of options to pass to the server backend.

## Class Method Summary collapse

- .setup ⇒ void

  Performs any global initialization for the adapter.

- .shutdown ⇒ void

  Performs any global shutdown procedures for the adapter.

## Instance Method Summary collapse

- #add_library(library) ⇒ Object

  Adds a library to the #libraries mapping for a given library object.

- #initialize(libs, opts = {}, server_opts = {}) ⇒ Adapter constructor

  Creates a new adapter object.

- #start ⇒ Object abstract

  Implement this method to connect your adapter to your server.

## Constructor Details

### #initialize(libs, opts = {}, server_opts = {}) ⇒ `Adapter`

Creates a new adapter object

Parameters:

- libs (`Hash{String=>Array<LibraryVersion>}`) —

  a list of libraries, see #libraries for formulating this list.

- opts (`Hash`) (defaults to: `{}`) —

  extra options to pass to the adapter

Options Hash (`opts`):

- :router (`Class`) — default: `Router` —

  the router class to initialize as the adapter’s router.

- :caching (`Boolean`) — default: `false` —

  whether or not caching is enabled

- :single_library (`Boolean`) — default: `false` —

  whether to server documentation for a single or multiple libraries (changes URL structure)

Since:

- 0.6.0

    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82

    # File 'lib/yard/server/adapter.rb', line 71

    def initialize(libs, opts = {}, server_opts = {})
      self.class.setup
      self.libraries = libs
      self.options = opts
      self.server_options = server_opts
      self.document_root = server_options[:DocumentRoot]
      self.router = (options[:router] || Router).new(self)
      options[:adapter] = self
      log.debug "Serving libraries using #{self.class}: #{libraries.keys.join(', ')}"
      log.debug "Caching on" if options[:caching]
      log.debug "Document root: #{document_root}" if document_root
    end

## Instance Attribute Details

### #document_root ⇒ `String`

Returns the location where static files are located, if any. To set this field on initialization, pass `:DocumentRoot` to the `server_opts` argument in #initialize.

Returns:

- (`String`) —

  the location where static files are located, if any. To set this field on initialization, pass `:DocumentRoot` to the `server_opts` argument in #initialize

Since:

- 0.6.0

    27
    28
    29

    # File 'lib/yard/server/adapter.rb', line 27

    def document_root
      @document_root
    end

### #libraries ⇒ `Hash{String=>Array<LibraryVersion>}`

Returns a map of libraries.

Returns:

- (`Hash{String=>Array<LibraryVersion>}`) —

  a map of libraries.

See Also:

- LibraryVersion for information on building a list of libraries
- #add_library

Since:

- 0.6.0

    32
    33
    34

    # File 'lib/yard/server/adapter.rb', line 32

    def libraries
      @libraries
    end

### #options ⇒ `Hash`

Returns options passed and processed by adapters. The actual options mostly depend on the adapters themselves.

Returns:

- (`Hash`) —

  options passed and processed by adapters. The actual options mostly depend on the adapters themselves.

Since:

- 0.6.0

    36
    37
    38

    # File 'lib/yard/server/adapter.rb', line 36

    def options
      @options
    end

### #router ⇒ `Router`

Returns the router object used to route URLs to commands.

Returns:

- (`Router`) —

  the router object used to route URLs to commands

Since:

- 0.6.0

    43
    44
    45

    # File 'lib/yard/server/adapter.rb', line 43

    def router
      @router
    end

### #server_options ⇒ `Hash`

Returns a set of options to pass to the server backend. Note that `:DocumentRoot` also sets the #document_root.

Returns:

- (`Hash`) —

  a set of options to pass to the server backend. Note that `:DocumentRoot` also sets the #document_root.

Since:

- 0.6.0

    40
    41
    42

    # File 'lib/yard/server/adapter.rb', line 40

    def server_options
      @server_options
    end

## Class Method Details

### .setup ⇒ `void`

Note:

If you subclass this method, make sure to call `super`.

This method returns an undefined value.

Performs any global initialization for the adapter.

Since:

- 0.6.0

    48
    49
    50
    51

    # File 'lib/yard/server/adapter.rb', line 48

    def self.setup
      Templates::Template.extra_includes |= [YARD::Server::DocServerHelper]
      Templates::Engine.template_paths |= [File.dirname(__FILE__) + '/templates']
    end

### .shutdown ⇒ `void`

Note:

If you subclass this method, make sure to call `super`.

This method returns an undefined value.

Performs any global shutdown procedures for the adapter.

Since:

- 0.6.0

    56
    57
    58
    59

    # File 'lib/yard/server/adapter.rb', line 56

    def self.shutdown
      Templates::Template.extra_includes -= [YARD::Server::DocServerHelper]
      Templates::Engine.template_paths -= [File.dirname(__FILE__) + '/templates']
    end

## Instance Method Details

### #add_library(library) ⇒ `Object`

Adds a library to the #libraries mapping for a given library object.

#### Examples:

#####

Adding a new library to an adapter

    adapter.add_library LibraryVersion.new('mylib', '1.0', '/path/to/.yardoc')

Parameters:

- library (`LibraryVersion`) —

  a library to add

Since:

- 0.6.0

    88
    89
    90
    91

    # File 'lib/yard/server/adapter.rb', line 88

    def add_library(library)
      libraries[library.name] ||= []
      libraries[library.name] |= [library]
    end

### #start ⇒ `Object`

This method is abstract.

Implement this method to connect your adapter to your server.

Raises:

- (`NotImplementedError`)

Since:

- 0.6.0

    95
    96
    97

    # File 'lib/yard/server/adapter.rb', line 95

    def start
      raise NotImplementedError
    end