yard 0.9.17 → 0.9.22

data/lib/yard/server/rack_adapter.rb

@@ -1,89 +1,89 @@
-# frozen_string_literal: true
-require 'rack'
-require 'webrick/httputils'
-
-module YARD
-  module Server
-    # This class wraps the {RackAdapter} into a Rack-compatible middleware.
-    # See {#initialize} for a list of options to pass via Rack's +#use+ method.
-    #
-    # @note You must pass a +:libraries+ option to the RackMiddleware via +#use+. To
-    #   read about how to return a list of libraries, see {LibraryVersion} or look
-    #   at the example below.
-    # @example Using the RackMiddleware in a Rack application
-    #   libraries = {:mylib => [YARD::Server::LibraryVersion.new('mylib', nil, '/path/to/.yardoc')]}
-    #   use YARD::Server::RackMiddleware, :libraries => libraries
-    #
-    class RackMiddleware
-      # Creates a new Rack-based middleware for serving YARD documentation.
-      #
-      # @param app the next Rack middleware in the stack
-      # @option opts [Hash{String=>Array<LibraryVersion>}] :libraries ({})
-      #   the map of libraries to serve through the adapter. This option is *required*.
-      # @option opts [Hash] :options ({}) a list of options to pass to the adapter.
-      #   See {Adapter#options} for a list.
-      # @option opts [Hash] :server_options ({}) a list of options to pass to the server.
-      #   See {Adapter#server_options} for a list.
-      def initialize(app, opts = {})
-        args = [opts[:libraries] || {}, opts[:options] || {}, opts[:server_options] || {}]
-        @app = app
-        @adapter = RackAdapter.new(*args)
-      end
-
-      def call(env)
-        status, headers, body = *@adapter.call(env)
-        if status == 404
-          @app.call(env)
-        else
-          [status, headers, body]
-        end
-      end
-    end
-
-    # A server adapter to respond to requests using the Rack server infrastructure.
-    class RackAdapter < Adapter
-      include WEBrick::HTTPUtils
-
-      # Responds to Rack requests and builds a response with the {Router}.
-      # @return [Array(Numeric,Hash,Array)] the Rack-style response
-      def call(env)
-        request = Rack::Request.new(env)
-        request.path_info = unescape(request.path_info) # unescape things like %3F
-        router.call(request)
-      rescue StandardError => ex
-        log.backtrace(ex)
-        [500, {'Content-Type' => 'text/plain'},
-          [ex.message + "\n" + ex.backtrace.join("\n")]]
-      end
-
-      # Starts the +Rack::Server+. This method will pass control to the server and
-      # block.
-      # @return [void]
-      def start
-        server = Rack::Server.new(server_options)
-        server.instance_variable_set("@app", self)
-        print_start_message(server)
-        server.start
-      end
-
-      private
-
-      def print_start_message(server)
-        opts = server.default_options.merge(server.options)
-        log.puts ">> YARD #{YARD::VERSION} documentation server at http://#{opts[:Host]}:#{opts[:Port]}"
-
-        # Only happens for Mongrel
-        return unless server.server.to_s == "Rack::Handler::Mongrel"
-        log.puts ">> #{server.server.class_name} web server (running on Rack)"
-        log.puts ">> Listening on #{opts[:Host]}:#{opts[:Port]}, CTRL+C to stop"
-      end
-    end
-  end
-end
-
-# @private
-class Rack::Request
-  attr_accessor :version_supplied
-  alias query params
-  def xhr?; (env['HTTP_X_REQUESTED_WITH'] || "").casecmp("xmlhttprequest") == 0 end
-end
+# frozen_string_literal: true
+require 'rack'
+require 'webrick/httputils'
+
+module YARD
+  module Server
+    # This class wraps the {RackAdapter} into a Rack-compatible middleware.
+    # See {#initialize} for a list of options to pass via Rack's +#use+ method.
+    #
+    # @note You must pass a +:libraries+ option to the RackMiddleware via +#use+. To
+    #   read about how to return a list of libraries, see {LibraryVersion} or look
+    #   at the example below.
+    # @example Using the RackMiddleware in a Rack application
+    #   libraries = {:mylib => [YARD::Server::LibraryVersion.new('mylib', nil, '/path/to/.yardoc')]}
+    #   use YARD::Server::RackMiddleware, :libraries => libraries
+    #
+    class RackMiddleware
+      # Creates a new Rack-based middleware for serving YARD documentation.
+      #
+      # @param app the next Rack middleware in the stack
+      # @option opts [Hash{String=>Array<LibraryVersion>}] :libraries ({})
+      #   the map of libraries to serve through the adapter. This option is *required*.
+      # @option opts [Hash] :options ({}) a list of options to pass to the adapter.
+      #   See {Adapter#options} for a list.
+      # @option opts [Hash] :server_options ({}) a list of options to pass to the server.
+      #   See {Adapter#server_options} for a list.
+      def initialize(app, opts = {})
+        args = [opts[:libraries] || {}, opts[:options] || {}, opts[:server_options] || {}]
+        @app = app
+        @adapter = RackAdapter.new(*args)
+      end
+
+      def call(env)
+        status, headers, body = *@adapter.call(env)
+        if status == 404
+          @app.call(env)
+        else
+          [status, headers, body]
+        end
+      end
+    end
+
+    # A server adapter to respond to requests using the Rack server infrastructure.
+    class RackAdapter < Adapter
+      include WEBrick::HTTPUtils
+
+      # Responds to Rack requests and builds a response with the {Router}.
+      # @return [Array(Numeric,Hash,Array)] the Rack-style response
+      def call(env)
+        request = Rack::Request.new(env)
+        request.path_info = unescape(request.path_info) # unescape things like %3F
+        router.call(request)
+      rescue StandardError => ex
+        log.backtrace(ex)
+        [500, {'Content-Type' => 'text/plain'},
+          [ex.message + "\n" + ex.backtrace.join("\n")]]
+      end
+
+      # Starts the +Rack::Server+. This method will pass control to the server and
+      # block.
+      # @return [void]
+      def start
+        server = Rack::Server.new(server_options)
+        server.instance_variable_set("@app", self)
+        print_start_message(server)
+        server.start
+      end
+
+      private
+
+      def print_start_message(server)
+        opts = server.default_options.merge(server.options)
+        log.puts ">> YARD #{YARD::VERSION} documentation server at http://#{opts[:Host]}:#{opts[:Port]}"
+
+        # Only happens for Mongrel
+        return unless server.server.to_s == "Rack::Handler::Mongrel"
+        log.puts ">> #{server.server.class_name} web server (running on Rack)"
+        log.puts ">> Listening on #{opts[:Host]}:#{opts[:Port]}, CTRL+C to stop"
+      end
+    end
+  end
+end
+
+# @private
+class Rack::Request
+  attr_accessor :version_supplied
+  alias query params
+  def xhr?; (env['HTTP_X_REQUESTED_WITH'] || "").casecmp("xmlhttprequest") == 0 end
+end

