Class: Toys::SourceInfo

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/source_info.rb

Overview

Information about the source of a tool, such as the file, git repository, or block that defined it.

This object represents a source of tool information and definitions. Such a source could include:

  • A toys directory
  • A single toys file
  • A file or directory loaded from git
  • A file or directory loaded from a gem
  • A config block passed directly to the CLI
  • A tool block within a toys file

The SourceInfo provides information such as the tool's context directory, and locates data and lib directories appropriate to the tool. It also locates the tool's source code so it can be reported when an error occurs.

Each tool has a unique SourceInfo with all the information specific to that tool. Additionally, SourceInfo objects are arranged in a containment hierarchy. For example, a SourceInfo object representing a toys files could have a parent representing a toys directory, and an object representing a tool block could have a parent representing an enclosing block or a file.

Child SourceInfo objects generally inherit some attributes of their parent. For example, the .toys directory in a project directory defines the context directory as that project directory. Then all tools defined under that directory will share that context directory, so all SourceInfo objects descending from that root will inherit that value (unless it's changed explicitly).

SourceInfo objects can be obtained in the DSL from DSL::Tool#source_info or at runtime by getting the Context::Key::TOOL_SOURCE key. However, they are created internally by the Loader and should not be created manually.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#context_directory ⇒ String? (readonly)

The context directory path (normally the directory containing the toplevel toys file or directory).

This is not affected by setting a custom context directory for a tool.

Returns:

  • (String) —

    The context directory path.

  • (nil) —

    if there is no context directory (perhaps because the root source was a block)



75
76
77
 
# File 'lib/toys/source_info.rb', line 75

def context_directory
  @context_directory
end

#gem_name ⇒ String? (readonly)

The gem name. This is set if the source, or one of its ancestors, comes from a gem.

Returns:

  • (String) —

    The gem name.

  • (nil) —

    if this source is not from a gem.



154
155
156
 
# File 'lib/toys/source_info.rb', line 154

def gem_name
  @gem_name
end

#gem_path ⇒ String? (readonly)

The path within the gem, including the toys root directory in the gem.

Returns:

  • (String) —

    The path.

  • (nil) —

    if this source is not from a gem.



171
172
173
 
# File 'lib/toys/source_info.rb', line 171

def gem_path
  @gem_path
end

#gem_version ⇒ Gem::Version? (readonly)

The gem version. This is set if the source, or one of its ancestors, comes from a gem.

Returns:

  • (Gem::Version) —

    The gem version.

  • (nil) —

    if this source is not from a gem.



163
164
165
 
# File 'lib/toys/source_info.rb', line 163

def gem_version
  @gem_version
end

#git_commit ⇒ String? (readonly)

The git commit. This is set if the source, or one of its ancestors, comes from git.

Returns:

  • (String) —

    The git commit.

  • (nil) —

    if this source is not fron git.



145
146
147
 
# File 'lib/toys/source_info.rb', line 145

def git_commit
  @git_commit
end

#git_path ⇒ String? (readonly)

The git path. This is set if the source, or one of its ancestors, comes from git.

Returns:

  • (String) —

    The git path. This could be the empty string.

  • (nil) —

    if this source is not fron git.



136
137
138
 
# File 'lib/toys/source_info.rb', line 136

def git_path
  @git_path
end

#git_remote ⇒ String? (readonly)

The git remote. This is set if the source, or one of its ancestors, comes from git.

Returns:

  • (String) —

    The git remote

  • (nil) —

    if this source is not fron git.



127
128
129
 
# File 'lib/toys/source_info.rb', line 127

def git_remote
  @git_remote
end

#parent ⇒ Toys::SourceInfo? (readonly)

The parent of this SourceInfo.

Returns:



47
48
49
 
# File 'lib/toys/source_info.rb', line 47

def parent
  @parent
end

#priority ⇒ Integer (readonly)

The priority of tools defined by this source. Higher values indicate a higher priority. Lower priority values could be negative.

Returns:

  • (Integer) —

    The priority.



63
64
65
 
# File 'lib/toys/source_info.rb', line 63

def priority
  @priority
end

#root ⇒ Toys::SourceInfo (readonly)

The root ancestor of this SourceInfo. This generally represents a source that was added directly to a CLI in code.

Returns:



55
56
57
 
# File 'lib/toys/source_info.rb', line 55

def root
  @root
end

#source ⇒ String, Proc (readonly)

The source, which may be a path or a proc depending on the #source_type.

Returns:

  • (String) —

    Path to the source file or directory.

  • (Proc) —

    The block serving as the source.



83
84
85
 
# File 'lib/toys/source_info.rb', line 83

def source
  @source
end

#source_name ⇒ String (readonly) Also known as: to_s

A user-visible name of this source.

Returns:

  • (String) 


178
179
180
 
# File 'lib/toys/source_info.rb', line 178

def source_name
  @source_name
end

#source_path ⇒ String? (readonly)

The path of the current source file or directory.

This could be set even if #source_type is :proc, if that proc is defined within a toys file. The only time this is not set is if the source is added directly to a CLI in a code block.

Returns:

  • (String) —

    The source path

  • (nil) —

    if this source has no file system path.



110
111
112
 
# File 'lib/toys/source_info.rb', line 110

def source_path
  @source_path
end

#source_proc ⇒ Proc? (readonly)

The source proc. This is set if #source_type is :proc.

Returns:

  • (Proc) —

    The source proc

  • (nil) —

    if this source has no proc.



118
119
120
 
# File 'lib/toys/source_info.rb', line 118

def source_proc
  @source_proc
end

#source_type ⇒ :file, ... (readonly)

The type of source. This could be:

  • :file, representing a single toys file. The #source will be the filesystem path to that file.
  • :directory, representing a toys directory. The #source will be the filesystem path to that directory.
  • :proc, representing a proc, which could be a toplevel block added directly to a CLI, a tool block within a toys file, or a block within another block. The #source will be the proc itself.

Returns:

  • (:file, :directory, :proc) 


98
99
100
 
# File 'lib/toys/source_info.rb', line 98

def source_type
  @source_type
end

Instance Method Details

#apply_lib_paths ⇒ self

Apply all lib paths in order from high to low priority

Returns:

  • (self) 


210
211
212
213
214
 
# File 'lib/toys/source_info.rb', line 210

def apply_lib_paths
  parent&.apply_lib_paths
  $LOAD_PATH.unshift(@lib_dir) if @lib_dir && !$LOAD_PATH.include?(@lib_dir)
  self
end

#find_data(path, type: nil) ⇒ String?

Locate the given data file or directory and return an absolute path.

Parameters:

  • path (String) —

    The relative path to find

  • type (nil, :file, :directory) (defaults to: nil) —

    Type of file system object to find, or nil (the default) to return any type.

Returns:

  • (String) —

    Absolute path of the resulting data.

  • (nil) —

    if the data was not found.



190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/toys/source_info.rb', line 190

def find_data(path, type: nil)
  if @data_dir
    full_path = ::File.join(@data_dir, path)
    case type
    when :file
      return full_path if ::File.file?(full_path)
    when :directory
      return full_path if ::File.directory?(full_path)
    else
      return full_path if ::File.readable?(full_path)
    end
  end
  parent&.find_data(path, type: type)
end