yard 0.5.8 → 0.6.0

data/lib/yard/registry_store.rb

@@ -11,11 +11,13 @@ module YARD
     def initialize
       @file = nil
       @checksums = {}
-      @store = { :root => CodeObjects::RootObject.new(nil, :root) }
+      @store = {}
       @proxy_types = {}
       @notfound = {}
       @loaded_objects = 0
       @available_objects = 0
+      @store[:root] = CodeObjects::RootObject.allocate
+      @store[:root].send(:initialize, nil, :root)
     end
     
     # Gets a {CodeObjects::Base} from the store
@@ -94,6 +96,7 @@ module YARD
     # @param [String, nil] file the name of the yardoc db to load
     # @return [Boolean] whether the database was loaded
     # @see #load_all
+    # @since 0.5.1
     def load!(file = nil)
       if load(file)
         load_all
@@ -180,7 +183,6 @@ module YARD
     def load_yardoc
       return false unless @file
       if File.directory?(@file) # new format
-        Registry.objects.replace({})
         @loaded_objects = 0
         @available_objects = all_disk_objects.size
         load_proxy_types

data/lib/yard/serializers/base.rb

@@ -19,6 +19,8 @@ module YARD
       # @return [SymbolHash] the serializer options
       attr_reader :options
       
+      # @group Creating a New Serializer
+      
       # Creates a new serializer with options
       # 
       # @param [Hash] opts the options to assign to {#options}
@@ -26,19 +28,7 @@ module YARD
         @options = SymbolHash.new(false).update(opts)
       end
       
-      # Called before serialization. 
-      # 
-      # @abstract Should run code before serialization. Should return false
-      #   if serialization should not occur.
-      # @return [Boolean] whether or not serialization should occur
-      def before_serialize; end
-      
-      # Called after serialization. 
-      # 
-      # @abstract Should run code after serialization.
-      # @param [String] data the data that was serialized.
-      # @return [void]
-      def after_serialize(data); end
+      # @group Serializing an Object
       
       # Serializes an object.
       # 
@@ -58,6 +48,33 @@ module YARD
       # @param [CodeObjects::Base] object the object to return a path for
       # @return [String] the serialized path of an object
       def serialized_path(object) end
+        
+      # Returns whether an object has been serialized
+      # 
+      # @abstract This method should return whether the endpoint already exists.
+      #   For instance, a file system serializer would check if the file exists
+      #   on disk. You will most likely use +#basepath+ and {#serialized_path} to 
+      #   get the endpoint's location.
+      # @param [CodeObjects::Base] object the object to check existence of
+      # @return [Boolean] whether the endpoint exists.
+      # @since 0.6.0
+      def exists?(object) false end
+
+      # @group Callbacks
+
+      # Called before serialization. 
+      # 
+      # @abstract Should run code before serialization. Should return false
+      #   if serialization should not occur.
+      # @return [Boolean] whether or not serialization should occur
+      def before_serialize; end
+
+      # Called after serialization. 
+      # 
+      # @abstract Should run code after serialization.
+      # @param [String] data the data that was serialized.
+      # @return [void]
+      def after_serialize(data); end
     end
   end
 end

data/lib/yard/serializers/file_system_serializer.rb

@@ -1,5 +1,6 @@
 module YARD
   module Serializers
+    # Implements a serializer that reads from and writes to the filesystem.
     class FileSystemSerializer < Base
       # The base path to write data to.
       # @return [String] a base path
@@ -29,7 +30,7 @@ module YARD
         @extension = (options.has_key?(:extension) ? options[:extension] : 'html').to_s
       end
       
-      # Serializes object with data to its serialized path (prefixed by the {#basepath}).
+      # Serializes object with data to its serialized path (prefixed by the +#basepath+).
       # 
       # @return [String] the written data (for chaining)
       def serialize(object, data)
@@ -74,6 +75,14 @@ module YARD
         
         File.join(fspath)
       end
