Class: Toys::Loader

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/loader.rb,
core-docs/toys/loader/load_state.rb,
core-docs/toys/loader/tool_registry.rb

Overview

The Loader service loads tools from tool sources, and finds the appropriate tool given a set of command line arguments.

Defined in the toys-core gem

Constant Summary collapse

FALLBACK_ROOT_PRIORITY =

The priority of the always-present fallback root tool. This is the priority of the root tool that will be returned from lookups if no sources have been added. If any source is added, it will have a higher priority than this, and its tools will supersede this fallback.

Returns:

  • (Integer) 
-999_999_999

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source_list, tool_name_splitter: nil, middleware_stack: [], mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil, git_cache: nil, gems_util: nil) ⇒ Loader

Create a Loader.

Parameters:

  • source_list (Toys::SourceList) —

    The list of sources to use. The source specs are snapshotted from the SourceList on construction, so if the SourceList is modified later, those modifications are not reflected in the constructed Loader. The specs themselves are not resolved until the Loader first looks up a tool.

  • tool_name_splitter (Toys::ToolNameSplitter) (defaults to: nil) —

    The splitter that interprets delimiters in tool names. Defaults to ToolNameSplitter::DEFAULT, which recognizes only whitespace.

  • middleware_stack (Array<Toys::Middleware::Spec>) (defaults to: []) —

    An array of middleware that will be used by default for all tools loaded by this loader.

  • mixin_lookup (Toys::ModuleLookup) (defaults to: nil) —

    A lookup for well-known mixin modules. Defaults to an empty lookup.

  • middleware_lookup (Toys::ModuleLookup) (defaults to: nil) —

    A lookup for well-known middleware classes. Defaults to an empty lookup.

  • template_lookup (Toys::ModuleLookup) (defaults to: nil) —

    A lookup for well-known template classes. Defaults to an empty lookup.

  • git_cache (Toys::Utils::GitCache, nil) (defaults to: nil) —

    A custom GitCache instance to use when resolving git sources. Optional. If nil or not specified, uses a process-wide default GitCache.

  • gems_util (Toys::Utils::Gems, nil) (defaults to: nil) —

    A custom Gems utility instance to use when resolving gem sources. Optional. If nil or not specified, uses a process-wide default Gems utility.



55
56
57
58
59
60
61
62
63
64
 
# File 'core-docs/toys/loader.rb', line 55

def initialize(source_list,
               tool_name_splitter: nil,
               middleware_stack: [],
               mixin_lookup: nil,
               middleware_lookup: nil,
               template_lookup: nil,
               git_cache: nil,
               gems_util: nil)
  # Source available in the toys-core gem
end

Instance Attribute Details

#tool_name_splitter ⇒ Toys::ToolNameSplitter (readonly)

The splitter that interprets delimiters in the tool names handled by this loader. Use it to convert a delimited name into words.

Returns:



72
73
74
 
# File 'core-docs/toys/loader.rb', line 72

def tool_name_splitter
  @tool_name_splitter
end

Instance Method Details

#has_subtools?(words) ⇒ boolean

Returns true if the given path has at least one subtool, even if they are hidden or non-runnable. Loads from the sources if necessary.

Parameters:

  • words (Array<String>) —

    The name of the parent tool. It must be an array of strings; it cannot be a single string with delimiters.

Returns:

  • (boolean)

Raises:



151
152
153
 
# File 'core-docs/toys/loader.rb', line 151

def has_subtools?(words)
  # Source available in the toys-core gem
end

#list_subtools(words, recursive: false, include_hidden: false, include_namespaces: false, include_non_runnable: false) ⇒ Array<Toys::ToolDefinition>

Returns a list of subtools for the given path, loading from their sources and ensuring they are finished. The list will be sorted by name.

Parameters:

  • words (Array<String>) —

    The name of the parent tool. It must be an array of strings; it cannot be a single string with delimiters.

  • recursive (boolean) (defaults to: false) —

    If true, return all subtools recursively rather than just the immediate children (the default)

  • include_hidden (boolean) (defaults to: false) —

    If true, include hidden subtools, i.e. names beginning with underscores. Defaults to false.

  • include_namespaces (boolean) (defaults to: false) —

    If true, include namespaces, i.e. tools that are not runnable but have descendents that would have been listed by the current filters. Defaults to false.

  • include_non_runnable (boolean) (defaults to: false) —

    If true, include tools that have no children and are not runnable. Defaults to false.

Returns:

Raises:



133
134
135
136
137
138
139
 
# File 'core-docs/toys/loader.rb', line 133

def list_subtools(words,
                  recursive: false,
                  include_hidden: false,
                  include_namespaces: false,
                  include_non_runnable: false)
  # Source available in the toys-core gem
end

#lookup(args) ⇒ Array(Toys::ToolDefinition,Array<String>)

Given a list of command line arguments, find the appropriate tool to handle the command, loading it from its source if necessary and ensuring it has been finished. This always returns a tool. If the specific tool path is not defined and cannot be found in any source, it finds the nearest namespace that would contain that tool, up to the root tool (which always exists.)

Returns a tuple of the found tool, and the array of remaining arguments that are not part of the tool name and should be passed as tool args.

Parameters:

  • args (Array<String>) —

    Command line arguments. The first argument may be a full tool name with delimiters.

Returns:

Raises:



91
92
93
 
# File 'core-docs/toys/loader.rb', line 91

def lookup(args)
  # Source available in the toys-core gem
end

#lookup_specific(words) ⇒ Toys::ToolDefinition?

Given a tool name, looks up the specific tool, loading it from its source if necessary and ensuring it has been finished.

If there is an active tool, returns it; otherwise, returns the highest priority tool that has been defined. If no tool has been defined with the given name, returns nil.

Parameters:

  • words (Array<String>) —

    The tool name. It must be in the form of an array of strings; it cannot be a single string with delimiters.

Returns:

Raises:



110
111
112
 
# File 'core-docs/toys/loader.rb', line 110

def lookup_specific(words)
  # Source available in the toys-core gem
end

#resolve_sources ⇒ self

Ensures all root sources get resolved eagerly. Does not actually load any tools.

Can be called pre-emptively prior to other methods to prevent them from raising ToolSourceError directly. (It is still possible for them to raise ToolSourceError wrapped in a ContextualError if a tool invokes another source via one of the load directives.)

Returns:

  • (self)

Raises:



167
168
169
 
# File 'core-docs/toys/loader.rb', line 167

def resolve_sources
  # Source available in the toys-core gem
end