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:

  • 0.6.0

Direct Known Subclasses

RackAdapter, WebrickAdapter

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

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

#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:

See Also:

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:

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