Class: YARD::Server::Router

Inherits:
Object
  • Object
show all
Includes:
Commands, StaticCaching
Defined in:
lib/yard/server/router.rb

Overview

A router class implements the logic used to recognize a request for a specific URL and run specific commands.

Subclassing Notes

To create a custom router, subclass this class and pass it into the adapter options through Adapter#initialize or by directly modifying Adapter#router.

The most general customization is to change the URL prefixes recognized by routing, which can be done by overriding #docs_prefix, #list_prefix and #search_prefix.

Implementing Custom Caching

By default, the Router class performs static disk-based caching on all requests through the #check_static_cache. To override this behaviour, or create your own caching mechanism, mixin your own custom module with this method implemented as per StaticCaching#check_static_cache.

Examples:

Creating a subclassed router

# Adds 'my' to all routing prefixes
class MyRouter < YARD::Server::Router
  def docs_prefix; 'mydocs' end
  def list_prefix; 'mylist' end
  def search_prefix; 'mysearch' end
end

# Using it:
WebrickAdapter.new(libraries, :router => MyRouter).start

Since:

  • 0.6.0

Instance Attribute Summary collapse

Route Prefixes collapse

Routing Methods collapse

Utility Methods collapse

Instance Method Summary collapse

Methods included from StaticCaching

#check_static_cache

Constructor Details

#initialize(adapter) ⇒ Router

Creates a new router for a specific adapter

Since:

  • 0.6.0

Parameters:

  • the adapter to route requests to



43
44
45
 
# File 'lib/yard/server/router.rb', line 43

def initialize(adapter)
  self.adapter = adapter
end

Instance Attribute Details

#adapter ⇒ Adapter

Returns the adapter used by the router.

Since:

  • 0.6.0

Returns:

  • the adapter used by the router



38
39
40
 
# File 'lib/yard/server/router.rb', line 38

def adapter
  @adapter
end

#request ⇒ Adapter Dependent

Returns the request data coming in with the routing.

Since:

  • 0.6.0

Returns:

  • the request data coming in with the routing



35
36
37
 
# File 'lib/yard/server/router.rb', line 35

def request
  @request
end

Instance Method Details

#call(request) ⇒ Array(Numeric,Hash,Array)

Perform routing on a specific request, serving the request as a static file through Commands::StaticFileCommand if no route is found.

Since:

  • 0.6.0

Parameters:

  • the request object

Returns:

  • the Rack-style server response data



52
53
54
55
56
57
58
59
 
# File 'lib/yard/server/router.rb', line 52

def call(request)
  self.request = request
  if result = (check_static_cache || route)
    result
  else
    StaticFileCommand.new(adapter.options).call(request)
  end
end

#docs_prefix ⇒ String

Returns the URI prefix for all object documentation requests.

Since:

  • 0.6.0

Returns:

  • the URI prefix for all object documentation requests



64
 
# File 'lib/yard/server/router.rb', line 64

def docs_prefix; 'docs' end

#final_options(library, paths) ⇒ Hash (protected)

Adds extra :library/:path option keys to the adapter options. Use this method when passing options to a command.

Since:

  • 0.6.0

Parameters:

  • the library to route for

  • path components (split by ‘/’)

Returns:

  • finalized options



171
172
173
 
# File 'lib/yard/server/router.rb', line 171

def final_options(library, paths)
  adapter.options.merge(:library => library, :path => paths.join('/'))
end

#list_prefix ⇒ String

Returns the URI prefix for all class/method/file list requests.

Since:

  • 0.6.0

Returns:

  • the URI prefix for all class/method/file list requests



67
 
# File 'lib/yard/server/router.rb', line 67

def list_prefix; 'list' end

#parse_library_from_path(paths) ⇒ Array(LibraryVersion, Array<String>)

Returns the library followed by the rest of the path components in the request path. LibraryVersion will be nil if no matching library was found.

Since:

  • 0.6.0

