toys 0.12.2 → 0.13.0
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 +35 -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,329 @@
|
|
1
|
+
module Toys
|
2
|
+
##
|
3
|
+
# **_Defined in the toys-core gem_**
|
4
|
+
#
|
5
|
+
# A Completion is a callable Proc that determines candidates for shell tab
|
6
|
+
# completion. You pass a {Toys::Completion::Context} object (which includes
|
7
|
+
# the current string fragment and other information) and it returns an array
|
8
|
+
# of candidates, represented by {Toys::Completion::Candidate} objects, for
|
9
|
+
# completing the fragment.
|
10
|
+
#
|
11
|
+
# A useful method here is the class method {Toys::Completion.create} which
|
12
|
+
# takes a variety of inputs and returns a suitable completion Proc.
|
13
|
+
#
|
14
|
+
module Completion
|
15
|
+
##
|
16
|
+
# **_Defined in the toys-core gem_**
|
17
|
+
#
|
18
|
+
# The context in which to determine completion candidates.
|
19
|
+
#
|
20
|
+
class Context
|
21
|
+
##
|
22
|
+
# Create a completion context
|
23
|
+
#
|
24
|
+
# @param cli [Toys::CLI] The CLI being run. Required.
|
25
|
+
# @param previous_words [Array<String>] Array of complete strings that
|
26
|
+
# appeared prior to the fragment to complete.
|
27
|
+
# @param fragment_prefix [String] A prefix in the fragment that does not
|
28
|
+
# participate in completion. (e.g. "key=")
|
29
|
+
# @param fragment [String] The string fragment to complete.
|
30
|
+
# @param params [Hash] Miscellaneous context data
|
31
|
+
#
|
32
|
+
def initialize(cli:, previous_words: [], fragment_prefix: "", fragment: "", **params)
|
33
|
+
# Source available in the toys-core gem
|
34
|
+
end
|
35
|
+
|
36
|
+
##
|
37
|
+
# Create a new completion context with the given modifications.
|
38
|
+
#
|
39
|
+
# @param delta_params [Hash] Replace context data.
|
40
|
+
# @return [Toys::Completion::Context]
|
41
|
+
#
|
42
|
+
def with(**delta_params)
|
43
|
+
# Source available in the toys-core gem
|
44
|
+
end
|
45
|
+
|
46
|
+
##
|
47
|
+
# The CLI being run.
|
48
|
+
# @return [Toys::CLI]
|
49
|
+
#
|
50
|
+
attr_reader :cli
|
51
|
+
|
52
|
+
##
|
53
|
+
# All previous words.
|
54
|
+
# @return [Array<String>]
|
55
|
+
#
|
56
|
+
attr_reader :previous_words
|
57
|
+
|
58
|
+
##
|
59
|
+
# A non-completed prefix for the current fragment.
|
60
|
+
# @return [String]
|
61
|
+
#
|
62
|
+
attr_reader :fragment_prefix
|
63
|
+
|
64
|
+
##
|
65
|
+
# The current string fragment to complete
|
66
|
+
# @return [String]
|
67
|
+
#
|
68
|
+
attr_reader :fragment
|
69
|
+
|
70
|
+
##
|
71
|
+
# Get data for arbitrary key.
|
72
|
+
# @param [Symbol] key
|
73
|
+
# @return [Object]
|
74
|
+
#
|
75
|
+
def [](key)
|
76
|
+
# Source available in the toys-core gem
|
77
|
+
end
|
78
|
+
alias get []
|
79
|
+
|
80
|
+
##
|
81
|
+
# The tool being invoked, which should control the completion.
|
82
|
+
# @return [Toys::ToolDefinition]
|
83
|
+
#
|
84
|
+
def tool
|
85
|
+
# Source available in the toys-core gem
|
86
|
+
end
|
87
|
+
|
88
|
+
##
|
89
|
+
# An array of complete arguments passed to the tool, prior to the
|
90
|
+
# fragment to complete.
|
91
|
+
# @return [Array<String>]
|
92
|
+
#
|
93
|
+
def args
|
94
|
+
# Source available in the toys-core gem
|
95
|
+
end
|
96
|
+
|
97
|
+
##
|
98
|
+
# Current ArgParser indicating the status of argument parsing up to
|
99
|
+
# this point.
|
100
|
+
#
|
101
|
+
# @return [Toys::ArgParser]
|
102
|
+
#
|
103
|
+
def arg_parser
|
104
|
+
# Source available in the toys-core gem
|
105
|
+
end
|
106
|
+
end
|
107
|
+
|
108
|
+
##
|
109
|
+
# **_Defined in the toys-core gem_**
|
110
|
+
#
|
111
|
+
# A candidate for completing a string fragment.
|
112
|
+
#
|
113
|
+
# A candidate includes a string representing the potential completed
|
114
|
+
# word, as well as a flag indicating whether it is a *partial* completion
|
115
|
+
# (i.e. a prefix that could still be added to) versus a *final* word.
|
116
|
+
# Generally, tab completion systems should add a trailing space after a
|
117
|
+
# final completion but not after a partial completion.
|
118
|
+
#
|
119
|
+
class Candidate
|
120
|
+
include ::Comparable
|
121
|
+
|
122
|
+
##
|
123
|
+
# Create a new candidate
|
124
|
+
# @param string [String] The candidate string
|
125
|
+
# @param partial [Boolean] Whether the candidate is partial. Defaults
|
126
|
+
# to `false`.
|
127
|
+
#
|
128
|
+
def initialize(string, partial: false)
|
129
|
+
# Source available in the toys-core gem
|
130
|
+
end
|
131
|
+
|
132
|
+
##
|
133
|
+
# Get the candidate string.
|
134
|
+
# @return [String]
|
135
|
+
#
|
136
|
+
attr_reader :string
|
137
|
+
alias to_s string
|
138
|
+
|
139
|
+
##
|
140
|
+
# Determine whether the candidate is partial completion.
|
141
|
+
# @return [Boolean]
|
142
|
+
#
|
143
|
+
def partial?
|
144
|
+
# Source available in the toys-core gem
|
145
|
+
end
|
146
|
+
|
147
|
+
##
|
148
|
+
# Determine whether the candidate is a final completion.
|
149
|
+
# @return [Boolean]
|
150
|
+
#
|
151
|
+
def final?
|
152
|
+
# Source available in the toys-core gem
|
153
|
+
end
|
154
|
+
|
155
|
+
##
|
156
|
+
# Create an array of candidates given an array of strings.
|
157
|
+
#
|
158
|
+
# @param array [Array<String>]
|
159
|
+
# @return [Array<Toys::Completion::Candidate]
|
160
|
+
#
|
161
|
+
def self.new_multi(array, partial: false)
|
162
|
+
# Source available in the toys-core gem
|
163
|
+
end
|
164
|
+
end
|
165
|
+
|
166
|
+
##
|
167
|
+
# **_Defined in the toys-core gem_**
|
168
|
+
#
|
169
|
+
# A base class that returns no completions.
|
170
|
+
#
|
171
|
+
# Completions *may* but do not need to subclass this base class. They
|
172
|
+
# merely need to duck-type `Proc` by implementing the `call` method.
|
173
|
+
#
|
174
|
+
class Base
|
175
|
+
##
|
176
|
+
# Returns candidates for the current completion.
|
177
|
+
# This default implementation returns an empty list.
|
178
|
+
#
|
179
|
+
# @param context [Toys::Completion::Context] The current completion
|
180
|
+
# context including the string fragment.
|
181
|
+
# @return [Array<Toys::Completion::Candidate>] An array of candidates
|
182
|
+
#
|
183
|
+
def call(context)
|
184
|
+
# Source available in the toys-core gem
|
185
|
+
end
|
186
|
+
end
|
187
|
+
|
188
|
+
##
|
189
|
+
# **_Defined in the toys-core gem_**
|
190
|
+
#
|
191
|
+
# A Completion that returns candidates from the local file system.
|
192
|
+
#
|
193
|
+
class FileSystem < Base
|
194
|
+
##
|
195
|
+
# Create a completion that gets candidates from names in the local file
|
196
|
+
# system.
|
197
|
+
#
|
198
|
+
# @param cwd [String] Working directory (defaults to the current dir).
|
199
|
+
# @param omit_files [Boolean] Omit files from candidates
|
200
|
+
# @param omit_directories [Boolean] Omit directories from candidates
|
201
|
+
# @param prefix_constraint [String,Regexp] Constraint on the fragment
|
202
|
+
# prefix. Defaults to requiring the prefix be empty.
|
203
|
+
#
|
204
|
+
def initialize(cwd: nil, omit_files: false, omit_directories: false, prefix_constraint: "")
|
205
|
+
# Source available in the toys-core gem
|
206
|
+
end
|
207
|
+
|
208
|
+
##
|
209
|
+
# Whether files are included in the completion candidates.
|
210
|
+
# @return [Boolean]
|
211
|
+
#
|
212
|
+
attr_reader :include_files
|
213
|
+
|
214
|
+
##
|
215
|
+
# Whether directories are included in the completion candidates.
|
216
|
+
# @return [Boolean]
|
217
|
+
#
|
218
|
+
attr_reader :include_directories
|
219
|
+
|
220
|
+
##
|
221
|
+
# Constraint on the fragment prefix.
|
222
|
+
# @return [String,Regexp]
|
223
|
+
#
|
224
|
+
attr_reader :prefix_constraint
|
225
|
+
|
226
|
+
##
|
227
|
+
# Path to the starting directory.
|
228
|
+
# @return [String]
|
229
|
+
#
|
230
|
+
attr_reader :cwd
|
231
|
+
|
232
|
+
##
|
233
|
+
# Returns candidates for the current completion.
|
234
|
+
#
|
235
|
+
# @param context [Toys::Completion::Context] the current completion
|
236
|
+
# context including the string fragment.
|
237
|
+
# @return [Array<Toys::Completion::Candidate>] an array of candidates
|
238
|
+
#
|
239
|
+
def call(context)
|
240
|
+
# Source available in the toys-core gem
|
241
|
+
end
|
242
|
+
end
|
243
|
+
|
244
|
+
##
|
245
|
+
# **_Defined in the toys-core gem_**
|
246
|
+
#
|
247
|
+
# A Completion whose candidates come from a static list of strings.
|
248
|
+
#
|
249
|
+
class Enum < Base
|
250
|
+
##
|
251
|
+
# Create a completion from a list of values.
|
252
|
+
#
|
253
|
+
# @param values [Array<String>]
|
254
|
+
# @param prefix_constraint [String,Regexp] Constraint on the fragment
|
255
|
+
# prefix. Defaults to requiring the prefix be empty.
|
256
|
+
#
|
257
|
+
def initialize(values, prefix_constraint: "")
|
258
|
+
# Source available in the toys-core gem
|
259
|
+
end
|
260
|
+
|
261
|
+
##
|
262
|
+
# The array of completion candidates.
|
263
|
+
# @return [Array<String>]
|
264
|
+
#
|
265
|
+
attr_reader :values
|
266
|
+
|
267
|
+
##
|
268
|
+
# Constraint on the fragment prefix.
|
269
|
+
# @return [String,Regexp]
|
270
|
+
#
|
271
|
+
attr_reader :prefix_constraint
|
272
|
+
|
273
|
+
##
|
274
|
+
# Returns candidates for the current completion.
|
275
|
+
#
|
276
|
+
# @param context [Toys::Completion::Context] the current completion
|
277
|
+
# context including the string fragment.
|
278
|
+
# @return [Array<Toys::Completion::Candidate>] an array of candidates
|
279
|
+
#
|
280
|
+
def call(context)
|
281
|
+
# Source available in the toys-core gem
|
282
|
+
end
|
283
|
+
end
|
284
|
+
|
285
|
+
##
|
286
|
+
# An instance of the empty completion that returns no candidates.
|
287
|
+
# @return [Toys:::Completion::Base]
|
288
|
+
#
|
289
|
+
EMPTY = Base.new
|
290
|
+
|
291
|
+
##
|
292
|
+
# Create a completion Proc from a variety of specification formats. The
|
293
|
+
# completion is constructed from the given specification object and/or the
|
294
|
+
# given block. Additionally, some completions can take a hash of options.
|
295
|
+
#
|
296
|
+
# Recognized specs include:
|
297
|
+
#
|
298
|
+
# * `:empty`: Returns the empty completion. Any block or options are
|
299
|
+
# ignored.
|
300
|
+
#
|
301
|
+
# * `:file_system`: Returns a completion that searches the current
|
302
|
+
# directory for file and directory names. You may also pass any of the
|
303
|
+
# options recognized by {Toys::Completion::FileSystem#initialize}. The
|
304
|
+
# block is ignored.
|
305
|
+
#
|
306
|
+
# * An **Array** of strings. Returns a completion that uses those values
|
307
|
+
# as candidates. You may also pass any of the options recognized by
|
308
|
+
# {Toys::Completion::Enum#initialize}. The block is ignored.
|
309
|
+
#
|
310
|
+
# * A **function**, either passed as a Proc (where the block is ignored)
|
311
|
+
# or as a block (if the spec is nil). The function must behave as a
|
312
|
+
# completion object, taking {Toys::Completion::Context} as the sole
|
313
|
+
# argument, and returning an array of {Toys::Completion::Candidate}.
|
314
|
+
#
|
315
|
+
# * `:default` and `nil` indicate the **default completion**. For this
|
316
|
+
# method, the default is the empty completion (i.e. these are synonyms
|
317
|
+
# for `:empty`). However, other completion resolution methods might
|
318
|
+
# have a different default.
|
319
|
+
#
|
320
|
+
# @param spec [Object] See the description for recognized values.
|
321
|
+
# @param options [Hash] Additional options to pass to the completion.
|
322
|
+
# @param block [Proc] See the description for recognized forms.
|
323
|
+
# @return [Toys::Completion::Base,Proc]
|
324
|
+
#
|
325
|
+
def self.create(spec = nil, **options, &block)
|
326
|
+
# Source available in the toys-core gem
|
327
|
+
end
|
328
|
+
end
|
329
|
+
end
|
@@ -0,0 +1,321 @@
|
|
1
|
+
module Toys
|
2
|
+
##
|
3
|
+
# **_Defined in the toys-core gem_**
|
4
|
+
#
|
5
|
+
# This is the base class for tool execution. It represents `self` when your
|
6
|
+
# tool's methods (such as `run`) are called, and it defines the methods that
|
7
|
+
# can be called by your tool (such as {#logger} and {#exit}.)
|
8
|
+
#
|
9
|
+
# This class also manages the "data" available to your tool when it runs.
|
10
|
+
# This data is a hash of key-value pairs. It consists of values set by flags
|
11
|
+
# and arguments defined by the tool, plus some "well-known" values such as
|
12
|
+
# the logger and verbosity level.
|
13
|
+
#
|
14
|
+
# You can obtain a value from the data using the {Toys::Context#get} method.
|
15
|
+
# Additionally, convenience methods are provided for many of the well-known
|
16
|
+
# keys. For instance, you can call {Toys::Context#verbosity} to obtain the
|
17
|
+
# value for the key {Toys::Context::Key::VERBOSITY}. Finally, flags and
|
18
|
+
# positional arguments that store their data here will also typically
|
19
|
+
# generate convenience methods. For example, an argument with key `:abc` will
|
20
|
+
# add a method called `abc` that you can call to get the value.
|
21
|
+
#
|
22
|
+
# By convention, flags and arguments defined by your tool should use strings
|
23
|
+
# or symbols as keys. Keys that are not strings or symbols should either be
|
24
|
+
# well-known keys such as {Toys::Context::Key::VERBOSITY}, or should be used
|
25
|
+
# for internal private information needed by middleware and mixins. The
|
26
|
+
# module {Toys::Context::Key} defines a number of well-known keys as
|
27
|
+
# constants.
|
28
|
+
#
|
29
|
+
class Context
|
30
|
+
##
|
31
|
+
# **_Defined in the toys-core gem_**
|
32
|
+
#
|
33
|
+
# Well-known context keys.
|
34
|
+
#
|
35
|
+
# This module is mixed into the runtime context. This means you can
|
36
|
+
# reference any of these constants directly from your run method.
|
37
|
+
#
|
38
|
+
# ### Example
|
39
|
+
#
|
40
|
+
# tool "my-name" do
|
41
|
+
# def run
|
42
|
+
# # TOOL_NAME is available here.
|
43
|
+
# puts "My name is #{get(TOOL_NAME)}"
|
44
|
+
# end
|
45
|
+
# end
|
46
|
+
#
|
47
|
+
module Key
|
48
|
+
##
|
49
|
+
# Context key for the argument list passed to the current tool. Value is
|
50
|
+
# an array of strings.
|
51
|
+
# @return [Object]
|
52
|
+
#
|
53
|
+
ARGS = ::Object.new.freeze
|
54
|
+
|
55
|
+
##
|
56
|
+
# Context key for the currently running {Toys::CLI}. You can use the
|
57
|
+
# value to run other tools from your tool by calling {Toys::CLI#run}.
|
58
|
+
# @return [Object]
|
59
|
+
#
|
60
|
+
CLI = ::Object.new.freeze
|
61
|
+
|
62
|
+
##
|
63
|
+
# Context key for the context directory path. The value is a string
|
64
|
+
# @return [Object]
|
65
|
+
#
|
66
|
+
CONTEXT_DIRECTORY = ::Object.new.freeze
|
67
|
+
|
68
|
+
##
|
69
|
+
# Context key for the context from which the current call was delegated.
|
70
|
+
# The value is either another context object, or `nil` if the current
|
71
|
+
# call is not delegated.
|
72
|
+
# @return [Object]
|
73
|
+
#
|
74
|
+
DELEGATED_FROM = ::Object.new.freeze
|
75
|
+
|
76
|
+
##
|
77
|
+
# Context key for the active `Logger` object.
|
78
|
+
# @return [Object]
|
79
|
+
#
|
80
|
+
LOGGER = ::Object.new.freeze
|
81
|
+
|
82
|
+
##
|
83
|
+
# Context key for the {Toys::ToolDefinition} object being executed.
|
84
|
+
# @return [Object]
|
85
|
+
#
|
86
|
+
TOOL = ::Object.new.freeze
|
87
|
+
|
88
|
+
##
|
89
|
+
# Context key for the full name of the tool being executed. Value is an
|
90
|
+
# array of strings.
|
91
|
+
# @return [Object]
|
92
|
+
#
|
93
|
+
TOOL_NAME = ::Object.new.freeze
|
94
|
+
|
95
|
+
##
|
96
|
+
# Context key for the {Toys::SourceInfo} describing the source of this
|
97
|
+
# tool.
|
98
|
+
# @return [Object]
|
99
|
+
#
|
100
|
+
TOOL_SOURCE = ::Object.new.freeze
|
101
|
+
|
102
|
+
##
|
103
|
+
# Context key for all unmatched args in order. The value is an array of
|
104
|
+
# strings.
|
105
|
+
# @return [Object]
|
106
|
+
#
|
107
|
+
UNMATCHED_ARGS = ::Object.new.freeze
|
108
|
+
|
109
|
+
##
|
110
|
+
# Context key for unmatched flags. The value is an array of strings.
|
111
|
+
# @return [Object]
|
112
|
+
#
|
113
|
+
UNMATCHED_FLAGS = ::Object.new.freeze
|
114
|
+
|
115
|
+
##
|
116
|
+
# Context key for unmatched positional args. The value is an array of
|
117
|
+
# strings.
|
118
|
+
# @return [Object]
|
119
|
+
#
|
120
|
+
UNMATCHED_POSITIONAL = ::Object.new.freeze
|
121
|
+
|
122
|
+
##
|
123
|
+
# Context key for the list of usage errors raised. The value is an array
|
124
|
+
# of {Toys::ArgParser::UsageError}.
|
125
|
+
# @return [Object]
|
126
|
+
#
|
127
|
+
USAGE_ERRORS = ::Object.new.freeze
|
128
|
+
|
129
|
+
##
|
130
|
+
# Context key for the verbosity value. The value is an integer defaulting
|
131
|
+
# to 0, with higher values meaning more verbose and lower meaning more
|
132
|
+
# quiet.
|
133
|
+
# @return [Object]
|
134
|
+
#
|
135
|
+
VERBOSITY = ::Object.new.freeze
|
136
|
+
end
|
137
|
+
|
138
|
+
##
|
139
|
+
# The raw arguments passed to the tool, as an array of strings.
|
140
|
+
# This does not include the tool name itself.
|
141
|
+
#
|
142
|
+
# This is a convenience getter for {Toys::Context::Key::ARGS}.
|
143
|
+
#
|
144
|
+
# @return [Array<String>]
|
145
|
+
#
|
146
|
+
def args
|
147
|
+
# Source available in the toys-core gem
|
148
|
+
end
|
149
|
+
|
150
|
+
##
|
151
|
+
# The currently running CLI.
|
152
|
+
#
|
153
|
+
# This is a convenience getter for {Toys::Context::Key::CLI}.
|
154
|
+
#
|
155
|
+
# @return [Toys::CLI]
|
156
|
+
#
|
157
|
+
def cli
|
158
|
+
# Source available in the toys-core gem
|
159
|
+
end
|
160
|
+
|
161
|
+
##
|
162
|
+
# Return the context directory for this tool. Generally, this defaults
|
163
|
+
# to the directory containing the toys config directory structure being
|
164
|
+
# read, but it may be changed by setting a different context directory
|
165
|
+
# for the tool.
|
166
|
+
#
|
167
|
+
# This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
|
168
|
+
#
|
169
|
+
# @return [String] Context directory path
|
170
|
+
# @return [nil] if there is no context.
|
171
|
+
#
|
172
|
+
def context_directory
|
173
|
+
# Source available in the toys-core gem
|
174
|
+
end
|
175
|
+
|
176
|
+
##
|
177
|
+
# The logger for this execution.
|
178
|
+
#
|
179
|
+
# This is a convenience getter for {Toys::Context::Key::LOGGER}.
|
180
|
+
#
|
181
|
+
# @return [Logger]
|
182
|
+
#
|
183
|
+
def logger
|
184
|
+
# Source available in the toys-core gem
|
185
|
+
end
|
186
|
+
|
187
|
+
##
|
188
|
+
# The full name of the tool being executed, as an array of strings.
|
189
|
+
#
|
190
|
+
# This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
|
191
|
+
#
|
192
|
+
# @return [Array<String>]
|
193
|
+
#
|
194
|
+
def tool_name
|
195
|
+
# Source available in the toys-core gem
|
196
|
+
end
|
197
|
+
|
198
|
+
##
|
199
|
+
# The source of the tool being executed.
|
200
|
+
#
|
201
|
+
# This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
|
202
|
+
#
|
203
|
+
# @return [Toys::SourceInfo]
|
204
|
+
#
|
205
|
+
def tool_source
|
206
|
+
# Source available in the toys-core gem
|
207
|
+
end
|
208
|
+
|
209
|
+
##
|
210
|
+
# The (possibly empty) array of errors detected during argument parsing.
|
211
|
+
#
|
212
|
+
# This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
|
213
|
+
#
|
214
|
+
# @return [Array<Toys::ArgParser::UsageError>]
|
215
|
+
#
|
216
|
+
def usage_errors
|
217
|
+
# Source available in the toys-core gem
|
218
|
+
end
|
219
|
+
|
220
|
+
##
|
221
|
+
# The current verbosity setting as an integer.
|
222
|
+
#
|
223
|
+
# This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
|
224
|
+
#
|
225
|
+
# @return [Integer]
|
226
|
+
#
|
227
|
+
def verbosity
|
228
|
+
# Source available in the toys-core gem
|
229
|
+
end
|
230
|
+
|
231
|
+
##
|
232
|
+
# Fetch an option or other piece of data by key.
|
233
|
+
#
|
234
|
+
# @param key [Symbol]
|
235
|
+
# @return [Object]
|
236
|
+
#
|
237
|
+
def [](key)
|
238
|
+
# Source available in the toys-core gem
|
239
|
+
end
|
240
|
+
alias get []
|
241
|
+
alias __get []
|
242
|
+
|
243
|
+
##
|
244
|
+
# Set an option or other piece of context data by key.
|
245
|
+
#
|
246
|
+
# @param key [Symbol]
|
247
|
+
# @param value [Object]
|
248
|
+
#
|
249
|
+
def []=(key, value)
|
250
|
+
# Source available in the toys-core gem
|
251
|
+
end
|
252
|
+
|
253
|
+
##
|
254
|
+
# Set one or more options or other context data by key.
|
255
|
+
#
|
256
|
+
# @return [self]
|
257
|
+
#
|
258
|
+
# @overload set(key, value)
|
259
|
+
# Set an option or other piece of context data by key.
|
260
|
+
# @param key [Symbol]
|
261
|
+
# @param value [Object]
|
262
|
+
# @return [self]
|
263
|
+
#
|
264
|
+
# @overload set(hash)
|
265
|
+
# Set multiple content data keys and values
|
266
|
+
# @param hash [Hash] The keys and values to set
|
267
|
+
# @return [self]
|
268
|
+
#
|
269
|
+
def set(key, value = nil)
|
270
|
+
# Source available in the toys-core gem
|
271
|
+
end
|
272
|
+
|
273
|
+
##
|
274
|
+
# The subset of the context that uses string or symbol keys. By convention,
|
275
|
+
# this includes keys that are set by tool flags and arguments, but does not
|
276
|
+
# include well-known context values such as verbosity or private context
|
277
|
+
# values used by middleware or mixins.
|
278
|
+
#
|
279
|
+
# @return [Hash]
|
280
|
+
#
|
281
|
+
def options
|
282
|
+
# Source available in the toys-core gem
|
283
|
+
end
|
284
|
+
|
285
|
+
##
|
286
|
+
# Find the given data file or directory in this tool's search path.
|
287
|
+
#
|
288
|
+
# @param path [String] The path to find
|
289
|
+
# @param type [nil,:file,:directory] Type of file system object to find,
|
290
|
+
# or nil to return any type.
|
291
|
+
#
|
292
|
+
# @return [String] Absolute path of the result
|
293
|
+
# @return [nil] if the data was not found.
|
294
|
+
#
|
295
|
+
def find_data(path, type: nil)
|
296
|
+
# Source available in the toys-core gem
|
297
|
+
end
|
298
|
+
|
299
|
+
##
|
300
|
+
# Exit immediately with the given status code
|
301
|
+
#
|
302
|
+
# @param code [Integer] The status code, which should be 0 for no error,
|
303
|
+
# or nonzero for an error condition. Default is 0.
|
304
|
+
# @return [void]
|
305
|
+
#
|
306
|
+
def exit(code = 0)
|
307
|
+
# Source available in the toys-core gem
|
308
|
+
end
|
309
|
+
|
310
|
+
##
|
311
|
+
# Exit immediately with the given status code
|
312
|
+
#
|
313
|
+
# @param code [Integer] The status code, which should be 0 for no error,
|
314
|
+
# or nonzero for an error condition. Default is 0.
|
315
|
+
# @return [void]
|
316
|
+
#
|
317
|
+
def self.exit(code = 0)
|
318
|
+
# Source available in the toys-core gem
|
319
|
+
end
|
320
|
+
end
|
321
|
+
end
|
@@ -0,0 +1,56 @@
|
|
1
|
+
##
|
2
|
+
# Create a base class for defining a tool with a given name.
|
3
|
+
#
|
4
|
+
# This method returns a base class for defining a tool with a given name.
|
5
|
+
# This is useful if the naming behavior of {Toys::Tool} is not adequate for
|
6
|
+
# your tool.
|
7
|
+
#
|
8
|
+
# ### Example
|
9
|
+
#
|
10
|
+
# class FooBar < Toys.Tool("Foo_Bar")
|
11
|
+
# desc "This is a tool called Foo_Bar"
|
12
|
+
#
|
13
|
+
# def run
|
14
|
+
# puts "Foo_Bar called"
|
15
|
+
# end
|
16
|
+
# end
|
17
|
+
#
|
18
|
+
# @param name [String] Name of the tool. Defaults to a name inferred from the
|
19
|
+
# class name. (See {Toys::Tool}.)
|
20
|
+
# @param base [Class] Use this tool class as the base class, and inherit helper
|
21
|
+
# methods from it.
|
22
|
+
# @param args [String,Class] Any string-valued positional argument is
|
23
|
+
# interpreted as the name. Any class-valued positional argument is
|
24
|
+
# interpreted as the base class.
|
25
|
+
#
|
26
|
+
def Toys.Tool(*args, name: nil, base: nil)
|
27
|
+
# Source available in the toys-core gem
|
28
|
+
end
|
29
|
+
|
30
|
+
module Toys
|
31
|
+
##
|
32
|
+
# **_Defined in the toys-core gem_**
|
33
|
+
#
|
34
|
+
# Base class for defining tools
|
35
|
+
#
|
36
|
+
# This base class provides an alternative to the {Toys::DSL::Tool#tool}
|
37
|
+
# directive for defining tools in the Toys DSL. Creating a subclass of
|
38
|
+
# `Toys::Tool` will create a tool whose name is the "kebab-case" of the class
|
39
|
+
# name. Subclasses can be created only in the context of a tool configuration
|
40
|
+
# DSL. Furthermore, a class-defined tool can be created only at the top level
|
41
|
+
# of a configuration file, or within another class-defined tool. It cannot
|
42
|
+
# be a subtool of a tool block.
|
43
|
+
#
|
44
|
+
# ### Example
|
45
|
+
#
|
46
|
+
# class FooBar < Toys::Tool
|
47
|
+
# desc "This is a tool called foo-bar"
|
48
|
+
#
|
49
|
+
# def run
|
50
|
+
# puts "foo-bar called"
|
51
|
+
# end
|
52
|
+
# end
|
53
|
+
#
|
54
|
+
class Tool < Context
|
55
|
+
end
|
56
|
+
end
|