data/lib/yard/server/router.rb

@@ -1,187 +1,187 @@
-# frozen_string_literal: true
-module YARD
-  module Server
-    # 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},
-    # {#static_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 static_prefix; 'mystatic' end
-    #     def search_prefix; 'mysearch' end
-    #   end
-    #
-    #   # Using it:
-    #   WebrickAdapter.new(libraries, :router => MyRouter).start
-    class Router
-      include StaticCaching
-      include Commands
-
-      # @return [Adapter Dependent] the request data coming in with the routing
-      attr_accessor :request
-
-      # @return [Adapter] the adapter used by the router
-      attr_accessor :adapter
-
-      # Creates a new router for a specific adapter
-      #
-      # @param [Adapter] adapter the adapter to route requests to
-      def initialize(adapter)
-        self.adapter = adapter
-      end
-
-      # Perform routing on a specific request, serving the request as a static
-      # file through {Commands::RootRequestCommand} if no route is found.
-      #
-      # @param [Adapter Dependent] request the request object
-      # @return [Array(Numeric,Hash,Array)] the Rack-style server response data
-      def call(request)
-        self.request = request
-        result = check_static_cache || route
-        result ? result : RootRequestCommand.new(adapter.options).call(request)
-      end
-
-      # @group Route Prefixes
-
-      # @return [String] the URI prefix for all object documentation requests
-      def docs_prefix; 'docs' end
-
-      # @return [String] the URI prefix for all class/method/file list requests
-      def list_prefix; 'list' end
-
-      # @return [String] the URI prefix for all search requests
-      def search_prefix; 'search' end
-
-      # @return [String] the URI prefix for all static assets (templates)
-      def static_prefix; 'static' end
-
-      # @group Routing Methods
-
-      # @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.
-      def parse_library_from_path(paths)
-        return [adapter.libraries.values.first.first, paths] if adapter.options[:single_library]
-        library = nil
-        paths = paths.dup
-        libs = adapter.libraries[paths.first]
-        if libs
-          paths.shift
-          library = libs.find {|l| l.version == paths.first }
-          if library
-            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
-
-      protected
-
-      # 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
-      def route(path = request.path_info)
-        path = path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
-        return route_index if path.empty? || path == docs_prefix
-        case path
-        when %r{^(#{docs_prefix}|#{list_prefix}|#{search_prefix}|#{static_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)
-                 when static_prefix; route_static(library, paths)
-                 end
-        end
-        nil
-      end
-
-      # 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)
-      def route_docs(library, paths)
-        return route_index if library.nil?
-        case paths.first
-        when "frames"
-          paths.shift
-          cmd = DisplayObjectCommand
-        when "file"
-          paths.shift
-          cmd = DisplayFileCommand
-        else
-          cmd = DisplayObjectCommand
-        end
-        cmd = cmd.new(final_options(library, paths))
-        cmd.call(request)
-      end
-
-      # Routes for the index of a library / multiple libraries
-      # @return (see #route)
-      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
-
-      # Routes requests from {#list_prefix} and calls the appropriate command
-      # @param (see #route_docs)
-      # @return (see #route_docs)
-      def route_list(library, paths)
-        return if paths.empty?
-        ListCommand.new(final_options(library, paths)).call(request)
-      end
-
-      # Routes requests from {#search_prefix} and calls the appropriate command
-      # @param (see #route_docs)
-      # @return (see #route_docs)
-      def route_search(library, paths)
-        return unless paths.empty?
-        SearchCommand.new(final_options(library, paths)).call(request)
-      end
-
-      def route_static(library, paths)
-        StaticFileCommand.new(final_options(library, paths)).call(request)
-      end
-
-      # @group Utility Methods
-
-      # 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
-      def final_options(library, paths)
-        path = File.cleanpath(paths.join('/')).gsub(%r{^(\.\./)+}, '')
-        adapter.options.merge(:library => library, :path => path)
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  module Server
+    # 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},
+    # {#static_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 static_prefix; 'mystatic' end
+    #     def search_prefix; 'mysearch' end
+    #   end
+    #
+    #   # Using it:
+    #   WebrickAdapter.new(libraries, :router => MyRouter).start
+    class Router
+      include StaticCaching
+      include Commands
+
+      # @return [Adapter Dependent] the request data coming in with the routing
+      attr_accessor :request
+
+      # @return [Adapter] the adapter used by the router
+      attr_accessor :adapter
+
+      # Creates a new router for a specific adapter
+      #
+      # @param [Adapter] adapter the adapter to route requests to
+      def initialize(adapter)
+        self.adapter = adapter
+      end
+
+      # Perform routing on a specific request, serving the request as a static
+      # file through {Commands::RootRequestCommand} if no route is found.
+      #
+      # @param [Adapter Dependent] request the request object
+      # @return [Array(Numeric,Hash,Array)] the Rack-style server response data
+      def call(request)
+        self.request = request
+        result = check_static_cache || route
+        result ? result : RootRequestCommand.new(adapter.options).call(request)
+      end
+
+      # @group Route Prefixes
+
+      # @return [String] the URI prefix for all object documentation requests
+      def docs_prefix; 'docs' end
+
+      # @return [String] the URI prefix for all class/method/file list requests
+      def list_prefix; 'list' end
+
+      # @return [String] the URI prefix for all search requests
+      def search_prefix; 'search' end
+
+      # @return [String] the URI prefix for all static assets (templates)
+      def static_prefix; 'static' end
+
+      # @group Routing Methods
+
+      # @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.
+      def parse_library_from_path(paths)
+        return [adapter.libraries.values.first.first, paths] if adapter.options[:single_library]
+        library = nil
+        paths = paths.dup
+        libs = adapter.libraries[paths.first]
+        if libs
+          paths.shift
+          library = libs.find {|l| l.version == paths.first }
+          if library
+            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
+
+      protected
+
+      # 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
+      def route(path = request.path_info)
+        path = path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
+        return route_index if path.empty? || path == docs_prefix
+        case path
+        when %r{^(#{docs_prefix}|#{list_prefix}|#{search_prefix}|#{static_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)
+                 when static_prefix; route_static(library, paths)
+                 end
+        end
+        nil
+      end
+
+      # 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)
+      def route_docs(library, paths)
+        return route_index if library.nil?
+        case paths.first
+        when "frames"
+          paths.shift
+          cmd = DisplayObjectCommand
+        when "file"
+          paths.shift
+          cmd = DisplayFileCommand
+        else
+          cmd = DisplayObjectCommand
+        end
+        cmd = cmd.new(final_options(library, paths))
+        cmd.call(request)
+      end
+
+      # Routes for the index of a library / multiple libraries
+      # @return (see #route)
+      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
+
+      # Routes requests from {#list_prefix} and calls the appropriate command
+      # @param (see #route_docs)
+      # @return (see #route_docs)
+      def route_list(library, paths)
+        return if paths.empty?
+        ListCommand.new(final_options(library, paths)).call(request)
+      end
+
+      # Routes requests from {#search_prefix} and calls the appropriate command
+      # @param (see #route_docs)
+      # @return (see #route_docs)
+      def route_search(library, paths)
+        return unless paths.empty?
+        SearchCommand.new(final_options(library, paths)).call(request)
+      end
+
+      def route_static(library, paths)
+        StaticFileCommand.new(final_options(library, paths)).call(request)
+      end
+
+      # @group Utility Methods
+
+      # 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
+      def final_options(library, paths)
+        path = File.cleanpath(paths.join('/')).gsub(%r{^(\.\./)+}, '')
+        adapter.options.merge(:library => library, :path => path)
+      end
+    end
+  end
+end