Class: YARD::Server::Adapter Abstract

Inherits:
Object
  • Object
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:

Direct Known Subclasses

RackAdapter, WebrickAdapter

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

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

Creates a new adapter object

Parameters:

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

- (String) document_root

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

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

Returns a map of libraries.



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

def libraries
  @libraries
end

- (Hash) options

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

- (Hash) server_options

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

+ (void) setup

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

+ (void) shutdown

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

- (Object) add_library(library)

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:

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

- (Object) start

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