Class: Toys::Loader

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

Overview

Defined in the toys-core gem

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

Instance Method Summary collapse

Constructor Details

#initialize(index_file_name: nil, preload_dir_name: nil, preload_file_name: nil, data_dir_name: nil, lib_dir_name: nil, middleware_stack: [], extra_delimiters: "", mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil, git_cache: nil) ⇒ Loader

Create a Loader

Parameters:

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

    A file with this name that appears in any configuration directory (not just a toplevel directory) is loaded first as a standalone configuration file. If not provided, standalone configuration files are disabled.

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

    A file with this name that appears in any configuration directory is preloaded before any tools in that configuration directory are defined.

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

    A directory with this name that appears in any configuration directory is searched for Ruby files, which are preloaded before any tools in that configuration directory are defined.

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

    A directory with this name that appears in any configuration directory is added to the data directory search path for any tool file in that directory.

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

    A directory with this name that appears in any configuration directory is added to the Ruby load path for any tool file in that directory.

  • 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.

  • extra_delimiters (String) (defaults to: "") —

    A string containing characters that can function as delimiters in a tool name. Defaults to empty. Allowed characters are period, colon, and slash.

  • 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.



42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'core-docs/toys/loader.rb', line 42

def initialize(index_file_name: nil,
               preload_dir_name: nil,
               preload_file_name: nil,
               data_dir_name: nil,
               lib_dir_name: nil,
               middleware_stack: [],
               extra_delimiters: "",
               mixin_lookup: nil,
               middleware_lookup: nil,
               template_lookup: nil,
               git_cache: nil)
  # Source available in the toys-core gem
end

Instance Method Details

#add_block(high_priority: false, source_name: nil, context_directory: nil, &block) ⇒ self

Add a configuration block to the loader.

Parameters:

  • high_priority (Boolean) (defaults to: false) —

    If true, add this block at the top of the priority list. Defaults to false, indicating the block should be at the bottom of the priority list.

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

    The source name that will be shown in documentation for tools defined in this block. If omitted, a default unique string will be generated.

  • block (Proc) —

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

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

    The context directory for tools loaded from this block. You can pass a directory path as a string, or nil to denote no context. Defaults to nil.

Returns:

  • (self) 


119
120
121
122
123
124
 
# File 'core-docs/toys/loader.rb', line 119

def add_block(high_priority: false,
              source_name: nil,
              context_directory: nil,
              &block)
  # Source available in the toys-core gem
end

#add_git(git_remote, git_path, git_commit, high_priority: false, update: false, context_directory: nil) ⇒ self

Add a configuration git source to the loader.

Parameters:

  • git_remote (String) —

    The git repo URL

  • git_path (String) —

    The path to the relevant file or directory in the repo. Specify the empty string to use the entire repo.

  • git_commit (String) —

    The git ref (i.e. SHA, tag, or branch name)

  • high_priority (Boolean) (defaults to: false) —

    If true, add this path at the top of the priority list. Defaults to false, indicating the new path should be at the bottom of the priority list.

  • update (Boolean) (defaults to: false) —

    If the commit is not a SHA, pulls any updates from the remote. Defaults to false, which uses a local cache and does not update if the commit has been fetched previously.

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

    The context directory for tools loaded from this source. You can pass a directory path as a string, or nil to denote no context. Defaults to nil.

Returns:

  • (self) 


144
145
146
147
148
149
 
# File 'core-docs/toys/loader.rb', line 144

def add_git(git_remote, git_path, git_commit,
            high_priority: false,
            update: false,
            context_directory: nil)
  # Source available in the toys-core gem
end

#add_path(path, high_priority: false, source_name: nil, context_directory: :parent) ⇒ self

Add a configuration file/directory to the loader.

Parameters:

  • path (String) —

    A single path to add.

  • high_priority (Boolean) (defaults to: false) —

    If true, add this path at the top of the priority list. Defaults to false, indicating the new path should be at the bottom of the priority list.

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

    A custom name for the root source. Optional.

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

    The context directory for tools loaded from this path. You can pass a directory path as a string, :path to denote the given path, :parent to denote the given path's parent directory, or nil to denote no context. Defaults to :parent.

Returns:

  • (self) 


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

def add_path(path,
             high_priority: false,
             source_name: nil,
             context_directory: :parent)
  # Source available in the toys-core gem
end

#add_path_set(root_path, relative_paths, high_priority: false, context_directory: :path) ⇒ self

Add a set of configuration files/directories from a common directory to the loader. The set of paths will be added at the same priority level and will share a root.

Parameters:

  • root_path (String) —

    A root path to be seen as the root source. This should generally be a directory containing the paths to add.

  • relative_paths (String, Array<String>) —

    One or more paths to add, as relative paths from the common root.

  • high_priority (Boolean) (defaults to: false) —

    If true, add the paths at the top of the priority list. Defaults to false, indicating the new paths should be at the bottom of the priority list.

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

    The context directory for tools loaded from this path. You can pass a directory path as a string, :path to denote the given root path, :parent to denote the given root path's parent directory, or nil to denote no context. Defaults to :path.

Returns:

  • (self) 


97
98
99
100
101
 
# File 'core-docs/toys/loader.rb', line 97

def add_path_set(root_path, relative_paths,
                 high_priority: false,
                 context_directory: :path)
  # Source available in the toys-core gem
end

#has_subtools?(words) ⇒ Boolean

Returns true if the given path has at least one subtool. Loads from the configuration if necessary.

Parameters:

  • words (Array<String>) —

    The name of the parent tool

Returns:

  • (Boolean) 


206
207
208
 
# File 'core-docs/toys/loader.rb', line 206

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

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

Returns a list of subtools for the given path, loading from the configuration if necessary.

Parameters:

  • words (Array<String>) —

    The name of the parent tool

  • 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, e.g. names beginning with underscores.

Returns:



195
196
197
 
# File 'core-docs/toys/loader.rb', line 195

def list_subtools(words, recursive: false, include_hidden: 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 the configuration if necessary. This always returns a tool. If the specific tool path is not defined and cannot be found in any configuration, it finds the nearest namespace that would contain that tool, up to the root tool.

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

Returns:



164
165
166
 
# File 'core-docs/toys/loader.rb', line 164

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 the configuration if necessary.

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

Returns:



180
181
182
 
# File 'core-docs/toys/loader.rb', line 180

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

#split_path(str) ⇒ Array<String>

Splits the given path using the delimiters configured in this Loader. You may pass in either an array of strings, or a single string possibly delimited by path separators. Always returns an array of strings.

Parameters:

  • str (String, Symbol, Array<String,Symbol>) —

    The path to split.

Returns:

  • (Array<String>) 


218
219
220
 
# File 'core-docs/toys/loader.rb', line 218

def split_path(str)
  # Source available in the toys-core gem
end