yard 0.9.17 → 0.9.22

data/lib/yard/server/adapter.rb

@@ -1,100 +1,100 @@
-# frozen_string_literal: true
-module YARD
-  module Server
-    # Short circuits a request by raising an error. This exception is caught
-    # by {Commands::Base#call} to immediately end a request and return a response.
-    class FinishRequest < RuntimeError; end
-
-    # Raises an error if a resource is not found. This exception is caught by
-    # {Commands::Base#call} to immediately end a request and return a 404 response
-    # code. If a message is provided, the body is set to the exception message.
-    class NotFoundError < RuntimeError; end
-
-    # 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.
-    #
-    # @abstract
-    class Adapter
-      # @return [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}
-      attr_accessor :document_root
-
-      # @return [Hash{String=>Array<LibraryVersion>}] a map of libraries.
-      # @see LibraryVersion LibraryVersion for information on building a list of libraries
-      # @see #add_library
-      attr_accessor :libraries
-
-      # @return [Hash] options passed and processed by adapters. The actual
-      #   options mostly depend on the adapters themselves.
-      attr_accessor :options
-
-      # @return [Hash] a set of options to pass to the server backend. Note
-      #   that +:DocumentRoot+ also sets the {#document_root}.
-      attr_accessor :server_options
-
-      # @return [Router] the router object used to route URLs to commands
-      attr_accessor :router
-
-      # Performs any global initialization for the adapter.
-      # @note If you subclass this method, make sure to call +super+.
-      # @return [void]
-      def self.setup
-        Templates::Template.extra_includes |= [YARD::Server::DocServerHelper]
-        Templates::Engine.template_paths |= [File.dirname(__FILE__) + '/templates']
-      end
-
-      # Performs any global shutdown procedures for the adapter.
-      # @note If you subclass this method, make sure to call +super+.
-      # @return [void]
-      def self.shutdown
-        Templates::Template.extra_includes -= [YARD::Server::DocServerHelper]
-        Templates::Engine.template_paths -= [File.dirname(__FILE__) + '/templates']
-      end
-
-      # Creates a new adapter object
-      #
-      # @param [Hash{String=>Array<LibraryVersion>}] libs a list of libraries,
-      #   see {#libraries} for formulating this list.
-      # @param [Hash] opts extra options to pass to the adapter
-      # @option opts [Class] :router (Router) the router class to initialize as the
-      #   adapter's router.
-      # @option opts [Boolean] :caching (false) whether or not caching is enabled
-      # @option opts [Boolean] :single_library (false) whether to server documentation
-      #   for a single or multiple libraries (changes URL structure)
-      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
-
-      # Adds a library to the {#libraries} mapping for a given library object.
-      # @example Adding a new library to an adapter
-      #   adapter.add_library LibraryVersion.new('mylib', '1.0', '/path/to/.yardoc')
-      # @param [LibraryVersion] library a library to add
-      def add_library(library)
-        libraries[library.name] ||= []
-        libraries[library.name] |= [library]
-      end
-
-      # Implement this method to connect your adapter to your server.
-      # @abstract
-      def start
-        raise NotImplementedError
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  module Server
+    # Short circuits a request by raising an error. This exception is caught
+    # by {Commands::Base#call} to immediately end a request and return a response.
+    class FinishRequest < RuntimeError; end
+
+    # Raises an error if a resource is not found. This exception is caught by
+    # {Commands::Base#call} to immediately end a request and return a 404 response
+    # code. If a message is provided, the body is set to the exception message.
+    class NotFoundError < RuntimeError; end
+
+    # 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.
+    #
+    # @abstract
+    class Adapter
+      # @return [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}
+      attr_accessor :document_root
+
+      # @return [Hash{String=>Array<LibraryVersion>}] a map of libraries.
+      # @see LibraryVersion LibraryVersion for information on building a list of libraries
+      # @see #add_library
+      attr_accessor :libraries
+
+      # @return [Hash] options passed and processed by adapters. The actual
+      #   options mostly depend on the adapters themselves.
+      attr_accessor :options
+
+      # @return [Hash] a set of options to pass to the server backend. Note
+      #   that +:DocumentRoot+ also sets the {#document_root}.
+      attr_accessor :server_options
+
+      # @return [Router] the router object used to route URLs to commands
+      attr_accessor :router
+
+      # Performs any global initialization for the adapter.
+      # @note If you subclass this method, make sure to call +super+.
+      # @return [void]
+      def self.setup
+        Templates::Template.extra_includes |= [YARD::Server::DocServerHelper]
+        Templates::Engine.template_paths |= [File.dirname(__FILE__) + '/templates']
+      end
+
+      # Performs any global shutdown procedures for the adapter.
+      # @note If you subclass this method, make sure to call +super+.
+      # @return [void]
+      def self.shutdown
+        Templates::Template.extra_includes -= [YARD::Server::DocServerHelper]
+        Templates::Engine.template_paths -= [File.dirname(__FILE__) + '/templates']
+      end
+
+      # Creates a new adapter object
+      #
+      # @param [Hash{String=>Array<LibraryVersion>}] libs a list of libraries,
+      #   see {#libraries} for formulating this list.
+      # @param [Hash] opts extra options to pass to the adapter
+      # @option opts [Class] :router (Router) the router class to initialize as the
+      #   adapter's router.
+      # @option opts [Boolean] :caching (false) whether or not caching is enabled
+      # @option opts [Boolean] :single_library (false) whether to server documentation
+      #   for a single or multiple libraries (changes URL structure)
+      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
+
+      # Adds a library to the {#libraries} mapping for a given library object.
+      # @example Adding a new library to an adapter
+      #   adapter.add_library LibraryVersion.new('mylib', '1.0', '/path/to/.yardoc')
+      # @param [LibraryVersion] library a library to add
+      def add_library(library)
+        libraries[library.name] ||= []
+        libraries[library.name] |= [library]
+      end
+
+      # Implement this method to connect your adapter to your server.
+      # @abstract
+      def start
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/yard/server/commands/base.rb

