Class: YARD::Server::LibraryVersion

### Home Classes Methods

### In Files

- lib/yard/server/library_version.rb

### Parent

Object

### Methods

- ::new
- #==
- #eql?
- #equal?
- #gemspec
- #hash
- #load_yardoc_from_disk
- #load_yardoc_from_gem
- #prepare!
- #source_path_for_disk
- #source_path_for_gem
- #to_s

### Files

- LICENSE.txt
- MIT.txt

### Class/Module Index

Quicksearch

- YARD
- YARD::CLI
- YARD::CLI::Command
- YARD::CLI::CommandParser
- YARD::CLI::Config
- YARD::CLI::Diff
- YARD::CLI::Display
- YARD::CLI::Gems
- YARD::CLI::Graph
- YARD::CLI::GraphOptions
- YARD::CLI::Help
- YARD::CLI::I18n
- YARD::CLI::List
- YARD::CLI::MarkupTypes
- YARD::CLI::Server
- YARD::CLI::Stats
- YARD::CLI::YRI
- YARD::CLI::Yardoc
- YARD::CLI::YardocOptions
- YARD::CLI::YardoptsCommand
- YARD::CodeObjects
- YARD::CodeObjects::Base
- YARD::CodeObjects::ClassObject
- YARD::CodeObjects::ClassVariableObject
- YARD::CodeObjects::CodeObjectList
- YARD::CodeObjects::ConstantObject
- YARD::CodeObjects::ExtendedMethodObject
- YARD::CodeObjects::ExtraFileObject
- YARD::CodeObjects::MacroObject
- YARD::CodeObjects::MethodObject
- YARD::CodeObjects::ModuleObject
- YARD::CodeObjects::NamespaceObject
- YARD::CodeObjects::Proxy
- YARD::CodeObjects::ProxyMethodError
- YARD::CodeObjects::RootObject
- YARD::Config
- YARD::Docstring
- YARD::DocstringParser
- YARD::Handlers
- YARD::Handlers::Base
- YARD::Handlers::C
- YARD::Handlers::C::AliasHandler
- YARD::Handlers::C::AttributeHandler
- YARD::Handlers::C::Base
- YARD::Handlers::C::ClassHandler
- YARD::Handlers::C::ConstantHandler
- YARD::Handlers::C::HandlerMethods
- YARD::Handlers::C::InitHandler
- YARD::Handlers::C::MethodHandler
- YARD::Handlers::C::MixinHandler
- YARD::Handlers::C::ModuleHandler
- YARD::Handlers::C::OverrideCommentHandler
- YARD::Handlers::C::PathHandler
- YARD::Handlers::C::StructHandler
- YARD::Handlers::C::SymbolHandler
- YARD::Handlers::HandlerAborted
- YARD::Handlers::NamespaceMissingError
- YARD::Handlers::Processor
- YARD::Handlers::Ruby
- YARD::Handlers::Ruby::AliasHandler
- YARD::Handlers::Ruby::AttributeHandler
- YARD::Handlers::Ruby::Base
- YARD::Handlers::Ruby::ClassConditionHandler
- YARD::Handlers::Ruby::ClassHandler
- YARD::Handlers::Ruby::ClassVariableHandler
- YARD::Handlers::Ruby::CommentHandler
- YARD::Handlers::Ruby::ConstantHandler
- YARD::Handlers::Ruby::DSLHandler
- YARD::Handlers::Ruby::DSLHandlerMethods
- YARD::Handlers::Ruby::ExceptionHandler
- YARD::Handlers::Ruby::ExtendHandler
- YARD::Handlers::Ruby::HandlesExtension
- YARD::Handlers::Ruby::Legacy
- YARD::Handlers::Ruby::Legacy::AliasHandler
- YARD::Handlers::Ruby::Legacy::AttributeHandler
- YARD::Handlers::Ruby::Legacy::Base
- YARD::Handlers::Ruby::Legacy::ClassConditionHandler
- YARD::Handlers::Ruby::Legacy::ClassHandler
- YARD::Handlers::Ruby::Legacy::ClassVariableHandler
- YARD::Handlers::Ruby::Legacy::CommentHandler
- YARD::Handlers::Ruby::Legacy::ConstantHandler
- YARD::Handlers::Ruby::Legacy::DSLHandler
- YARD::Handlers::Ruby::Legacy::ExceptionHandler
- YARD::Handlers::Ruby::Legacy::ExtendHandler
- YARD::Handlers::Ruby::Legacy::MethodHandler
- YARD::Handlers::Ruby::Legacy::MixinHandler
- YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler
- YARD::Handlers::Ruby::Legacy::ModuleHandler
- YARD::Handlers::Ruby::Legacy::PrivateClassMethodHandler
- YARD::Handlers::Ruby::Legacy::PrivateConstantHandler
- YARD::Handlers::Ruby::Legacy::VisibilityHandler
- YARD::Handlers::Ruby::Legacy::YieldHandler
- YARD::Handlers::Ruby::MethodCallWrapper
- YARD::Handlers::Ruby::MethodConditionHandler
- YARD::Handlers::Ruby::MethodHandler
- YARD::Handlers::Ruby::MixinHandler
- YARD::Handlers::Ruby::ModuleFunctionHandler
- YARD::Handlers::Ruby::ModuleHandler
- YARD::Handlers::Ruby::PrivateClassMethodHandler
- YARD::Handlers::Ruby::PrivateConstantHandler
- YARD::Handlers::Ruby::StructHandlerMethods
- YARD::Handlers::Ruby::TestNodeWrapper
- YARD::Handlers::Ruby::VisibilityHandler
- YARD::Handlers::Ruby::YieldHandler
- YARD::I18n
- YARD::I18n::Locale
- YARD::I18n::Message
- YARD::I18n::Messages
- YARD::I18n::POParser
- YARD::I18n::PotGenerator
- YARD::I18n::Text
- YARD::Logger
- YARD::Options
- YARD::Parser
- YARD::Parser::Base
- YARD::Parser::C
- YARD::Parser::C::BodyStatement
- YARD::Parser::C::CParser
- YARD::Parser::C::Comment
- YARD::Parser::C::CommentParser
- YARD::Parser::C::Statement
- YARD::Parser::C::ToplevelStatement
- YARD::Parser::OrderedParser
- YARD::Parser::ParserSyntaxError
- YARD::Parser::Ruby
- YARD::Parser::Ruby::AstNode
- YARD::Parser::Ruby::ClassNode
- YARD::Parser::Ruby::CommentNode
- YARD::Parser::Ruby::ConditionalNode
- YARD::Parser::Ruby::KeywordNode
- YARD::Parser::Ruby::Legacy
- YARD::Parser::Ruby::Legacy::RubyLex
- YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
- YARD::Parser::Ruby::Legacy::RubyParser
- YARD::Parser::Ruby::Legacy::RubyToken
- YARD::Parser::Ruby::Legacy::RubyToken::TkBlockContents
- YARD::Parser::Ruby::Legacy::RubyToken::TkError
- YARD::Parser::Ruby::Legacy::RubyToken::TkId
- YARD::Parser::Ruby::Legacy::RubyToken::TkKW
- YARD::Parser::Ruby::Legacy::RubyToken::TkNode
- YARD::Parser::Ruby::Legacy::RubyToken::TkOPASGN
- YARD::Parser::Ruby::Legacy::RubyToken::TkOp
- YARD::Parser::Ruby::Legacy::RubyToken::TkStatementEnd
- YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar
- YARD::Parser::Ruby::Legacy::RubyToken::TkVal
- YARD::Parser::Ruby::Legacy::RubyToken::TkWhitespace
- YARD::Parser::Ruby::Legacy::RubyToken::Token
- YARD::Parser::Ruby::Legacy::Statement
- YARD::Parser::Ruby::Legacy::StatementList
- YARD::Parser::Ruby::Legacy::TokenList
- YARD::Parser::Ruby::LiteralNode
- YARD::Parser::Ruby::LoopNode
- YARD::Parser::Ruby::MethodCallNode
- YARD::Parser::Ruby::MethodDefinitionNode
- YARD::Parser::Ruby::ModuleNode
- YARD::Parser::Ruby::ParameterNode
- YARD::Parser::Ruby::ReferenceNode
- YARD::Parser::Ruby::RipperParser
- YARD::Parser::Ruby::RubyParser
- YARD::Parser::SourceParser
- YARD::Parser::UndocumentableError
- YARD::Rake
- YARD::Rake::YardocTask
- YARD::Registry
- YARD::RegistryStore
- YARD::Serializers
- YARD::Serializers::Base
- YARD::Serializers::FileSystemSerializer
- YARD::Serializers::ProcessSerializer
- YARD::Serializers::StdoutSerializer
- YARD::Serializers::YardocSerializer
- YARD::Server
- YARD::Server::Adapter
- YARD::Server::Commands
- YARD::Server::Commands::Base
- YARD::Server::Commands::DisplayFileCommand
- YARD::Server::Commands::DisplayObjectCommand
- YARD::Server::Commands::FramesCommand
- YARD::Server::Commands::LibraryCommand
- YARD::Server::Commands::LibraryIndexCommand
- YARD::Server::Commands::LibraryOptions
- YARD::Server::Commands::ListCommand
- YARD::Server::Commands::SearchCommand
- YARD::Server::Commands::StaticFileCommand
- YARD::Server::DocServerHelper
- YARD::Server::DocServerSerializer
- YARD::Server::FinishRequest
- YARD::Server::LibraryNotPreparedError
- YARD::Server::LibraryVersion
- YARD::Server::NotFoundError
- YARD::Server::RackAdapter
- YARD::Server::RackMiddleware
- YARD::Server::Router
- YARD::Server::StaticCaching
- YARD::Server::WebrickAdapter
- YARD::Server::WebrickServlet
- YARD::StubProxy
- YARD::Tags
- YARD::Tags::AttributeDirective
- YARD::Tags::DefaultFactory
- YARD::Tags::DefaultTag
- YARD::Tags::Directive
- YARD::Tags::EndGroupDirective
- YARD::Tags::GroupDirective
- YARD::Tags::Library
- YARD::Tags::MacroDirective
- YARD::Tags::MethodDirective
- YARD::Tags::OptionTag
- YARD::Tags::OverloadTag
- YARD::Tags::ParseDirective
- YARD::Tags::RefTag
- YARD::Tags::RefTagList
- YARD::Tags::ScopeDirective
- YARD::Tags::Tag
- YARD::Tags::TagFormatError
- YARD::Tags::VisibilityDirective
- YARD::Templates
- YARD::Templates::Engine
- YARD::Templates::ErbCache
- YARD::Templates::Helpers
- YARD::Templates::Helpers::BaseHelper
- YARD::Templates::Helpers::FilterHelper
- YARD::Templates::Helpers::HtmlHelper
- YARD::Templates::Helpers::HtmlSyntaxHighlightHelper
- YARD::Templates::Helpers::Markup
- YARD::Templates::Helpers::Markup::RDocMarkdown
- YARD::Templates::Helpers::Markup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::MarkupHelper
- YARD::Templates::Helpers::MethodHelper
- YARD::Templates::Helpers::ModuleHelper
- YARD::Templates::Helpers::TextHelper
- YARD::Templates::Helpers::UMLHelper
- YARD::Templates::Section
- YARD::Templates::Template
- YARD::Templates::Template::ClassMethods
- YARD::Templates::TemplateOptions
- YARD::Verifier
- Gem
- Gem::DocManager
- Gem::SourceIndex
- Gem::Specification
- Rack
- Rack::Request
- WEBrick
- WEBrick::HTTPRequest
- Array
- File
- Hash
- Insertion
- Module
- Object
- String
- SymbolHash

