class YARD::Server::Router

A router class implements the logic used to recognize a request for a specific URL and run specific {Commands::Base 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}.

@example 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

Attributes

adapter[RW]

@return [Adapter] the adapter used by the router

request[RW]

@return [Adapter Dependent] the request data coming in with the routing

Public Class Methods

new(adapter) click to toggle source

Creates a new router for a specific adapter

@param [Adapter] adapter the adapter to route requests to

# File lib/yard/server/router.rb, line 43
def initialize(adapter)
  self.adapter = adapter
end

Public Instance Methods

call(request) click to toggle source

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

@param [Adapter Dependent] request the request object @return [Array(Numeric,Hash,Array)] the Rack-style server response data

# 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() click to toggle source

@return [String] the URI prefix for all object documentation requests

# File lib/yard/server/router.rb, line 64
def docs_prefix; 'docs' end
list_prefix() click to toggle source

@return [String] the URI prefix for all class/method/file list requests

# File lib/yard/server/router.rb, line 67
def list_prefix; 'list' end
parse_library_from_path(paths) click to toggle source

@return [Array(LibraryVersion, Array<String>)] the library followed

by the rest of the path components in the request path. LibraryVersion
will be nil if no matching library was found.
# 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
search_prefix() click to toggle source

@return [String] the URI prefix for all search requests

# File lib/yard/server/router.rb, line 70
def search_prefix; 'search' end

Protected Instance Methods

final_options(library, paths) click to toggle source

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

@param (see route_docs) @return [Hash] finalized options

# File lib/yard/server/router.rb, line 171
def final_options(library, paths)
  adapter.options.merge(:library => library, :path => paths.join('/'))
end
route(path = request.path) click to toggle source

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

@return [Array(Numeric,Hash,Array<String>)] the Rack-style response @return [nil] if no route is matched

# 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) click to toggle source

Routes requests from {#docs_prefix} and calls the appropriate command @param [LibraryVersion] library the library to route for @param [Array<String>] paths path components (split by '/') @return (see route)

# 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() click to toggle source

Routes for the index of a library / multiple libraries @return (see route)

# 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) click to toggle source

Routes requests from {#list_prefix} and calls the appropriate command @param (see route_docs) @return (see route_docs)

# 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