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



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

def context_directory
  @context_directory
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.



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

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.



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

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.



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

def git_remote
  @git_remote
end

#parent ⇒ Toys::SourceInfo? (readonly)

The parent of this SourceInfo.

Returns:



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

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.



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

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:



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

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.



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

def source
  @source
end

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

A user-visible name of this source.

Returns:

  • (String) 


151
152
153
 
# File 'lib/toys/source_info.rb', line 151

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.



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

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.



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

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) 


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

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) 


183
184
185
186
187
 
# File 'lib/toys/source_info.rb', line 183

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.



163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/toys/source_info.rb', line 163

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