Module: Toys::SourceSpec

Defined in:
lib/toys/source_spec.rb

Overview

A source spec is an unresolved description of a source: its kind, and the information needed to locate it.

Source specs cover the sources added to a SourceList, and the sources declared from within a toys file using the load, load_git, and load_gem directives. (A source that a Loader finds by walking a directory has no source spec.)

A source spec says only what to load; it performs no filesystem access, no git fetch, and no gem activation. Those happen later, when a loader resolves the spec into a SourceInfo. A spec does, however, check the types of its arguments when it is created, so a malformed description is reported at that point rather than at resolution time. Create specs using the factory methods SourceSpec.path, SourceSpec.git, SourceSpec.gem, and SourceSpec.block, each of which returns an instance of the corresponding subclass of Base.

Source specs are immutable and compare by value, so two specs describing the same source are equal and hash alike. (A block spec's proc compares by identity.)

Defined Under Namespace

Classes: Base, Block, Gem, Git, Path

Constant Summary collapse

EMPTY =

An empty SourceSpec. Used as a synthetic root SourceSpec for tools without a true source (such as the default root tool, and synthetic tools used for testing.)

Returns:

Block.new(proc {}, nil, "(No source)").freeze

Class Method Summary collapse

Class Method Details

.block(context_directory: nil, source_name: nil, &block) ⇒ Toys::SourceSpec::Block

Create a spec for a block of DSL code.

Parameters:

  • context_directory (String, Pathname, nil) (defaults to: nil) —

    The context directory path for tools loaded from this source. Optional. Defaults to nil if not provided. Context directory paths should generally be absolute. Relative paths will be converted to absolute, using the current working directory at the time of construction.

  • source_name (String, nil) (defaults to: nil) —

    The source name that will be shown in documentation for tools loaded from this source. If omitted, a default is generated at resolution time.

  • block (Proc) —

    The source block, executed in the context of the tool DSL DSL::Tool.

Returns:

Raises:

  • (ArgumentError) —

    if an argument is not a legal value.



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

def block(context_directory: nil, source_name: nil, &block)
  Block.new(block, context_directory, source_name)
end

.gem(name, version: nil, path: nil, toys_dir: nil, context_directory: nil, source_name: nil, on_missing: nil, default_confirm: nil) ⇒ Toys::SourceSpec::Gem

Create a spec for a gem.

Parameters:

  • name (String) —

    The name of the gem.

  • version (String, Array<String>, nil) (defaults to: nil) —

    Version requirements for the gem. Optional. If not provided, any version is allowed.

  • path (String, nil) (defaults to: nil) —

    The path from the gem's toys directory to the relevant file or directory. Optional. If not provided, the entire toys directory is used.

  • toys_dir (String, nil) (defaults to: nil) —

    The name of the gem's toys directory. Optional. Defaults to the directory specified in the gem's metadata, or the value "toys".

  • context_directory (String, Pathname, nil) (defaults to: nil) —

    The context directory path for tools loaded from this source. Optional. Defaults to nil if not provided. Context directory paths should generally be absolute. Relative paths will be converted to absolute, using the current working directory at the time of construction.

  • source_name (String, nil) (defaults to: nil) —

    The source name that will be shown in documentation for tools loaded from this source. If omitted, a default is generated at resolution time.

  • on_missing (:confirm, :error, :install) (defaults to: nil) —

    What to do if the requested gem is not installed. Possible values:

    • :confirm - prompt the user on whether to install
    • :error - raise an exception
    • :install - just install the gem

    Defaults to the setting in the Utils::Gems utility used to activate the gem (usually :confirm).

  • default_confirm (boolean) (defaults to: nil) —

    The default confirmation result, if on_missing is set to :confirm. Defaults to the setting in the Utils::Gems utility used to activate the gem (usually true).

Returns:

Raises:

  • (ArgumentError) —

    if an argument is not a legal value.



124
125
126
127
 
# File 'lib/toys/source_spec.rb', line 124

def gem(name, version: nil, path: nil, toys_dir: nil, context_directory: nil, source_name: nil,
        on_missing: nil, default_confirm: nil)
  Gem.new(name, version, path, toys_dir, context_directory, source_name, on_missing, default_confirm)
end

.git(remote, path: nil, commit: nil, update: false, context_directory: nil, source_name: nil) ⇒ Toys::SourceSpec::Git

Create a spec for a git repository.

Parameters:

  • remote (String, nil) —

    The git repo URL, or nil to inherit the remote from the source doing the loading. (A nil remote with no such source fails at resolution time, not here.)

  • path (String, nil) (defaults to: nil) —

    The path within the repo to the file or directory to load. Optional. Defaults to the root of the repo.

  • commit (String, nil) (defaults to: nil) —

    The git ref (i.e. SHA, tag, or branch name). Optional. Defaults to the commit of the source doing the loading, or to "HEAD".

  • update (boolean, Integer) (defaults to: false) —

    Whether to update non-SHA commit references if they were previously loaded. Pass true or false to specify whether to update, or an integer to update if the last update was done at least that many seconds ago. Default is false.

  • context_directory (String, Pathname, nil) (defaults to: nil) —

    The context directory path for tools loaded from this source. Optional. Defaults to nil if not provided. Context directory paths should generally be absolute. Relative paths will be converted to absolute, using the current working directory at the time of construction.

  • source_name (String, nil) (defaults to: nil) —

    The source name that will be shown in documentation for tools loaded from this source. If omitted, a default is generated at resolution time.

Returns:

Raises:

  • (ArgumentError) —

    if an argument is not a legal value.



84
85
86
 
# File 'lib/toys/source_spec.rb', line 84

def git(remote, path: nil, commit: nil, update: false, context_directory: nil, source_name: nil)
  Git.new(remote, path, commit, update, context_directory, source_name)
end

.path(path, relative_paths: nil, context_directory: nil, source_name: nil) ⇒ Toys::SourceSpec::Path

Create a spec for a file system path.

Parameters:

  • path (String, Pathname) —

    Path to a tool file or directory. Must be a String or a Pathname. Paths should generally be absolute. Relative paths will be converted to absolute, using the current working directory at the time of construction.

  • relative_paths (String, Array<String>, nil) (defaults to: nil) —

    If provided, the given path is treated as a root directory, and these paths, relative to it, are the sources actually loaded. Pass nil (the default) to load the path itself. Note that nil and the empty array mean different things: the empty array indicates no paths under the given root path, effectively a noop, while nil indicates a single path equal to the given root path.

  • context_directory (String, Pathname, nil) (defaults to: nil) —

    The context directory path for tools loaded from this source. Optional. Defaults to nil if not provided. Context directory paths should generally be absolute. Relative paths will be converted to absolute, using the current working directory at the time of construction.

  • source_name (String, nil) (defaults to: nil) —

    The source name that will be shown in documentation for tools loaded from this source. If omitted, a default is generated at resolution time.

Returns:

Raises:

  • (ArgumentError) —

    if an argument is not a legal value.



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

def path(path, relative_paths: nil, context_directory: nil, source_name: nil)
  Path.new(path, relative_paths, context_directory, source_name)
end