toys 0.12.1 → 0.13.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.yardopts +2 -0
- data/CHANGELOG.md +44 -0
- data/LICENSE.md +1 -1
- data/README.md +7 -4
- data/builtins/system/git-cache.rb +238 -0
- data/builtins/system/test.rb +37 -2
- data/core-docs/toys/acceptor.rb +432 -0
- data/core-docs/toys/arg_parser.rb +397 -0
- data/core-docs/toys/cli.rb +493 -0
- data/core-docs/toys/compat.rb +2 -0
- data/core-docs/toys/completion.rb +329 -0
- data/core-docs/toys/context.rb +321 -0
- data/core-docs/toys/core.rb +14 -0
- data/core-docs/toys/dsl/base.rb +56 -0
- data/core-docs/toys/dsl/flag.rb +261 -0
- data/core-docs/toys/dsl/flag_group.rb +259 -0
- data/core-docs/toys/dsl/internal.rb +4 -0
- data/core-docs/toys/dsl/positional_arg.rb +139 -0
- data/core-docs/toys/dsl/tool.rb +1530 -0
- data/core-docs/toys/errors.rb +93 -0
- data/core-docs/toys/flag.rb +549 -0
- data/core-docs/toys/flag_group.rb +186 -0
- data/core-docs/toys/input_file.rb +8 -0
- data/core-docs/toys/loader.rb +222 -0
- data/core-docs/toys/middleware.rb +295 -0
- data/core-docs/toys/mixin.rb +142 -0
- data/core-docs/toys/module_lookup.rb +75 -0
- data/core-docs/toys/positional_arg.rb +145 -0
- data/core-docs/toys/settings.rb +507 -0
- data/core-docs/toys/source_info.rb +127 -0
- data/core-docs/toys/standard_middleware/add_verbosity_flags.rb +49 -0
- data/core-docs/toys/standard_middleware/apply_config.rb +24 -0
- data/core-docs/toys/standard_middleware/handle_usage_errors.rb +33 -0
- data/core-docs/toys/standard_middleware/set_default_descriptions.rb +222 -0
- data/core-docs/toys/standard_middleware/show_help.rb +190 -0
- data/core-docs/toys/standard_middleware/show_root_version.rb +45 -0
- data/core-docs/toys/standard_mixins/bundler.rb +83 -0
- data/core-docs/toys/standard_mixins/exec.rb +645 -0
- data/core-docs/toys/standard_mixins/fileutils.rb +18 -0
- data/core-docs/toys/standard_mixins/gems.rb +48 -0
- data/core-docs/toys/standard_mixins/git_cache.rb +41 -0
- data/core-docs/toys/standard_mixins/highline.rb +133 -0
- data/core-docs/toys/standard_mixins/terminal.rb +135 -0
- data/core-docs/toys/standard_mixins/xdg.rb +49 -0
- data/core-docs/toys/template.rb +112 -0
- data/core-docs/toys/tool_definition.rb +926 -0
- data/core-docs/toys/utils/completion_engine.rb +49 -0
- data/core-docs/toys/utils/exec.rb +721 -0
- data/core-docs/toys/utils/gems.rb +185 -0
- data/core-docs/toys/utils/git_cache.rb +353 -0
- data/core-docs/toys/utils/help_text.rb +134 -0
- data/core-docs/toys/utils/terminal.rb +310 -0
- data/core-docs/toys/utils/xdg.rb +253 -0
- data/core-docs/toys/wrappable_string.rb +120 -0
- data/core-docs/toys-core.rb +63 -0
- data/docs/guide.md +497 -156
- data/lib/toys/standard_cli.rb +50 -36
- data/lib/toys/templates/clean.rb +18 -0
- data/lib/toys/templates/gem_build.rb +24 -0
- data/lib/toys/templates/minitest.rb +21 -0
- data/lib/toys/templates/rake.rb +23 -3
- data/lib/toys/templates/rdoc.rb +29 -0
- data/lib/toys/templates/rspec.rb +32 -4
- data/lib/toys/templates/rubocop.rb +14 -1
- data/lib/toys/templates/yardoc.rb +55 -0
- data/lib/toys/testing.rb +186 -109
- data/lib/toys/version.rb +1 -1
- data/lib/toys.rb +4 -2
- metadata +56 -6
@@ -0,0 +1,186 @@
|
|
1
|
+
module Toys
|
2
|
+
##
|
3
|
+
# **_Defined in the toys-core gem_**
|
4
|
+
#
|
5
|
+
# A FlagGroup is a group of flags with the same requirement settings.
|
6
|
+
#
|
7
|
+
module FlagGroup
|
8
|
+
##
|
9
|
+
# Create a flag group object of the given type.
|
10
|
+
#
|
11
|
+
# The type should be one of the following symbols:
|
12
|
+
# * `:optional` All flags in the group are optional
|
13
|
+
# * `:required` All flags in the group are required
|
14
|
+
# * `:exactly_one` Exactly one flag in the group must be provided
|
15
|
+
# * `:at_least_one` At least one flag in the group must be provided
|
16
|
+
# * `:at_most_one` At most one flag in the group must be provided
|
17
|
+
#
|
18
|
+
# @param type [Symbol] The type of group. Default is `:optional`.
|
19
|
+
# @param desc [String,Array<String>,Toys::WrappableString] Short
|
20
|
+
# description for the group. See {Toys::ToolDefinition#desc} for a
|
21
|
+
# description of allowed formats. Defaults to `"Flags"`.
|
22
|
+
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
|
23
|
+
# Long description for the flag group. See
|
24
|
+
# {Toys::ToolDefinition#long_desc} for a description of allowed
|
25
|
+
# formats. Defaults to the empty array.
|
26
|
+
# @param name [String,Symbol,nil] The name of the group, or nil for no
|
27
|
+
# name.
|
28
|
+
# @return [Toys::FlagGroup::Base] A flag group of the correct subclass.
|
29
|
+
#
|
30
|
+
def self.create(type: nil, name: nil, desc: nil, long_desc: nil)
|
31
|
+
# Source available in the toys-core gem
|
32
|
+
end
|
33
|
+
|
34
|
+
##
|
35
|
+
# **_Defined in the toys-core gem_**
|
36
|
+
#
|
37
|
+
# The base class of a FlagGroup, implementing everything except validation.
|
38
|
+
# The base class effectively behaves as an Optional group. And the default
|
39
|
+
# group that contains flags not otherwise assigned to a group, is of this
|
40
|
+
# type. However, you should use {Toys::FlagGroup::Optional} when creating
|
41
|
+
# an explicit optional group.
|
42
|
+
#
|
43
|
+
class Base
|
44
|
+
##
|
45
|
+
# The symbolic name for this group
|
46
|
+
# @return [String,Symbol,nil]
|
47
|
+
#
|
48
|
+
attr_reader :name
|
49
|
+
|
50
|
+
##
|
51
|
+
# The short description string.
|
52
|
+
#
|
53
|
+
# When reading, this is always returned as a {Toys::WrappableString}.
|
54
|
+
#
|
55
|
+
# When setting, the description may be provided as any of the following:
|
56
|
+
# * A {Toys::WrappableString}.
|
57
|
+
# * A normal String, which will be transformed into a
|
58
|
+
# {Toys::WrappableString} using spaces as word delimiters.
|
59
|
+
# * An Array of String, which will be transformed into a
|
60
|
+
# {Toys::WrappableString} where each array element represents an
|
61
|
+
# individual word for wrapping.
|
62
|
+
#
|
63
|
+
# @return [Toys::WrappableString]
|
64
|
+
#
|
65
|
+
attr_reader :desc
|
66
|
+
|
67
|
+
##
|
68
|
+
# The long description strings.
|
69
|
+
#
|
70
|
+
# When reading, this is returned as an Array of {Toys::WrappableString}
|
71
|
+
# representing the lines in the description.
|
72
|
+
#
|
73
|
+
# When setting, the description must be provided as an Array where *each
|
74
|
+
# element* may be any of the following:
|
75
|
+
# * A {Toys::WrappableString} representing one line.
|
76
|
+
# * A normal String representing a line. This will be transformed into
|
77
|
+
# a {Toys::WrappableString} using spaces as word delimiters.
|
78
|
+
# * An Array of String representing a line. This will be transformed
|
79
|
+
# into a {Toys::WrappableString} where each array element represents
|
80
|
+
# an individual word for wrapping.
|
81
|
+
#
|
82
|
+
# @return [Array<Toys::WrappableString>]
|
83
|
+
#
|
84
|
+
attr_reader :long_desc
|
85
|
+
|
86
|
+
##
|
87
|
+
# An array of flags that are in this group.
|
88
|
+
# Do not modify the returned array.
|
89
|
+
# @return [Array<Toys::Flag>]
|
90
|
+
#
|
91
|
+
attr_reader :flags
|
92
|
+
|
93
|
+
##
|
94
|
+
# Returns true if this group is empty
|
95
|
+
# @return [Boolean]
|
96
|
+
#
|
97
|
+
def empty?
|
98
|
+
# Source available in the toys-core gem
|
99
|
+
end
|
100
|
+
|
101
|
+
##
|
102
|
+
# Returns a string summarizing this group. This is generally either the
|
103
|
+
# short description or a representation of all the flags included.
|
104
|
+
# @return [String]
|
105
|
+
#
|
106
|
+
def summary
|
107
|
+
# Source available in the toys-core gem
|
108
|
+
end
|
109
|
+
|
110
|
+
##
|
111
|
+
# Set the short description string.
|
112
|
+
#
|
113
|
+
# See {#desc} for details.
|
114
|
+
#
|
115
|
+
# @param desc [Toys::WrappableString,String,Array<String>]
|
116
|
+
#
|
117
|
+
def desc=(desc)
|
118
|
+
# Source available in the toys-core gem
|
119
|
+
end
|
120
|
+
|
121
|
+
##
|
122
|
+
# Set the long description strings.
|
123
|
+
#
|
124
|
+
# See {#long_desc} for details.
|
125
|
+
#
|
126
|
+
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
|
127
|
+
#
|
128
|
+
def long_desc=(long_desc)
|
129
|
+
# Source available in the toys-core gem
|
130
|
+
end
|
131
|
+
|
132
|
+
##
|
133
|
+
# Append long description strings.
|
134
|
+
#
|
135
|
+
# You must pass an array of lines in the long description. See {#long_desc}
|
136
|
+
# for details on how each line may be represented.
|
137
|
+
#
|
138
|
+
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
|
139
|
+
# @return [self]
|
140
|
+
#
|
141
|
+
def append_long_desc(long_desc)
|
142
|
+
# Source available in the toys-core gem
|
143
|
+
end
|
144
|
+
end
|
145
|
+
|
146
|
+
##
|
147
|
+
# **_Defined in the toys-core gem_**
|
148
|
+
#
|
149
|
+
# A FlagGroup containing all required flags
|
150
|
+
#
|
151
|
+
class Required < Base
|
152
|
+
end
|
153
|
+
|
154
|
+
##
|
155
|
+
# **_Defined in the toys-core gem_**
|
156
|
+
#
|
157
|
+
# A FlagGroup containing all optional flags
|
158
|
+
#
|
159
|
+
class Optional < Base
|
160
|
+
end
|
161
|
+
|
162
|
+
##
|
163
|
+
# **_Defined in the toys-core gem_**
|
164
|
+
#
|
165
|
+
# A FlagGroup in which exactly one flag must be set
|
166
|
+
#
|
167
|
+
class ExactlyOne < Base
|
168
|
+
end
|
169
|
+
|
170
|
+
##
|
171
|
+
# **_Defined in the toys-core gem_**
|
172
|
+
#
|
173
|
+
# A FlagGroup in which at most one flag must be set
|
174
|
+
#
|
175
|
+
class AtMostOne < Base
|
176
|
+
end
|
177
|
+
|
178
|
+
##
|
179
|
+
# **_Defined in the toys-core gem_**
|
180
|
+
#
|
181
|
+
# A FlagGroup in which at least one flag must be set
|
182
|
+
#
|
183
|
+
class AtLeastOne < Base
|
184
|
+
end
|
185
|
+
end
|
186
|
+
end
|
@@ -0,0 +1,8 @@
|
|
1
|
+
##
|
2
|
+
# **_Defined in the toys-core gem_**
|
3
|
+
#
|
4
|
+
# This module is a namespace for constant scopes. Whenever a configuration file
|
5
|
+
# is parsed, a module is created under this parent for that file's constants.
|
6
|
+
#
|
7
|
+
module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
|
8
|
+
end
|
@@ -0,0 +1,222 @@
|
|
1
|
+
module Toys
|
2
|
+
##
|
3
|
+
# **_Defined in the toys-core gem_**
|
4
|
+
#
|
5
|
+
# The Loader service loads tools from configuration files, and finds the
|
6
|
+
# appropriate tool given a set of command line arguments.
|
7
|
+
#
|
8
|
+
class Loader
|
9
|
+
##
|
10
|
+
# Create a Loader
|
11
|
+
#
|
12
|
+
# @param index_file_name [String,nil] A file with this name that appears
|
13
|
+
# in any configuration directory (not just a toplevel directory) is
|
14
|
+
# loaded first as a standalone configuration file. If not provided,
|
15
|
+
# standalone configuration files are disabled.
|
16
|
+
# @param preload_file_name [String,nil] A file with this name that appears
|
17
|
+
# in any configuration directory is preloaded before any tools in that
|
18
|
+
# configuration directory are defined.
|
19
|
+
# @param preload_dir_name [String,nil] A directory with this name that
|
20
|
+
# appears in any configuration directory is searched for Ruby files,
|
21
|
+
# which are preloaded before any tools in that configuration directory
|
22
|
+
# are defined.
|
23
|
+
# @param data_dir_name [String,nil] A directory with this name that appears
|
24
|
+
# in any configuration directory is added to the data directory search
|
25
|
+
# path for any tool file in that directory.
|
26
|
+
# @param lib_dir_name [String,nil] A directory with this name that appears
|
27
|
+
# in any configuration directory is added to the Ruby load path for any
|
28
|
+
# tool file in that directory.
|
29
|
+
# @param middleware_stack [Array<Toys::Middleware::Spec>] An array of
|
30
|
+
# middleware that will be used by default for all tools loaded by this
|
31
|
+
# loader.
|
32
|
+
# @param extra_delimiters [String] A string containing characters that can
|
33
|
+
# function as delimiters in a tool name. Defaults to empty. Allowed
|
34
|
+
# characters are period, colon, and slash.
|
35
|
+
# @param mixin_lookup [Toys::ModuleLookup] A lookup for well-known
|
36
|
+
# mixin modules. Defaults to an empty lookup.
|
37
|
+
# @param middleware_lookup [Toys::ModuleLookup] A lookup for
|
38
|
+
# well-known middleware classes. Defaults to an empty lookup.
|
39
|
+
# @param template_lookup [Toys::ModuleLookup] A lookup for
|
40
|
+
# well-known template classes. Defaults to an empty lookup.
|
41
|
+
#
|
42
|
+
def initialize(index_file_name: nil,
|
43
|
+
preload_dir_name: nil,
|
44
|
+
preload_file_name: nil,
|
45
|
+
data_dir_name: nil,
|
46
|
+
lib_dir_name: nil,
|
47
|
+
middleware_stack: [],
|
48
|
+
extra_delimiters: "",
|
49
|
+
mixin_lookup: nil,
|
50
|
+
middleware_lookup: nil,
|
51
|
+
template_lookup: nil,
|
52
|
+
git_cache: nil)
|
53
|
+
# Source available in the toys-core gem
|
54
|
+
end
|
55
|
+
|
56
|
+
##
|
57
|
+
# Add a configuration file/directory to the loader.
|
58
|
+
#
|
59
|
+
# @param path [String] A single path to add.
|
60
|
+
# @param high_priority [Boolean] If true, add this path at the top of the
|
61
|
+
# priority list. Defaults to false, indicating the new path should be
|
62
|
+
# at the bottom of the priority list.
|
63
|
+
# @param source_name [String] A custom name for the root source. Optional.
|
64
|
+
# @param context_directory [String,nil,:path,:parent] The context directory
|
65
|
+
# for tools loaded from this path. You can pass a directory path as a
|
66
|
+
# string, `:path` to denote the given path, `:parent` to denote the
|
67
|
+
# given path's parent directory, or `nil` to denote no context.
|
68
|
+
# Defaults to `:parent`.
|
69
|
+
# @return [self]
|
70
|
+
#
|
71
|
+
def add_path(path,
|
72
|
+
high_priority: false,
|
73
|
+
source_name: nil,
|
74
|
+
context_directory: :parent)
|
75
|
+
# Source available in the toys-core gem
|
76
|
+
end
|
77
|
+
|
78
|
+
##
|
79
|
+
# Add a set of configuration files/directories from a common directory to
|
80
|
+
# the loader. The set of paths will be added at the same priority level and
|
81
|
+
# will share a root.
|
82
|
+
#
|
83
|
+
# @param root_path [String] A root path to be seen as the root source. This
|
84
|
+
# should generally be a directory containing the paths to add.
|
85
|
+
# @param relative_paths [String,Array<String>] One or more paths to add, as
|
86
|
+
# relative paths from the common root.
|
87
|
+
# @param high_priority [Boolean] If true, add the paths at the top of the
|
88
|
+
# priority list. Defaults to false, indicating the new paths should be
|
89
|
+
# at the bottom of the priority list.
|
90
|
+
# @param context_directory [String,nil,:path,:parent] The context directory
|
91
|
+
# for tools loaded from this path. You can pass a directory path as a
|
92
|
+
# string, `:path` to denote the given root path, `:parent` to denote
|
93
|
+
# the given root path's parent directory, or `nil` to denote no context.
|
94
|
+
# Defaults to `:path`.
|
95
|
+
# @return [self]
|
96
|
+
#
|
97
|
+
def add_path_set(root_path, relative_paths,
|
98
|
+
high_priority: false,
|
99
|
+
context_directory: :path)
|
100
|
+
# Source available in the toys-core gem
|
101
|
+
end
|
102
|
+
|
103
|
+
##
|
104
|
+
# Add a configuration block to the loader.
|
105
|
+
#
|
106
|
+
# @param high_priority [Boolean] If true, add this block at the top of the
|
107
|
+
# priority list. Defaults to false, indicating the block should be at
|
108
|
+
# the bottom of the priority list.
|
109
|
+
# @param source_name [String] The source name that will be shown in
|
110
|
+
# documentation for tools defined in this block. If omitted, a default
|
111
|
+
# unique string will be generated.
|
112
|
+
# @param block [Proc] The block of configuration, executed in the context
|
113
|
+
# of the tool DSL {Toys::DSL::Tool}.
|
114
|
+
# @param context_directory [String,nil] The context directory for tools
|
115
|
+
# loaded from this block. You can pass a directory path as a string, or
|
116
|
+
# `nil` to denote no context. Defaults to `nil`.
|
117
|
+
# @return [self]
|
118
|
+
#
|
119
|
+
def add_block(high_priority: false,
|
120
|
+
source_name: nil,
|
121
|
+
context_directory: nil,
|
122
|
+
&block)
|
123
|
+
# Source available in the toys-core gem
|
124
|
+
end
|
125
|
+
|
126
|
+
##
|
127
|
+
# Add a configuration git source to the loader.
|
128
|
+
#
|
129
|
+
# @param git_remote [String] The git repo URL
|
130
|
+
# @param git_path [String] The path to the relevant file or directory in
|
131
|
+
# the repo. Specify the empty string to use the entire repo.
|
132
|
+
# @param git_commit [String] The git ref (i.e. SHA, tag, or branch name)
|
133
|
+
# @param high_priority [Boolean] If true, add this path at the top of the
|
134
|
+
# priority list. Defaults to false, indicating the new path should be
|
135
|
+
# at the bottom of the priority list.
|
136
|
+
# @param update [Boolean] If the commit is not a SHA, pulls any updates
|
137
|
+
# from the remote. Defaults to false, which uses a local cache and does
|
138
|
+
# not update if the commit has been fetched previously.
|
139
|
+
# @param context_directory [String,nil] The context directory for tools
|
140
|
+
# loaded from this source. You can pass a directory path as a string,
|
141
|
+
# or `nil` to denote no context. Defaults to `nil`.
|
142
|
+
# @return [self]
|
143
|
+
#
|
144
|
+
def add_git(git_remote, git_path, git_commit,
|
145
|
+
high_priority: false,
|
146
|
+
update: false,
|
147
|
+
context_directory: nil)
|
148
|
+
# Source available in the toys-core gem
|
149
|
+
end
|
150
|
+
|
151
|
+
##
|
152
|
+
# Given a list of command line arguments, find the appropriate tool to
|
153
|
+
# handle the command, loading it from the configuration if necessary.
|
154
|
+
# This always returns a tool. If the specific tool path is not defined and
|
155
|
+
# cannot be found in any configuration, it finds the nearest namespace that
|
156
|
+
# *would* contain that tool, up to the root tool.
|
157
|
+
#
|
158
|
+
# Returns a tuple of the found tool, and the array of remaining arguments
|
159
|
+
# that are not part of the tool name and should be passed as tool args.
|
160
|
+
#
|
161
|
+
# @param args [Array<String>] Command line arguments
|
162
|
+
# @return [Array(Toys::ToolDefinition,Array<String>)]
|
163
|
+
#
|
164
|
+
def lookup(args)
|
165
|
+
# Source available in the toys-core gem
|
166
|
+
end
|
167
|
+
|
168
|
+
##
|
169
|
+
# Given a tool name, looks up the specific tool, loading it from the
|
170
|
+
# configuration if necessary.
|
171
|
+
#
|
172
|
+
# If there is an active tool, returns it; otherwise, returns the highest
|
173
|
+
# priority tool that has been defined. If no tool has been defined with
|
174
|
+
# the given name, returns `nil`.
|
175
|
+
#
|
176
|
+
# @param words [Array<String>] The tool name
|
177
|
+
# @return [Toys::ToolDefinition] if the tool was found
|
178
|
+
# @return [nil] if no such tool exists
|
179
|
+
#
|
180
|
+
def lookup_specific(words)
|
181
|
+
# Source available in the toys-core gem
|
182
|
+
end
|
183
|
+
|
184
|
+
##
|
185
|
+
# Returns a list of subtools for the given path, loading from the
|
186
|
+
# configuration if necessary.
|
187
|
+
#
|
188
|
+
# @param words [Array<String>] The name of the parent tool
|
189
|
+
# @param recursive [Boolean] If true, return all subtools recursively
|
190
|
+
# rather than just the immediate children (the default)
|
191
|
+
# @param include_hidden [Boolean] If true, include hidden subtools,
|
192
|
+
# e.g. names beginning with underscores.
|
193
|
+
# @return [Array<Toys::ToolDefinition>] An array of subtools.
|
194
|
+
#
|
195
|
+
def list_subtools(words, recursive: false, include_hidden: false)
|
196
|
+
# Source available in the toys-core gem
|
197
|
+
end
|
198
|
+
|
199
|
+
##
|
200
|
+
# Returns true if the given path has at least one subtool. Loads from the
|
201
|
+
# configuration if necessary.
|
202
|
+
#
|
203
|
+
# @param words [Array<String>] The name of the parent tool
|
204
|
+
# @return [Boolean]
|
205
|
+
#
|
206
|
+
def has_subtools?(words)
|
207
|
+
# Source available in the toys-core gem
|
208
|
+
end
|
209
|
+
|
210
|
+
##
|
211
|
+
# Splits the given path using the delimiters configured in this Loader.
|
212
|
+
# You may pass in either an array of strings, or a single string possibly
|
213
|
+
# delimited by path separators. Always returns an array of strings.
|
214
|
+
#
|
215
|
+
# @param str [String,Symbol,Array<String,Symbol>] The path to split.
|
216
|
+
# @return [Array<String>]
|
217
|
+
#
|
218
|
+
def split_path(str)
|
219
|
+
# Source available in the toys-core gem
|
220
|
+
end
|
221
|
+
end
|
222
|
+
end
|