+      
+      # Checks the disk for an object and returns whether it was serialized.
+      # 
+      # @param [CodeObjects::Base] object the object to check
+      # @return [Boolean] whether an object has been serialized to disk
+      def exists?(object)
+        File.exist?(File.join(basepath, serialized_path(object)))
+      end
     end
   end
 end

data/lib/yard/server/adapter.rb

@@ -0,0 +1,51 @@
+module YARD
+  module Server
+    class FinishRequest < RuntimeError; end
+    class NotFoundError < RuntimeError; end
+
+    class Adapter
+      # @return [String] the location where static files are located, if any
+      attr_accessor :document_root
+      
+      attr_accessor :libraries
+      
+      attr_accessor :options
+      
+      attr_accessor :server_options
+      
+      attr_accessor :router
+
+      def self.setup
+        Templates::Template.extra_includes |= [YARD::Server::DocServerHelper]
+        Templates::Engine.template_paths |= [File.dirname(__FILE__) + '/templates']
+      end
+
+      def self.shutdown
+        Templates::Template.extra_includes -= [YARD::Server::DocServerHelper]
+        Templates::Engine.template_paths -= [File.dirname(__FILE__) + '/templates']
+      end
+      
+      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
+      
+      def add_library(library)
+        libraries[library.name] ||= []
+        libraries[library.name] |= [library]
+      end
+      
+      def start
+        raise NotImplementedError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+require 'fileutils'
+
+module YARD
+  module Server
+    module Commands
+      class Base
+        # @return [Hash] the options passed to the command's constructor
+        attr_accessor :command_options
+        
+        # @return [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
+        attr_accessor :status
+
+        # @return [String] the response body
+        attr_accessor :body
+        
+        # @return [Adapter] the server adapter
+        attr_accessor :adapter
+        
+        # @return [Boolean] whether to cache
+        attr_accessor :caching
+
+        def initialize(opts = {})
+          opts.each do |key, value|
+            send("#{key}=", value) if respond_to?("#{key}=")
+          end
+          self.command_options = opts
+        end
+
+        def call(request)
+          self.request = request
+          self.path ||= request.path[1..-1]
+          self.headers = {'Content-Type' => 'text/html'}
+          self.body = ''
+          self.status = 200
+          begin
+            run
+          rescue FinishRequest
+          rescue NotFoundError => e
+            self.body = e.message if e.message != e.class.to_s
+            self.status = 404
+          end
+          not_found if status == 404
+          [status, headers, body.is_a?(Array) ? body : [body]]
+        end
+
+        def run
+          raise NotImplementedError
+        end
+        
+        def not_found
+          return unless body.empty?
+          self.body = "Not found: #{request.path}"
+          self.headers['Content-Type'] = 'text/plain'
+          self.headers['X-Cascade'] = 'pass'
+        end
+        
+        protected
+        
+        def cache(data)
+          if caching && adapter.document_root
+            path = File.join(adapter.document_root, request.path.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
+
+        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
+
+        def redirect(url)
+          headers['Location'] = url
+          self.status = 302
+          raise FinishRequest
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module YARD
+  module Server
+    module Commands
+      class DisplayFileCommand < LibraryCommand
+        def run
+          ppath = library.source_path
+          filename = File.cleanpath(File.join(library.source_path, path))
+          raise NotFoundError if !File.file?(filename)
+          if filename =~ /\.(jpe?g|gif|png|bmp)$/i
+            headers['Content-Type'] = StaticFileCommand::DefaultMimeTypes[$1.downcase] || 'text/html'
+            render IO.read(filename)
+          else
+            options.update(:object => Registry.root, :type => :layout, :file => filename)
+            render
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module YARD
+  module Server
+    module Commands
+      class DisplayObjectCommand < LibraryCommand
+        def run
+          return index if path.empty?
+          
+          if object = Registry.at(object_path)
+            options.update(:type => :layout)
+            render(object)
+          else
+            self.status = 404
+          end
+        end
+        
+        def index
+          Registry.load_all
+
+          title = options[:title]
+          unless title
+            title = "Documentation for #{library.name} #{library.version ? '(' + library.version + ')' : ''}"
+          end
+          options.update(
+            :object => '_index.html',
+            :objects => Registry.all(:module, :class),
+            :title => title,
+            :type => :layout
+          )
+          render
+        end
+        
+        def not_found
+          super
+          self.body = "Could not find object: #{object_path}"
+        end
+        
+        private
+        
+        def object_path
+          return @object_path if @object_path
+          if path == "toplevel"
+            @object_path = :root
+          else
+            @object_path = path.sub(':', '#').gsub('/', '::').sub(/^toplevel\b/, '').sub(/\.html$/, '')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module YARD
+  module Server
+    module Commands
+      class FramesCommand < DisplayObjectCommand
+        include DocServerHelper
+        
+        def run
+          main_url = request.path.gsub(/^(.+)?\/frames\/(#{path})$/, '\1/\2')
+          if path =~ %r{^file/}
+            page_title = "File: #{$'}"
+          elsif !path.empty?
+            page_title = "Object: #{object_path}"
+          elsif options[:files] && options[:files].size > 0
+            page_title = "File: #{options[:files].first.sub(/^#{library.source_path}\/?/, '')}"
+            main_url = url_for_file(options[:files].first)
+          elsif !path || path.empty?
+            page_title = "Documentation for #{library.name} #{library.version ? '(' + library.version + ')' : ''}"
+          end
+
+          options.update(
+            :page_title => page_title,
+            :main_url => main_url,
+            :template => :doc_server,
+            :type => :frames
+          )
+          render
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+module YARD
+  module Server
+    module Commands
+      class LibraryCommand < Base
+        # @return [LibraryVersion] the object containing library information
+        attr_accessor :library
+
+        # @return [Hash{Symbol => Object}] default options for the library
+        attr_accessor :options
+
+        # @return [Serializers::Base] the serializer used to perform file linking
+        attr_accessor :serializer
+
+        # @return [Boolean] whether router should route for multiple libraries
+        attr_accessor :single_library
+        
+        # @return [Boolean] whether to reparse data 
+        attr_accessor :incremental
+        
+        def initialize(opts = {})
+          super
+          self.serializer = DocServerSerializer.new(self)
+        end
+
+        def call(request)
+          self.options = SymbolHash.new(false).update(
+            :serialize => false,
+            :serializer => serializer,
+            :library => library,
+            :adapter => adapter,
+            :single_library => single_library,
+            :markup => :rdoc,
+            :format => :html
+          )
+          setup_library
+          super
+        rescue LibraryNotPreparedError
+          not_prepared(request)
+        end
+
+        private
+
+        def setup_library
+          library.prepare!
+          load_yardoc
+          setup_yardopts
+          true
+        end
+
+        def setup_yardopts
+          Dir.chdir(library.source_path)
+          yardoc = CLI::Yardoc.new
+          if incremental
+            yardoc.run('-c', '-n', '--no-stats')
+          else
+            yardoc.parse_arguments
+          end
+          yardoc.options.delete(:serializer)
+          yardoc.options[:files].unshift(*Dir.glob(library.source_path + '/README*'))
+          options.update(yardoc.options.to_hash)
+        end
+
+        def load_yardoc
+          if @@last_yardoc == library.yardoc_file
+            log.debug "Reusing yardoc file: #{library.yardoc_file}"
+            return
+          end
+          Registry.clear
+          Registry.load_yardoc(library.yardoc_file)
+          @@last_yardoc = library.yardoc_file
+        end
+        
+        def not_prepared(request)
+          self.caching = false
+          options.update(:path => request.path, :template => :doc_server, :type => :processing)
+          [302, {'Content-Type' => 'text/html'}, [render]]
+        end
+        
+        @@last_yardoc = nil
+      end
+    end
+  end
+end