Returns:

  • the library followed by the rest of the path components in the request path. LibraryVersion will be nil if no matching library was found.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/yard/server/router.rb', line 77

def parse_library_from_path(paths)
  return [adapter.libraries.values.first.first, paths] if adapter.options[:single_library]
  library, paths = nil, paths.dup
  if libs = adapter.libraries[paths.first]
    paths.shift
    if library = libs.find {|l| l.version == paths.first }
      request.version_supplied = true if request
      paths.shift
    else # use the last lib in the list
      request.version_supplied = false if request
      library = libs.last
    end
  end
  [library, paths]
end

#route(path = request.path) ⇒ Array(Numeric,Hash,Array<String>)? (protected)

Performs routing algorithm to find which prefix is called, first parsing out library name/version information.

Since:

  • 0.6.0

Returns:

  • the Rack-style response

  • if no route is matched



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/yard/server/router.rb', line 100

def route(path = request.path)
  path = path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
  return route_index if path.empty? || path == docs_prefix
  case path
  when /^(#{docs_prefix}|#{list_prefix}|#{search_prefix})(\/.*|$)/
    prefix = $1
    paths = $2.gsub(%r{^/|/$}, '').split('/')
    library, paths = *parse_library_from_path(paths)
    return unless library
    return case prefix
    when docs_prefix;   route_docs(library, paths)
    when list_prefix;   route_list(library, paths)
    when search_prefix; route_search(library, paths)
    end
  end
  nil
end

#route_docs(library, paths) ⇒ Array(Numeric,Hash,Array<String>)? (protected)

Routes requests from #docs_prefix and calls the appropriate command

Since:

  • 0.6.0

Parameters:

  • the library to route for

  • path components (split by ‘/’)

Returns:

  • the Rack-style response

  • if no route is matched



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/yard/server/router.rb', line 122

def route_docs(library, paths)
  return route_index if library.nil?
  case paths.first
  when "frames"
    paths.shift
    cmd = FramesCommand
  when "file"
    paths.shift
    cmd = DisplayFileCommand
  else
    cmd = DisplayObjectCommand
  end
  cmd = cmd.new(final_options(library, paths))
  cmd.call(request)
end

#route_index ⇒ Array(Numeric,Hash,Array<String>)? (protected)

Routes for the index of a library / multiple libraries

Since:

  • 0.6.0

Returns:

  • the Rack-style response

  • if no route is matched



140
141
142
143
144
145
146
 
# File 'lib/yard/server/router.rb', line 140

def route_index
  if adapter.options[:single_library]
    route_docs(adapter.libraries.values.first.first, [])
  else
    LibraryIndexCommand.new(adapter.options.merge(:path => '')).call(request)
  end
end

#route_list(library, paths) ⇒ Array(Numeric,Hash,Array<String>)? (protected)

Routes requests from #list_prefix and calls the appropriate command

Since:

  • 0.6.0

Parameters:

  • the library to route for

  • path components (split by ‘/’)

Returns:

  • the Rack-style response

  • if no route is matched



151
152
153
154
 
# File 'lib/yard/server/router.rb', line 151

def route_list(library, paths)
  return if paths.empty?
  ListCommand.new(final_options(library, paths)).call(request)
end

#route_search(library, paths) ⇒ Array(Numeric,Hash,Array<String>)? (protected)

Routes requests from #search_prefix and calls the appropriate command

Since:

  • 0.6.0

Parameters:

  • the library to route for

  • path components (split by ‘/’)

Returns:

  • the Rack-style response

  • if no route is matched



159
160
161
162
 
# File 'lib/yard/server/router.rb', line 159

def route_search(library, paths)
  return unless paths.empty?
  SearchCommand.new(final_options(library, paths)).call(request)
end

#search_prefix ⇒ String

Returns the URI prefix for all search requests.

Since:

  • 0.6.0

Returns:

  • the URI prefix for all search requests



70
 
# File 'lib/yard/server/router.rb', line 70

def search_prefix; 'search' end