@@ -1,209 +1,209 @@
-# frozen_string_literal: true
-require 'fileutils'
-
-module YARD
-  module Server
-    module Commands
-      # This is the base command class used to implement custom commands for
-      # a server. A command will be routed to by the {Router} class and return
-      # a Rack-style response.
-      #
-      # == Attribute Initializers
-      # All attributes can be initialized via options passed into the {#initialize}
-      # method. When creating a custom command, the {Adapter#options} will
-      # automatically be mapped to attributes by the same name on your class.
-      #
-      #   class MyCommand < Base
-      #     attr_accessor :myattr
-      #   end
-      #
-      #   Adapter.new(libs, {:myattr => 'foo'}).start
-      #
-      #   # when a request comes in, cmd.myattr == 'foo'
-      #
-      # == Subclassing Notes
-      # To implement a custom command, override the {#run} method, not {#call}.
-      # In your implementation, you should set the body and status for requests.
-      # See details in the +#run+ method documentation.
-      #
-      # Note that if your command deals directly with libraries, you should
-      # consider subclassing the more specific {LibraryCommand} class instead.
-      #
-      # @abstract
-      # @see #run
-      class Base
-        # @group Basic Command and Adapter Options
-
-        # @return [Hash] the options passed to the command's constructor
-        attr_accessor :command_options
-
-        # @return [Adapter] the server adapter
-        attr_accessor :adapter
-
-        # @return [Boolean] whether to cache
-        attr_accessor :caching
-
-        # @group Attributes Set Per Request
-
-        # @return [Rack::Request] request object
-        attr_accessor :request
-
-        # @return [String] the path after the command base URI
-        attr_accessor :path
-
-        # @return [Hash{String => String}] response headers
-        attr_accessor :headers
-
-        # @return [Numeric] status code. Defaults to 200 per request
-        attr_accessor :status
-
-        # @return [String] the response body. Defaults to empty string.
-        attr_accessor :body
-
-        # @group Instance Method Summary
-
-        # Creates a new command object, setting attributes named by keys
-        # in the options hash. After initialization, the options hash
-        # is saved in {#command_options} for further inspection.
-        #
-        # @example Creating a Command
-        #   cmd = DisplayObjectCommand.new(:caching => true, :library => mylib)
-        #   cmd.library # => mylib
-        #   cmd.command_options # => {:caching => true, :library => mylib}
-        # @param [Hash] opts the options hash, saved to {#command_options}
-        #   after initialization.
-        def initialize(opts = {})
-          opts.each do |key, value|
-            send("#{key}=", value) if respond_to?("#{key}=")
-          end
-          self.command_options = opts
-        end
-
-        # The main method called by a router with a request object.
-        #
-        # @note This command should not be overridden by subclasses. Implement
-        #   the callback method {#run} instead.
-        # @param [Adapter Dependent] request the request object
-        # @return [Array(Numeric,Hash,Array<String>)] a Rack-style response
-        #   of status, headers, and body wrapped in an array.
-        def call(request)
-          self.request = request
-          self.path ||= request.path_info[1..-1]
-          self.headers = {'Content-Type' => 'text/html'}
-          self.body = ''
-          self.status = 200
-          add_cache_control
-          begin
-            run
-          rescue FinishRequest
-            nil # noop
-          rescue NotFoundError => e
-            self.body = e.message if e.message != e.class.to_s
-            not_found
-          end
-
-          # keep this to support commands setting status manually.
-          not_found if status == 404
-
-          [status, headers, body.is_a?(Array) ? body : [body]]
-        end
-
-        # @group Abstract Methods
-
-        # Subclass this method to implement a custom command. This method
-        # should set the {#status} and {#body}, and optionally modify the
-        # {#headers}. Note that +#status+ defaults to 200.
-        #
-        # @example A custom command
-        #   class ErrorCommand < Base
-        #     def run
-        #       self.body = 'ERROR! The System is down!'
-        #       self.status = 500
-        #       self.headers['Conten-Type'] = 'text/plain'
-        #     end
-        #   end
-        #
-        # @abstract
-        # @return [void]
-        def run
-          raise NotImplementedError
-        end
-
-        protected
-
-        # @group Helper Methods
-
-        # Renders a specific object if provided, or a regular template rendering
-        # if object is not provided.
-        #
-        # @todo This method is dependent on +#options+, it should be in {LibraryCommand}.
-        # @param [CodeObjects::Base, nil] object calls {CodeObjects::Base#format} if
-        #   an object is provided, or {Templates::Engine.render} if object is nil. Both
-        #   receive +#options+ as an argument.
-        # @return [String] the resulting output to display
-        def render(object = nil)
-          case object
-          when CodeObjects::Base
-            cache object.format(options)
-          when nil
-            cache Templates::Engine.render(options)
-          else
-            cache object
-          end
-        end
-
-        # Override this method to implement custom caching mechanisms for
-        #
-        # @example Caching to memory
-        #   $memory_cache = {}
-        #   def cache(data)
-        #     $memory_cache[path] = data
-        #   end
-        # @param [String] data the data to cache
-        # @return [String] the same cached data (for chaining)
-        # @see StaticCaching
-        def cache(data)
-          if caching && adapter.document_root
-            path = File.join(adapter.document_root, request.path_info.sub(/\.html$/, '') + '.html')
-            path = path.sub(%r{/\.html$}, '.html')
-            FileUtils.mkdir_p(File.dirname(path))
-            log.debug "Caching data to #{path}"
-            File.open(path, 'wb') {|f| f.write(data) }
-          end
-          self.body = data
-        end
-
-        # Sets the body and headers for a 404 response. Does not modify the
-        # body if already set.
-        #
-        # @return [void]
-        def not_found
-          self.status = 404
-          return unless body.empty?
-          self.body = "Not found: #{request.path}"
-          headers['Content-Type'] = 'text/plain'
-          headers['X-Cascade'] = 'pass'
-          headers.delete('Cache-Control')
-        end
-
-        # Sets the headers and status code for a redirection to a given URL
-        # @param [String] url the URL to redirect to
-        # @raise [FinishRequest] causes the request to terminate.
-        def redirect(url)
-          headers['Location'] = url
-          self.status = 302
-          raise FinishRequest
-        end
-
-        private
-
-        # Add a conservative cache control policy to reduce load on
-        # requests served with "?1234567890" style timestamp query strings.
-        def add_cache_control
-          return if request.query_string.to_i == 0
-          headers['Cache-Control'] = 'private, max-age=300'
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+require 'fileutils'
+
+module YARD
+  module Server
+    module Commands
+      # This is the base command class used to implement custom commands for
+      # a server. A command will be routed to by the {Router} class and return
+      # a Rack-style response.
+      #
+      # == Attribute Initializers
+      # All attributes can be initialized via options passed into the {#initialize}
+      # method. When creating a custom command, the {Adapter#options} will
+      # automatically be mapped to attributes by the same name on your class.
+      #
+      #   class MyCommand < Base
+      #     attr_accessor :myattr
+      #   end
+      #
+      #   Adapter.new(libs, {:myattr => 'foo'}).start
+      #
+      #   # when a request comes in, cmd.myattr == 'foo'
+      #
+      # == Subclassing Notes
+      # To implement a custom command, override the {#run} method, not {#call}.
+      # In your implementation, you should set the body and status for requests.
+      # See details in the +#run+ method documentation.
+      #
+      # Note that if your command deals directly with libraries, you should
+      # consider subclassing the more specific {LibraryCommand} class instead.
+      #
+      # @abstract
+      # @see #run
+      class Base
+        # @group Basic Command and Adapter Options
+
+        # @return [Hash] the options passed to the command's constructor
+        attr_accessor :command_options
+
+        # @return [Adapter] the server adapter
+        attr_accessor :adapter
+
+        # @return [Boolean] whether to cache
+        attr_accessor :caching
+
+        # @group Attributes Set Per Request
+
+        # @return [Rack::Request] request object
+        attr_accessor :request
+
+        # @return [String] the path after the command base URI
+        attr_accessor :path
+
+        # @return [Hash{String => String}] response headers
+        attr_accessor :headers
+
+        # @return [Numeric] status code. Defaults to 200 per request
+        attr_accessor :status
+
+        # @return [String] the response body. Defaults to empty string.
+        attr_accessor :body
+
+        # @group Instance Method Summary
+
+        # Creates a new command object, setting attributes named by keys
+        # in the options hash. After initialization, the options hash
+        # is saved in {#command_options} for further inspection.
+        #
+        # @example Creating a Command
+        #   cmd = DisplayObjectCommand.new(:caching => true, :library => mylib)
+        #   cmd.library # => mylib
+        #   cmd.command_options # => {:caching => true, :library => mylib}
+        # @param [Hash] opts the options hash, saved to {#command_options}
+        #   after initialization.
+        def initialize(opts = {})
+          opts.each do |key, value|
+            send("#{key}=", value) if respond_to?("#{key}=")
+          end
+          self.command_options = opts
+        end
+
+        # The main method called by a router with a request object.
+        #
+        # @note This command should not be overridden by subclasses. Implement
+        #   the callback method {#run} instead.
+        # @param [Adapter Dependent] request the request object
+        # @return [Array(Numeric,Hash,Array<String>)] a Rack-style response
+        #   of status, headers, and body wrapped in an array.
+        def call(request)
+          self.request = request
+          self.path ||= request.path_info[1..-1]
+          self.headers = {'Content-Type' => 'text/html'}
+          self.body = ''
+          self.status = 200
+          add_cache_control
+          begin
+            run
+          rescue FinishRequest
+            nil # noop
+          rescue NotFoundError => e
+            self.body = e.message if e.message != e.class.to_s
+            not_found
+          end
+
+          # keep this to support commands setting status manually.
+          not_found if status == 404
+
+          [status, headers, body.is_a?(Array) ? body : [body]]
+        end
+
+        # @group Abstract Methods
+
+        # Subclass this method to implement a custom command. This method
+        # should set the {#status} and {#body}, and optionally modify the
+        # {#headers}. Note that +#status+ defaults to 200.
+        #
+        # @example A custom command
+        #   class ErrorCommand < Base
+        #     def run
+        #       self.body = 'ERROR! The System is down!'
+        #       self.status = 500
+        #       self.headers['Conten-Type'] = 'text/plain'
+        #     end
+        #   end
+        #
+        # @abstract
+        # @return [void]
+        def run
+          raise NotImplementedError
+        end
+
+        protected
+
+        # @group Helper Methods
+
+        # Renders a specific object if provided, or a regular template rendering
+        # if object is not provided.
+        #
+        # @todo This method is dependent on +#options+, it should be in {LibraryCommand}.
+        # @param [CodeObjects::Base, nil] object calls {CodeObjects::Base#format} if
+        #   an object is provided, or {Templates::Engine.render} if object is nil. Both
+        #   receive +#options+ as an argument.
+        # @return [String] the resulting output to display
+        def render(object = nil)
+          case object
+          when CodeObjects::Base
+            cache object.format(options)
+          when nil
+            cache Templates::Engine.render(options)
+          else
+            cache object
+          end
+        end
+
+        # Override this method to implement custom caching mechanisms for
+        #
+        # @example Caching to memory
+        #   $memory_cache = {}
+        #   def cache(data)
+        #     $memory_cache[path] = data
+        #   end
+        # @param [String] data the data to cache
+        # @return [String] the same cached data (for chaining)
+        # @see StaticCaching
+        def cache(data)
+          if caching && adapter.document_root
+            path = File.join(adapter.document_root, request.path_info.sub(/\.html$/, '') + '.html')
+            path = path.sub(%r{/\.html$}, '.html')
+            FileUtils.mkdir_p(File.dirname(path))
+            log.debug "Caching data to #{path}"
+            File.open(path, 'wb') {|f| f.write(data) }
+          end
+          self.body = data
+        end
+
+        # Sets the body and headers for a 404 response. Does not modify the
+        # body if already set.
+        #
+        # @return [void]
+        def not_found
+          self.status = 404
+          return unless body.empty?
+          self.body = "Not found: #{request.path}"
+          headers['Content-Type'] = 'text/plain'
+          headers['X-Cascade'] = 'pass'
+          headers.delete('Cache-Control')
+        end
+
+        # Sets the headers and status code for a redirection to a given URL
+        # @param [String] url the URL to redirect to
+        # @raise [FinishRequest] causes the request to terminate.
+        def redirect(url)
+          headers['Location'] = url
+          self.status = 302
+          raise FinishRequest
+        end
+
+        private
+
+        # Add a conservative cache control policy to reduce load on
+        # requests served with "?1234567890" style timestamp query strings.
+        def add_cache_control
+          return if request.query_string.to_i == 0
+          headers['Cache-Control'] = 'private, max-age=300'
+        end
+      end
+    end
+  end
+end