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, gems_util: 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
55
 
# 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,
               gems_util: 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 loaded from this source. 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) 


127
128
129
130
131
132
 
# File 'core-docs/toys/loader.rb', line 127

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

#add_gem(gem_name, gem_version, gem_path, high_priority: false, source_name: nil, gem_toys_dir: nil, context_directory: nil) ⇒ self

Add a configuration gem source to the loader.

Parameters:

  • gem_name (String) —

    The name of the gem

  • gem_version (String, Array<String>) —

    The version requirements

  • gem_path (String) —

    The path from the gem's toys directory to the relevant file or directory. Specify the empty string to use the entire toys directory.

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

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

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

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

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


185
186
187
188
189
190
191
 
# File 'core-docs/toys/loader.rb', line 185

def add_gem(gem_name, gem_version, gem_path,
            high_priority: false,
            source_name: nil,
            gem_toys_dir: nil,
            context_directory: nil)
  # Source available in the toys-core gem
end

#add_git(git_remote, git_path, git_commit, high_priority: false, source_name: nil, 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.

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

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

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


155
156
157
158
159
160
161
 
# File 'core-docs/toys/loader.rb', line 155

def add_git(git_remote, git_path, git_commit,
            high_priority: false,
            source_name: nil,
            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) —

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

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


74
75
76
77
78
79
 
# File 'core-docs/toys/loader.rb', line 74

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, source_name: nil, 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.

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

    The source name that will be shown in documentation for tools loaded from these sources. (Specifically, sets the name of the synthetic root source.) If omitted, a default unique string will be generated.

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


104
105
106
107
108
109
 
# File 'core-docs/toys/loader.rb', line 104

def add_path_set(root_path, relative_paths,
                 high_priority: false,
                 source_name: nil,
                 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, even if they are hidden or non-runnable. Loads from the configuration if necessary.

Parameters:

  • words (Array<String>) —

    The name of the parent tool

Returns:

  • (boolean) 


257
258
259
 
# File 'core-docs/toys/loader.rb', line 257

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 the configuration if necessary. The list will be sorted by name.

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, 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:



242
243
244
245
246
247
248
 
# File 'core-docs/toys/loader.rb', line 242

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



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

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:



222
223
224
 
# File 'core-docs/toys/loader.rb', line 222

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


269
270
271
 
# File 'core-docs/toys/loader.rb', line 269

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