No matching classes.

# YARD::Server::LibraryVersion

A library version encapsulates a library's documentation at a specific version. Although the version is optional, this allows for creating multiple documentation points for a specific library, each representing a unique version. The term "library" used in other parts of the YARD::Server documentation refers to objects of this class unless otherwise noted.

A library points to a location where a {yardoc_file} is located so that its documentation may be loaded and served. Optionally, a {source_path} is given to point to a location where any extra files (and {YARD::CLI::Yardoc .yardopts}) should be loaded from. Both of these methods may not be known immediately, since the yardoc file may not be built until later. Resolving the yardoc file and source path are dependent on the specific library "source type" used. Source types (known as "library source") are discussed in detail below.

## Using with Adapters

A list of libraries need to be passed into adapters upon creation. In most cases, you will never do this manually, but if you use a {RackMiddleware}, you will need to pass in this list yourself. To build this list of libraries, you should create a hash of library names mapped to an Array of LibraryVersion objects. For example:

    {'mylib' => [LibraryVersion.new('mylib', '1.0', ...),
                 LibraryVersion.new('mylib', '2.0', ...)]}

Note that you can also use {Adapter#add_library} for convenience.

The "array" part is required, even for just one library version.

## Library Sources

The {source} method represents the library source type, ie. where the library "comes from". It might come from "disk", or it might come from a "gem" (technically the disk, but a separate type nonetheless). In these two cases, the yardoc file sits somewhere on your filesystem, though it may also be built dynamically if it does not yet exist. This behaviour is controlled through the {prepare!} method, which prepares the yardoc file given a specific library source. We will see how this works in detail in the following section.

## Implementing a Custom Library Source

YARD can be extended to support custom library sources in order to build or retrieve a yardoc file at runtime from many different locations.

To implement this behaviour, two methods must be added to the `LibraryVersion` class, `#load_yardoc_from_SOURCE` and `#source_path_for_SOURCE`. In both cases, "SOURCE" represents the source type used in {source} when creating the library object. The `#source_path_for_SOURCE` method is called upon creation and should return the location where the source code for the library lives. The load method is called from {prepare!} if there is no yardoc file and should set {yardoc_file}. Below is a full example for implementing a custom library source, `:http`, which reads packaged .yardoc databases from zipped archives off of an HTTP server.

@example Implementing a Custom Library Source

    # Adds the source type "http" for .yardoc files zipped on HTTP servers
    class LibraryVersion
      def load_yardoc_from_http
        return if yardoc_file # we have the library

        # otherwise download it in a thread and return immediately
        Thread.new do
          # zip/unzip method implementations are not shown
          download_zip_file("http://mysite.com/yardocs/#{self}.zip")
          unzip_file_to("/path/to/yardocs/#{self}")
          self.yardoc_file = "/path/to/yardocs/#{self}/.yardoc"
          self.source_path = self.yardoc_file
        end

        # tell the server it's not ready yet (but it might be next time)
        raise LibraryNotPreparedError
      end

      # we set this later
      def source_path_for_http; nil end
    end

    # Creating a library of this source type:
    LibraryVersion.new('name', '1.0', nil, :http)

### Attributes

name[RW]

@return [String] the name of the library

source[RW]

@return [Symbol] the source type representing where the yardoc should be

    loaded from. Defaults are +:disk+ and +:gem+, though custom sources
    may be implemented. This value is used to inform {#prepare!} about how
    to load the necessary data in order to display documentation for an object.

@see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"

source_path[RW]

@return [String] the location of the source code for a library. This

    value is filled by calling +#source_path_for_SOURCE+ on this class.

@return [nil] if there is no source code @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"

version[RW]

@return [String] the version of the specific library

yardoc_file[RW]

@return [String] the location of the yardoc file used to load the object

    information from.

@return [nil] if no yardoc file exists yet. In this case, {prepare!} will

    be called on this library to build the yardoc file.

### Public Class Methods

new(name, version = nil, yardoc = nil, source = :disk) click to toggle source

@param [String] name the name of the library @param [String] version the specific (usually, but not always, numeric) library

    version

@param [String] yardoc the location of the yardoc file, or nil if it is

    generated later

@param [Symbol] source the location of the files used to build the yardoc.

    Builtin source types are +:disk+ or +:gem+.

    # File lib/yard/server/library_version.rb, line 120
    def initialize(name, version = nil, yardoc = nil, source = :disk)
      self.name = name
      self.yardoc_file = yardoc
      self.version = version
      self.source = source
      self.source_path = load_source_path
    end

### Public Instance Methods

==(other) click to toggle source
Alias for: eql?
eql?(other) click to toggle source

@return [Boolean] whether another LibraryVersion is equal to this one

    # File lib/yard/server/library_version.rb, line 140
    def eql?(other)
      other.is_a?(LibraryVersion) && other.name == name &&
        other.version == version && other.yardoc_file == yardoc_file
    end

Also aliased as: ==, equal?
equal?(other) click to toggle source
Alias for: eql?
gemspec() click to toggle source

@return [Gem::Specification] a gemspec object for a given library. Used

    for :gem source types.

@return [nil] if there is no installed gem for the library

    # File lib/yard/server/library_version.rb, line 171
    def gemspec
      ver = version ? "= #{version}" : ">= 0"
      Gem.source_index.find_name(name, ver).first
    end

hash() click to toggle source

@return [Fixnum] used for Hash mapping.

    # File lib/yard/server/library_version.rb, line 137
    def hash; to_s.hash end

prepare!() click to toggle source

@note You should not directly override this method. Instead, implement

    +load_yardoc_from_SOURCENAME+ when implementing loading for a specific
    source type. See the {LibraryVersion} documentation for "Implementing
    a Custom Library Source"

Prepares a library to be displayed by the server. This callback is performed before each request on a library to ensure that it is loaded and ready to be viewed. If any steps need to be performed prior to loading, they are performed through this method (though they should be implemented through the `load_yardoc_from_SOURCE` method).

@raise [LibraryNotPreparedError] if the library is not ready to be

    displayed. Usually when raising this error, you would simultaneously
    begin preparing the library for subsequent requests, although this
    is not necessary.

    # File lib/yard/server/library_version.rb, line 162
    def prepare!
      return if yardoc_file
      meth = "load_yardoc_from_#{source}"
      send(meth) if respond_to?(meth, true)
    end

to_s(url_format = true) click to toggle source

@param [Boolean] url_format if true, returns the string in a URI-compatible

    format (for appending to a URL). Otherwise, it is given in a more human
    readable format.

@return [String] the string representation of the library.

    # File lib/yard/server/library_version.rb, line 132
    def to_s(url_format = true)
      version ? "#{name}#{url_format ? '/' : '-'}#{version}" : "#{name}"
    end

### Protected Instance Methods

load_yardoc_from_disk() click to toggle source

Called when a library of source type "disk" is to be prepared. In this case, the {yardoc_file} should already be set, so nothing needs to be done.

    # File lib/yard/server/library_version.rb, line 181
    def load_yardoc_from_disk
      nil
    end

load_yardoc_from_gem() click to toggle source

Called when a library of source type "gem" is to be prepared. In this case, the {yardoc_file} needs to point to the correct location for the installed gem. The yardoc file is built if it has not been done.

@raise [LibraryNotPreparedError] if the gem does not have an existing

    yardoc file.

    # File lib/yard/server/library_version.rb, line 191
    def load_yardoc_from_gem
      require 'rubygems'
      ver = version ? "= #{version}" : ">= 0"
      self.yardoc_file = Registry.yardoc_file_for_gem(name, ver)
      unless yardoc_file && File.directory?(yardoc_file)
        Thread.new do
          # Build gem docs on demand
          log.debug "Building gem docs for #{to_s(false)}"
          CLI::Gems.run(name, ver)
          self.yardoc_file = Registry.yardoc_file_for_gem(name, ver)
          FileUtils.touch(File.join(yardoc_file, 'complete'))
        end
      end
      unless yardoc_file && File.exist?(File.join(yardoc_file, 'complete'))
        raise LibraryNotPreparedError
      end
    end

source_path_for_disk() click to toggle source

@return [String] the source path for a disk source

    # File lib/yard/server/library_version.rb, line 210
    def source_path_for_disk
      File.dirname(yardoc_file) if yardoc_file
    end

source_path_for_gem() click to toggle source

@return [String] the source path for a gem source

    # File lib/yard/server/library_version.rb, line 215
    def source_path_for_gem
      gemspec.full_gem_path if gemspec
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.