class YARD::CLI::YRI

A tool to view documentation in the console like `ri`

Constants

CACHE_FILE

The location in {YARD::CONFIG_DIR} where the YRI cache file is loaded from.

DEFAULT_SEARCH_PATHS

Default search paths that should be loaded dynamically into YRI. These paths take precedence over all other paths ({SEARCH_PATHS_FILE} and RubyGems paths). To add a path, call:

DEFAULT_SEARCH_PATHS.push("/path/to/.yardoc")

@return [Array<String>] a list of extra search paths @since 0.6.0

SEARCH_PATHS_FILE

A file containing all paths, delimited by newlines, to search for yardoc databases. @since 0.5.1

Public Class Methods

new() click to toggle source
Calls superclass method
# File lib/yard/cli/yri.rb, line 31
def initialize
  super
  @cache = {}
  @search_paths = []
  add_default_paths
  add_gem_paths
  load_cache
  @search_paths.uniq!
end
run(*args) click to toggle source

Helper method to run the utility on an instance. @see run

# File lib/yard/cli/yri.rb, line 29
def self.run(*args) new.run(*args) end

Public Instance Methods

description() click to toggle source
# File lib/yard/cli/yri.rb, line 41
def description
  "A tool to view documentation in the console like `ri`"
end
run(*args) click to toggle source

Runs the command-line utility.

@example

YRI.new.run('String#reverse')

@param [Array<String>] args each tokenized argument

# File lib/yard/cli/yri.rb, line 50
def run(*args)
  optparse(*args)

  if ::RbConfig::CONFIG['host_os'] =~ /mingw|win32/
    @serializer ||= YARD::Serializers::StdoutSerializer.new
  else
    @serializer ||= YARD::Serializers::ProcessSerializer.new('less')
  end

  if @name.nil? || @name.strip.empty?
    print_usage
    return exit(1)
  end

  object = find_object(@name)
  if object
    print_object(object)
  else
    STDERR.puts "No documentation for `#{@name}'"
    return exit(1)
  end
end

Protected Instance Methods

cache_object(name, path) click to toggle source

Caches the .yardoc file where an object can be found in the {CACHE_FILE} @return [void]

# File lib/yard/cli/yri.rb, line 85
def cache_object(name, path)
  return if path == Registry.yardoc_file
  @cache[name] = path

  File.open!(CACHE_FILE, 'w') do |file|
    @cache.each do |key, value|
      file.puts("#{key} #{value}")
    end
  end
end
find_object(name) click to toggle source

Locates an object by name starting in the cached paths and then searching through any search paths.

@param [String] name the full name of the object @return [CodeObjects::Base] an object if found @return [nil] if no object is found

# File lib/yard/cli/yri.rb, line 113
def find_object(name)
  @search_paths.unshift(@cache[name]) if @cache[name]
  @search_paths.unshift(Registry.yardoc_file)

  # Try to load it from in memory cache
  log.debug "Searching for #{name} in memory"
  obj = try_load_object(name, nil)
  return obj if obj

  log.debug "Searching for #{name} in search paths"
  @search_paths.each do |path|
    next unless File.exist?(path)
    log.debug "Searching for #{name} in #{path}..."
    Registry.load(path)
    obj = try_load_object(name, path)
    return obj if obj
  end
  nil
end
print_object(object) click to toggle source

@param [CodeObjects::Base] object the object to print. @return [String] the formatted output for an object.

print_usage() click to toggle source

Prints the command usage @return [void] @since 0.5.6

Private Instance Methods

add_default_paths() click to toggle source

Adds paths in {SEARCH_PATHS_FILE} @since 0.5.1

# File lib/yard/cli/yri.rb, line 181
def add_default_paths
  @search_paths.concat(DEFAULT_SEARCH_PATHS)
  return unless File.file?(SEARCH_PATHS_FILE)
  paths = File.readlines(SEARCH_PATHS_FILE).map(&:strip)
  @search_paths.concat(paths)
end
add_gem_paths() click to toggle source

Adds all RubyGems yardoc files to search paths @return [void]

# File lib/yard/cli/yri.rb, line 161
def add_gem_paths
  require 'rubygems'
  gem_paths = []
  YARD::GemIndex.each do |spec|
    yfile = Registry.yardoc_file_for_gem(spec.name)
    next if yfile.nil?

    if spec.name =~ /^yard-doc-/
      gem_paths.unshift(yfile)
    else
      gem_paths.push(yfile)
    end
  end
  @search_paths += gem_paths
rescue LoadError
  nil # noop
end
load_cache() click to toggle source

Loads {CACHE_FILE} @return [void]

# File lib/yard/cli/yri.rb, line 151
def load_cache
  return unless File.file?(CACHE_FILE)
  File.readlines(CACHE_FILE).each do |line|
    line = line.strip.split(/\s+/)
    @cache[line[0]] = line[1]
  end
end
optparse(*args) click to toggle source

Parses commandline options. @param [Array<String>] args each tokenized argument

# File lib/yard/cli/yri.rb, line 190
def optparse(*args)
  opts = OptionParser.new
  opts.banner = "Usage: yri [options] <Path to object>"
  opts.separator "Example: yri String#gsub"
  opts.separator ""
  opts.separator "General Options:"

  opts.on('-b', '--db FILE', 'Use a specified .yardoc db to search in') do |yfile|
    @search_paths.unshift(yfile)
  end

  opts.on('-T', '--no-pager', 'No pager') do
    @serializer = YARD::Serializers::StdoutSerializer.new
  end

  opts.on('-p PAGER', '--pager') do |pager|
    @serializer = YARD::Serializers::ProcessSerializer.new(pager)
  end

  common_options(opts)
  parse_options(opts, args)
  @name = args.first
end
try_load_object(name, cache_path) click to toggle source

Tries to load the object with name. If successful, caches the object with the cache_path

@param [String] name the object path @param [String] cache_path the location of the yardoc

db containing the object to cache for future lookups.
No caching is done if this is nil.

@return [void]

# File lib/yard/cli/yri.rb, line 143
def try_load_object(name, cache_path)
  obj = Registry.at(name)
  cache_object(name, cache_path) if obj && cache_path
  obj
end