# Class: YARD::CLI::YRI

Inherits:
  Command
  - Object
  - Command
  - YARD::CLI::YRI
  show all

Defined in:
  lib/yard/cli/yri.rb

## Overview

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

## Constant Summary collapse

CACHE_FILE =

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

      File.expand_path(File.join(YARD::Config::CONFIG_DIR, 'yri_cache'))

SEARCH_PATHS_FILE =

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

Since:

- 0.5.1

      File.expand_path(File.join(YARD::Config::CONFIG_DIR, 'yri_search_paths'))

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")

Returns:

- (`Array<String>`) —

  a list of extra search paths

Since:

- 0.6.0

      []

## Class Method Summary collapse

- .run(*args) ⇒ Object

  Helper method to run the utility on an instance.

## Instance Method Summary collapse

- #cache_object(name, path) ⇒ void protected

  Caches the .yardoc file where an object can be found in the CACHE_FILE.

- #description ⇒ Object
- #find_object(name) ⇒ CodeObjects::Base? protected

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

- #initialize ⇒ YRI constructor

  A new instance of YRI.

- #print_object(object) ⇒ String protected

  The formatted output for an object.

- #print_usage ⇒ void protected

  Prints the command usage.

- #run(*args) ⇒ Object

  Runs the command-line utility.

## Constructor Details

### #initialize ⇒ `YRI`

Returns a new instance of YRI.

    31
    32
    33
    34
    35
    36
    37
    38
    39

    # 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

## Class Method Details

### .run(*args) ⇒ `Object`

Helper method to run the utility on an instance.

See Also:

- #run

    29

    # File 'lib/yard/cli/yri.rb', line 29

    def self.run(*args) new.run(*args) end

## Instance Method Details

### #cache_object(name, path) ⇒ `void` (protected)

This method returns an undefined value.

Caches the .yardoc file where an object can be found in the CACHE_FILE

    85
    86
    87
    88
    89
    90
    91
    92
    93
    94

    # 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

### #description ⇒ `Object`

    41
    42
    43

    # File 'lib/yard/cli/yri.rb', line 41

    def description
      "A tool to view documentation in the console like `ri`"
    end

### #find_object(name) ⇒ `CodeObjects::Base`? (protected)

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

Parameters:

- name (`String`) —

  the full name of the object

Returns:

- (`CodeObjects::Base`) —

  an object if found

- (`nil`) —

  if no object is found

    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131

    # 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) ⇒ `String` (protected)

Returns the formatted output for an object.

Parameters:

- object (`CodeObjects::Base`) —

  the object to print.

Returns:

- (`String`) —

  the formatted output for an object.

    98
    99
    100
    101
    102
    103
    104
    105

    # File 'lib/yard/cli/yri.rb', line 98

    def print_object(object)
      if object.type == :method && object.is_alias?
        tmp = P(object.namespace, (object.scope == :instance ? "#" : "") +
          object.namespace.aliases[object].to_s)
        object = tmp unless YARD::CodeObjects::Proxy === tmp
      end
      object.format(:serializer => @serializer)
    end

### #print_usage ⇒ `void` (protected)

This method returns an undefined value.

Prints the command usage

Since:

- 0.5.6

    78
    79
    80
    81

    # File 'lib/yard/cli/yri.rb', line 78

    def print_usage
      log.puts "Usage: yri [options] <Path to object>"
      log.puts "See yri --help for more options."
    end

### #run(*args) ⇒ `Object`

Runs the command-line utility.

#### Examples:

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

Parameters:

- args (`Array<String>`) —

  each tokenized argument

    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71

    # 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