Class: Toys::Loader

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/loader.rb

Overview

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
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/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)
  if index_file_name && ::File.extname(index_file_name) != ".rb"
    raise ::ArgumentError, "Illegal index file name #{index_file_name.inspect}"
  end
  require "monitor"
  # This mutex serializes all loading. It could be held for arbitrary
  # amounts of time because it surrounds the loading of tools files.
  @mutex = ::Monitor.new
  @mixin_lookup = mixin_lookup || ModuleLookup.new
  @template_lookup = template_lookup || ModuleLookup.new
  @middleware_lookup = middleware_lookup || ModuleLookup.new
  @index_file_name = index_file_name
  @preload_file_name = preload_file_name
  @preload_dir_name = preload_dir_name
  @data_dir_name = data_dir_name
  @lib_dir_name = lib_dir_name
  @loading_started = false
  @worklist = []
  @tool_data = {}
  @roots_by_priority = {}
  @max_priority = @min_priority = 0
  @stop_priority = -999_999
  @min_loaded_priority = 999_999
  @middleware_stack = Middleware.stack(middleware_stack)
  @delimiter_handler = DelimiterHandler.new(extra_delimiters)
  @git_cache = git_cache
  @gems_util = gems_util
  get_tool([], -999_999)
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) 


182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/toys/loader.rb', line 182

def add_block(high_priority: false,
              source_name: nil,
              context_directory: nil,
              &block)
  @mutex.synchronize do
    raise "Cannot add a block after tool loading has started" if @loading_started
    priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
    source = SourceInfo.create_proc_root(block, priority,
                                         context_directory: context_directory,
                                         source_name: source_name,
                                         data_dir_name: @data_dir_name,
                                         lib_dir_name: @lib_dir_name)
    @roots_by_priority[priority] = source
    @worklist << [source, [], priority]
  end
  self
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) 


263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/toys/loader.rb', line 263

def add_gem(gem_name, gem_version, gem_path,
            high_priority: false,
            source_name: nil,
            gem_toys_dir: nil,
            context_directory: nil)
  gem_version, gem_path, path = resolve_gem_info(gem_name, gem_version, gem_toys_dir, gem_path)
  @mutex.synchronize do
    raise "Cannot add a gem source after tool loading has started" if @loading_started
    priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
    source = SourceInfo.create_gem_root(gem_name, gem_version, gem_path, path, priority,
                                        context_directory: context_directory,
                                        source_name: source_name,
                                        data_dir_name: @data_dir_name,
                                        lib_dir_name: @lib_dir_name)
    @roots_by_priority[priority] = source
    @worklist << [source, [], priority]
  end
  self
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) 


221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/toys/loader.rb', line 221

def add_git(git_remote, git_path, git_commit,
            high_priority: false,
            source_name: nil,
            update: false,
            context_directory: nil)
  path = resolve_git_path(git_remote, git_path, git_commit, update)
  @mutex.synchronize do
    raise "Cannot add a git source after tool loading has started" if @loading_started
    priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
    source = SourceInfo.create_git_root(git_remote, git_path, git_commit, path, priority,
                                        context_directory: context_directory,
                                        source_name: source_name,
                                        data_dir_name: @data_dir_name,
                                        lib_dir_name: @lib_dir_name)
    @roots_by_priority[priority] = source
    @worklist << [source, [], priority]
  end
  self
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) 


100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/toys/loader.rb', line 100

def add_path(path,
             high_priority: false,
             source_name: nil,
             context_directory: :parent)
  @mutex.synchronize do
    raise "Cannot add a path after tool loading has started" if @loading_started
    priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
    source = SourceInfo.create_path_root(path, priority,
                                         context_directory: context_directory,
                                         data_dir_name: @data_dir_name,
                                         lib_dir_name: @lib_dir_name,
                                         source_name: source_name)
    @roots_by_priority[priority] = source
    @worklist << [source, [], priority]
  end
  self
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) 


141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/toys/loader.rb', line 141

def add_path_set(root_path, relative_paths,
                 high_priority: false,
                 source_name: nil,
                 context_directory: :path)
  relative_paths = Array(relative_paths)
  @mutex.synchronize do
    raise "Cannot add a path after tool loading has started" if @loading_started
    priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
    root_source = SourceInfo.create_path_root(root_path, priority,
                                              context_directory: context_directory,
                                              data_dir_name: @data_dir_name,
                                              lib_dir_name: @lib_dir_name,
                                              source_name: source_name)
    unless root_source.source_type == :directory
      raise ::ArgumentError, "Root path #{root_path.inspect} for add_path_set was not a directory"
    end
    @roots_by_priority[priority] = root_source
    relative_paths.each do |path|
      source = root_source.relative_child(path)
      @worklist << [source, [], priority]
    end
  end
  self
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) 


370
371
372
373
374
375
376
377
 
# File 'lib/toys/loader.rb', line 370

def has_subtools?(words) # rubocop:disable Naming/PredicatePrefix
  load_for_prefix(words)
  len = words.length
  all_cur_definitions.any? do |tool|
    name = tool.full_name
    name.length > len && name.slice(0, len) == words
  end
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:



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/toys/loader.rb', line 345

def list_subtools(words,
                  recursive: false,
                  include_hidden: false,
                  include_namespaces: false,
                  include_non_runnable: false)
  load_for_prefix(words)
  len = words.length
  found_tools = all_cur_definitions.find_all do |tool|
    name = tool.full_name
    name.length > len && name.slice(0, len) == words &&
      (include_hidden || name[len..].none? { |word| word.start_with?("_") })
  end
  found_tools.sort_by!(&:full_name)
  found_tools = filter_non_runnable_tools(found_tools, include_namespaces, include_non_runnable)
  found_tools.select! { |tool| tool.full_name.length == len + 1 } unless recursive
  found_tools
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:



296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/toys/loader.rb', line 296

def lookup(args)
  orig_prefix, args = @delimiter_handler.find_orig_prefix(args)
  # Start looking for a tool with the entire prefix, and continue to
  # shorten it until a tool is found. Because the root tool always exists,
  # the final fallback of the empty prefix will always succeed.
  prefix = orig_prefix
  loop do
    tool = lookup_specific(prefix)
    return [tool, args.slice(prefix.length..-1)] if tool
    prefix = prefix.slice(0..-2)
  end
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:



321
322
323
324
325
326
327
 
# File 'lib/toys/loader.rb', line 321

def lookup_specific(words)
  words = @delimiter_handler.split_path(words.first) if words.size == 1
  load_for_prefix(words)
  tool = @mutex.synchronize { get_tool_data(words, false)&.cur_definition }
  finish_definitions_in_tree(words) if tool
  tool
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>) 


387
388
389
390
 
# File 'lib/toys/loader.rb', line 387

def split_path(str)
  return str.map(&:to_s) if str.is_a?(::Array)
  @delimiter_handler.split_path(str.to_s)
end