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,926 @@
|
|
1
|
+
module Toys
|
2
|
+
##
|
3
|
+
# **_Defined in the toys-core gem_**
|
4
|
+
#
|
5
|
+
# A ToolDefinition describes a single command that can be invoked using Toys.
|
6
|
+
# It has a name, a series of one or more words that you use to identify
|
7
|
+
# the tool on the command line. It also has a set of formal flags and
|
8
|
+
# command line arguments supported, and a block that gets run when the
|
9
|
+
# tool is executed.
|
10
|
+
#
|
11
|
+
class ToolDefinition
|
12
|
+
##
|
13
|
+
# **_Defined in the toys-core gem_**
|
14
|
+
#
|
15
|
+
# A Completion that implements the default algorithm for a tool.
|
16
|
+
#
|
17
|
+
class DefaultCompletion < Completion::Base
|
18
|
+
##
|
19
|
+
# Create a completion given configuration options.
|
20
|
+
#
|
21
|
+
# @param complete_subtools [Boolean] Whether to complete subtool names
|
22
|
+
# @param include_hidden_subtools [Boolean] Whether to include hidden
|
23
|
+
# subtools (i.e. those beginning with an underscore)
|
24
|
+
# @param complete_args [Boolean] Whether to complete positional args
|
25
|
+
# @param complete_flags [Boolean] Whether to complete flag names
|
26
|
+
# @param complete_flag_values [Boolean] Whether to complete flag values
|
27
|
+
# @param delegation_target [Array<String>,nil] Delegation target, or
|
28
|
+
# `nil` if none.
|
29
|
+
#
|
30
|
+
def initialize(complete_subtools: true, include_hidden_subtools: false,
|
31
|
+
complete_args: true, complete_flags: true, complete_flag_values: true,
|
32
|
+
delegation_target: nil)
|
33
|
+
# Source available in the toys-core gem
|
34
|
+
end
|
35
|
+
|
36
|
+
##
|
37
|
+
# Whether to complete subtool names
|
38
|
+
# @return [Boolean]
|
39
|
+
#
|
40
|
+
def complete_subtools?
|
41
|
+
# Source available in the toys-core gem
|
42
|
+
end
|
43
|
+
|
44
|
+
##
|
45
|
+
# Whether to include hidden subtools
|
46
|
+
# @return [Boolean]
|
47
|
+
#
|
48
|
+
def include_hidden_subtools?
|
49
|
+
# Source available in the toys-core gem
|
50
|
+
end
|
51
|
+
|
52
|
+
##
|
53
|
+
# Whether to complete flags
|
54
|
+
# @return [Boolean]
|
55
|
+
#
|
56
|
+
def complete_flags?
|
57
|
+
# Source available in the toys-core gem
|
58
|
+
end
|
59
|
+
|
60
|
+
##
|
61
|
+
# Whether to complete positional args
|
62
|
+
# @return [Boolean]
|
63
|
+
#
|
64
|
+
def complete_args?
|
65
|
+
# Source available in the toys-core gem
|
66
|
+
end
|
67
|
+
|
68
|
+
##
|
69
|
+
# Whether to complete flag values
|
70
|
+
# @return [Boolean]
|
71
|
+
#
|
72
|
+
def complete_flag_values?
|
73
|
+
# Source available in the toys-core gem
|
74
|
+
end
|
75
|
+
|
76
|
+
##
|
77
|
+
# Delegation target, or nil for none.
|
78
|
+
# @return [Array<String>] if there is a delegation target
|
79
|
+
# @return [nil] if there is no delegation target
|
80
|
+
#
|
81
|
+
attr_accessor :delegation_target
|
82
|
+
|
83
|
+
##
|
84
|
+
# Returns candidates for the current completion.
|
85
|
+
#
|
86
|
+
# @param context [Toys::Completion::Context] the current completion
|
87
|
+
# context including the string fragment.
|
88
|
+
# @return [Array<Toys::Completion::Candidate>] an array of candidates
|
89
|
+
#
|
90
|
+
def call(context)
|
91
|
+
# Source available in the toys-core gem
|
92
|
+
end
|
93
|
+
end
|
94
|
+
|
95
|
+
##
|
96
|
+
# **_Defined in the toys-core gem_**
|
97
|
+
#
|
98
|
+
# Tool-based settings class.
|
99
|
+
#
|
100
|
+
# The following settings are supported:
|
101
|
+
#
|
102
|
+
# * `propagate_helper_methods` (_Boolean_) - Whether subtools should
|
103
|
+
# inherit methods defined by parent tools. Defaults to `false`.
|
104
|
+
#
|
105
|
+
class Settings < ::Toys::Settings
|
106
|
+
settings_attr :propagate_helper_methods, default: false
|
107
|
+
end
|
108
|
+
|
109
|
+
##
|
110
|
+
# Settings for this tool
|
111
|
+
#
|
112
|
+
# @return [Toys::Tool::Settings]
|
113
|
+
#
|
114
|
+
attr_reader :settings
|
115
|
+
|
116
|
+
##
|
117
|
+
# The name of the tool as an array of strings.
|
118
|
+
# This array may not be modified.
|
119
|
+
#
|
120
|
+
# @return [Array<String>]
|
121
|
+
#
|
122
|
+
attr_reader :full_name
|
123
|
+
|
124
|
+
##
|
125
|
+
# The priority of this tool definition.
|
126
|
+
#
|
127
|
+
# @return [Integer]
|
128
|
+
#
|
129
|
+
attr_reader :priority
|
130
|
+
|
131
|
+
##
|
132
|
+
# The root source info defining this tool, or nil if there is no source.
|
133
|
+
#
|
134
|
+
# @return [Toys::SourceInfo,nil]
|
135
|
+
#
|
136
|
+
attr_reader :source_root
|
137
|
+
|
138
|
+
##
|
139
|
+
# The tool class.
|
140
|
+
#
|
141
|
+
# @return [Class]
|
142
|
+
#
|
143
|
+
attr_reader :tool_class
|
144
|
+
|
145
|
+
##
|
146
|
+
# The short description string.
|
147
|
+
#
|
148
|
+
# When reading, this is always returned as a {Toys::WrappableString}.
|
149
|
+
#
|
150
|
+
# When setting, the description may be provided as any of the following:
|
151
|
+
# * A {Toys::WrappableString}.
|
152
|
+
# * A normal String, which will be transformed into a
|
153
|
+
# {Toys::WrappableString} using spaces as word delimiters.
|
154
|
+
# * An Array of String, which will be transformed into a
|
155
|
+
# {Toys::WrappableString} where each array element represents an
|
156
|
+
# individual word for wrapping.
|
157
|
+
#
|
158
|
+
# @return [Toys::WrappableString]
|
159
|
+
#
|
160
|
+
attr_reader :desc
|
161
|
+
|
162
|
+
##
|
163
|
+
# The long description strings.
|
164
|
+
#
|
165
|
+
# When reading, this is returned as an Array of {Toys::WrappableString}
|
166
|
+
# representing the lines in the description.
|
167
|
+
#
|
168
|
+
# When setting, the description must be provided as an Array where *each
|
169
|
+
# element* may be any of the following:
|
170
|
+
# * A {Toys::WrappableString} representing one line.
|
171
|
+
# * A normal String representing a line. This will be transformed into a
|
172
|
+
# {Toys::WrappableString} using spaces as word delimiters.
|
173
|
+
# * An Array of String representing a line. This will be transformed into
|
174
|
+
# a {Toys::WrappableString} where each array element represents an
|
175
|
+
# individual word for wrapping.
|
176
|
+
#
|
177
|
+
# @return [Array<Toys::WrappableString>]
|
178
|
+
#
|
179
|
+
attr_reader :long_desc
|
180
|
+
|
181
|
+
##
|
182
|
+
# A list of all defined flag groups, in order.
|
183
|
+
#
|
184
|
+
# @return [Array<Toys::FlagGroup>]
|
185
|
+
#
|
186
|
+
attr_reader :flag_groups
|
187
|
+
|
188
|
+
##
|
189
|
+
# A list of all defined flags.
|
190
|
+
#
|
191
|
+
# @return [Array<Toys::Flag>]
|
192
|
+
#
|
193
|
+
attr_reader :flags
|
194
|
+
|
195
|
+
##
|
196
|
+
# A list of all defined required positional arguments.
|
197
|
+
#
|
198
|
+
# @return [Array<Toys::PositionalArg>]
|
199
|
+
#
|
200
|
+
attr_reader :required_args
|
201
|
+
|
202
|
+
##
|
203
|
+
# A list of all defined optional positional arguments.
|
204
|
+
#
|
205
|
+
# @return [Array<Toys::PositionalArg>]
|
206
|
+
#
|
207
|
+
attr_reader :optional_args
|
208
|
+
|
209
|
+
##
|
210
|
+
# The remaining arguments specification.
|
211
|
+
#
|
212
|
+
# @return [Toys::PositionalArg] The argument definition
|
213
|
+
# @return [nil] if remaining arguments are not supported by this tool.
|
214
|
+
#
|
215
|
+
attr_reader :remaining_arg
|
216
|
+
|
217
|
+
##
|
218
|
+
# A list of flags that have been used in the flag definitions.
|
219
|
+
#
|
220
|
+
# @return [Array<String>]
|
221
|
+
#
|
222
|
+
attr_reader :used_flags
|
223
|
+
|
224
|
+
##
|
225
|
+
# The default context data set by arguments.
|
226
|
+
#
|
227
|
+
# @return [Hash]
|
228
|
+
#
|
229
|
+
attr_reader :default_data
|
230
|
+
|
231
|
+
##
|
232
|
+
# The stack of middleware specs used for subtools.
|
233
|
+
#
|
234
|
+
# This array may be modified in place.
|
235
|
+
#
|
236
|
+
# @return [Array<Toys::Middleware::Spec>]
|
237
|
+
#
|
238
|
+
attr_reader :subtool_middleware_stack
|
239
|
+
|
240
|
+
##
|
241
|
+
# The stack of built middleware specs for this tool.
|
242
|
+
#
|
243
|
+
# @return [Array<Toys::Middleware>]
|
244
|
+
#
|
245
|
+
attr_reader :built_middleware
|
246
|
+
|
247
|
+
##
|
248
|
+
# Info on the source of this tool.
|
249
|
+
#
|
250
|
+
# @return [Toys::SourceInfo] The source info
|
251
|
+
# @return [nil] if the source is not defined.
|
252
|
+
#
|
253
|
+
attr_reader :source_info
|
254
|
+
|
255
|
+
##
|
256
|
+
# The custom context directory set for this tool.
|
257
|
+
#
|
258
|
+
# @return [String] The directory path
|
259
|
+
# @return [nil] if no custom context directory is set.
|
260
|
+
#
|
261
|
+
attr_reader :custom_context_directory
|
262
|
+
|
263
|
+
##
|
264
|
+
# The completion strategy for this tool.
|
265
|
+
#
|
266
|
+
# When reading, this may return an instance of one of the subclasses of
|
267
|
+
# {Toys::Completion::Base}, or a Proc that duck-types it. Generally, this
|
268
|
+
# defaults to a {Toys::ToolDefinition::DefaultCompletion}, providing a
|
269
|
+
# standard algorithm that finds appropriate completions from flags,
|
270
|
+
# positional arguments, and subtools.
|
271
|
+
#
|
272
|
+
# When setting, you may pass any of the following:
|
273
|
+
# * `nil` or `:default` which sets the value to a default instance.
|
274
|
+
# * A Hash of options to pass to the
|
275
|
+
# {Toys::ToolDefinition::DefaultCompletion} constructor.
|
276
|
+
# * Any other form recognized by {Toys::Completion.create}.
|
277
|
+
#
|
278
|
+
# @return [Toys::Completion::Base,Proc]
|
279
|
+
#
|
280
|
+
attr_reader :completion
|
281
|
+
|
282
|
+
##
|
283
|
+
# The interrupt handler.
|
284
|
+
#
|
285
|
+
# @return [Proc] The interrupt handler proc
|
286
|
+
# @return [Symbol] The name of a method to call
|
287
|
+
# @return [nil] if there is no interrupt handler
|
288
|
+
#
|
289
|
+
attr_reader :interrupt_handler
|
290
|
+
|
291
|
+
##
|
292
|
+
# The usage error handler.
|
293
|
+
#
|
294
|
+
# @return [Proc] The usage error handler proc
|
295
|
+
# @return [Symbol] The name of a method to call
|
296
|
+
# @return [nil] if there is no usage error handler
|
297
|
+
#
|
298
|
+
attr_reader :usage_error_handler
|
299
|
+
|
300
|
+
##
|
301
|
+
# The full name of the delegate target, if any.
|
302
|
+
#
|
303
|
+
# @return [Array<String>] if this tool delegates
|
304
|
+
# @return [nil] if this tool does not delegate
|
305
|
+
#
|
306
|
+
attr_reader :delegate_target
|
307
|
+
|
308
|
+
##
|
309
|
+
# The local name of this tool, i.e. the last element of the full name.
|
310
|
+
#
|
311
|
+
# @return [String]
|
312
|
+
#
|
313
|
+
def simple_name
|
314
|
+
# Source available in the toys-core gem
|
315
|
+
end
|
316
|
+
|
317
|
+
##
|
318
|
+
# A displayable name of this tool, generally the full name delimited by
|
319
|
+
# spaces.
|
320
|
+
#
|
321
|
+
# @return [String]
|
322
|
+
#
|
323
|
+
def display_name
|
324
|
+
# Source available in the toys-core gem
|
325
|
+
end
|
326
|
+
|
327
|
+
##
|
328
|
+
# Returns true if this tool is a root tool.
|
329
|
+
# @return [Boolean]
|
330
|
+
#
|
331
|
+
def root?
|
332
|
+
# Source available in the toys-core gem
|
333
|
+
end
|
334
|
+
|
335
|
+
##
|
336
|
+
# Returns true if this tool is marked as runnable.
|
337
|
+
# @return [Boolean]
|
338
|
+
#
|
339
|
+
def runnable?
|
340
|
+
# Source available in the toys-core gem
|
341
|
+
end
|
342
|
+
|
343
|
+
##
|
344
|
+
# Returns true if this tool handles interrupts.
|
345
|
+
# @return [Boolean]
|
346
|
+
#
|
347
|
+
def handles_interrupts?
|
348
|
+
# Source available in the toys-core gem
|
349
|
+
end
|
350
|
+
|
351
|
+
##
|
352
|
+
# Returns true if this tool handles usage errors.
|
353
|
+
# @return [Boolean]
|
354
|
+
#
|
355
|
+
def handles_usage_errors?
|
356
|
+
# Source available in the toys-core gem
|
357
|
+
end
|
358
|
+
|
359
|
+
##
|
360
|
+
# Returns true if this tool has at least one included module.
|
361
|
+
# @return [Boolean]
|
362
|
+
#
|
363
|
+
def includes_modules?
|
364
|
+
# Source available in the toys-core gem
|
365
|
+
end
|
366
|
+
|
367
|
+
##
|
368
|
+
# Returns true if there is a specific description set for this tool.
|
369
|
+
# @return [Boolean]
|
370
|
+
#
|
371
|
+
def includes_description?
|
372
|
+
# Source available in the toys-core gem
|
373
|
+
end
|
374
|
+
|
375
|
+
##
|
376
|
+
# Returns true if at least one flag or positional argument is defined
|
377
|
+
# for this tool.
|
378
|
+
# @return [Boolean]
|
379
|
+
#
|
380
|
+
def includes_arguments?
|
381
|
+
# Source available in the toys-core gem
|
382
|
+
end
|
383
|
+
|
384
|
+
##
|
385
|
+
# Returns true if this tool has any definition information.
|
386
|
+
# @return [Boolean]
|
387
|
+
#
|
388
|
+
def includes_definition?
|
389
|
+
# Source available in the toys-core gem
|
390
|
+
end
|
391
|
+
|
392
|
+
##
|
393
|
+
# Returns true if this tool's definition has been finished and is locked.
|
394
|
+
# @return [Boolean]
|
395
|
+
#
|
396
|
+
def definition_finished?
|
397
|
+
# Source available in the toys-core gem
|
398
|
+
end
|
399
|
+
|
400
|
+
##
|
401
|
+
# Returns true if this tool has disabled argument parsing.
|
402
|
+
# @return [Boolean]
|
403
|
+
#
|
404
|
+
def argument_parsing_disabled?
|
405
|
+
# Source available in the toys-core gem
|
406
|
+
end
|
407
|
+
|
408
|
+
##
|
409
|
+
# Returns true if this tool enforces flags before args.
|
410
|
+
# @return [Boolean]
|
411
|
+
#
|
412
|
+
def flags_before_args_enforced?
|
413
|
+
# Source available in the toys-core gem
|
414
|
+
end
|
415
|
+
|
416
|
+
##
|
417
|
+
# Returns true if this tool requires exact flag matches.
|
418
|
+
# @return [Boolean]
|
419
|
+
#
|
420
|
+
def exact_flag_match_required?
|
421
|
+
# Source available in the toys-core gem
|
422
|
+
end
|
423
|
+
|
424
|
+
##
|
425
|
+
# All arg definitions in order: required, optional, remaining.
|
426
|
+
#
|
427
|
+
# @return [Array<Toys::PositionalArg>]
|
428
|
+
#
|
429
|
+
def positional_args
|
430
|
+
# Source available in the toys-core gem
|
431
|
+
end
|
432
|
+
|
433
|
+
##
|
434
|
+
# Resolve the given flag given the flag string. Returns an object that
|
435
|
+
# describes the resolution result, including whether the resolution
|
436
|
+
# matched a unique flag, the specific flag syntax that was matched, and
|
437
|
+
# additional information.
|
438
|
+
#
|
439
|
+
# @param str [String] Flag string
|
440
|
+
# @return [Toys::Flag::Resolution]
|
441
|
+
#
|
442
|
+
def resolve_flag(str)
|
443
|
+
# Source available in the toys-core gem
|
444
|
+
end
|
445
|
+
|
446
|
+
##
|
447
|
+
# Get the named acceptor from this tool or its ancestors.
|
448
|
+
#
|
449
|
+
# @param name [String] The acceptor name.
|
450
|
+
# @return [Toys::Acceptor::Base] The acceptor.
|
451
|
+
# @return [nil] if no acceptor of the given name is found.
|
452
|
+
#
|
453
|
+
def lookup_acceptor(name)
|
454
|
+
# Source available in the toys-core gem
|
455
|
+
end
|
456
|
+
|
457
|
+
##
|
458
|
+
# Get the named template from this tool or its ancestors.
|
459
|
+
#
|
460
|
+
# @param name [String] The template name.
|
461
|
+
# @return [Class,nil] The template class.
|
462
|
+
# @return [nil] if no template of the given name is found.
|
463
|
+
#
|
464
|
+
def lookup_template(name)
|
465
|
+
# Source available in the toys-core gem
|
466
|
+
end
|
467
|
+
|
468
|
+
##
|
469
|
+
# Get the named mixin from this tool or its ancestors.
|
470
|
+
#
|
471
|
+
# @param name [String] The mixin name.
|
472
|
+
# @return [Module] The mixin module.
|
473
|
+
# @return [nil] if no mixin of the given name is found.
|
474
|
+
#
|
475
|
+
def lookup_mixin(name)
|
476
|
+
# Source available in the toys-core gem
|
477
|
+
end
|
478
|
+
|
479
|
+
##
|
480
|
+
# Get the named completion from this tool or its ancestors.
|
481
|
+
#
|
482
|
+
# @param name [String] The completion name
|
483
|
+
# @return [Toys::Completion::Base,Proc] The completion proc.
|
484
|
+
# @return [nil] if no completion of the given name is found.
|
485
|
+
#
|
486
|
+
def lookup_completion(name)
|
487
|
+
# Source available in the toys-core gem
|
488
|
+
end
|
489
|
+
|
490
|
+
##
|
491
|
+
# Include the given mixin in the tool class.
|
492
|
+
#
|
493
|
+
# The mixin must be given as a module. You can use {#lookup_mixin} to
|
494
|
+
# resolve named mixins.
|
495
|
+
#
|
496
|
+
# @param mod [Module] The mixin module
|
497
|
+
# @return [self]
|
498
|
+
#
|
499
|
+
def include_mixin(mod, *args, **kwargs)
|
500
|
+
# Source available in the toys-core gem
|
501
|
+
end
|
502
|
+
|
503
|
+
##
|
504
|
+
# Sets the path to the file that defines this tool.
|
505
|
+
# A tool may be defined from at most one path. If a different path is
|
506
|
+
# already set, it is left unchanged.
|
507
|
+
#
|
508
|
+
# @param source [Toys::SourceInfo] Source info
|
509
|
+
# @return [self]
|
510
|
+
#
|
511
|
+
def lock_source(source)
|
512
|
+
# Source available in the toys-core gem
|
513
|
+
end
|
514
|
+
|
515
|
+
##
|
516
|
+
# Set the short description string.
|
517
|
+
#
|
518
|
+
# See {#desc} for details.
|
519
|
+
#
|
520
|
+
# @param desc [Toys::WrappableString,String,Array<String>]
|
521
|
+
#
|
522
|
+
def desc=(desc)
|
523
|
+
# Source available in the toys-core gem
|
524
|
+
end
|
525
|
+
|
526
|
+
##
|
527
|
+
# Set the long description strings.
|
528
|
+
#
|
529
|
+
# See {#long_desc} for details.
|
530
|
+
#
|
531
|
+
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
|
532
|
+
#
|
533
|
+
def long_desc=(long_desc)
|
534
|
+
# Source available in the toys-core gem
|
535
|
+
end
|
536
|
+
|
537
|
+
##
|
538
|
+
# Append long description strings.
|
539
|
+
#
|
540
|
+
# You must pass an array of lines in the long description. See {#long_desc}
|
541
|
+
# for details on how each line may be represented.
|
542
|
+
#
|
543
|
+
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
|
544
|
+
# @return [self]
|
545
|
+
#
|
546
|
+
def append_long_desc(long_desc)
|
547
|
+
# Source available in the toys-core gem
|
548
|
+
end
|
549
|
+
|
550
|
+
##
|
551
|
+
# Add a named acceptor to the tool. This acceptor may be refereneced by
|
552
|
+
# name when adding a flag or an arg. See {Toys::Acceptor.create} for
|
553
|
+
# detailed information on how to specify an acceptor.
|
554
|
+
#
|
555
|
+
# @param name [String] The name of the acceptor.
|
556
|
+
# @param acceptor [Toys::Acceptor::Base,Object] The acceptor to add. You
|
557
|
+
# can provide either an acceptor object, or a spec understood by
|
558
|
+
# {Toys::Acceptor.create}.
|
559
|
+
# @param type_desc [String] Type description string, shown in help.
|
560
|
+
# Defaults to the acceptor name.
|
561
|
+
# @param block [Proc] Optional block used to create an acceptor. See
|
562
|
+
# {Toys::Acceptor.create}.
|
563
|
+
# @return [self]
|
564
|
+
#
|
565
|
+
def add_acceptor(name, acceptor = nil, type_desc: nil, &block)
|
566
|
+
# Source available in the toys-core gem
|
567
|
+
end
|
568
|
+
|
569
|
+
##
|
570
|
+
# Add a named mixin module to this tool.
|
571
|
+
# You may provide a mixin module or a block that configures one.
|
572
|
+
#
|
573
|
+
# @param name [String] The name of the mixin.
|
574
|
+
# @param mixin_module [Module] The mixin module.
|
575
|
+
# @param block [Proc] Define the mixin module here if a `mixin_module` is
|
576
|
+
# not provided directly.
|
577
|
+
# @return [self]
|
578
|
+
#
|
579
|
+
def add_mixin(name, mixin_module = nil, &block)
|
580
|
+
# Source available in the toys-core gem
|
581
|
+
end
|
582
|
+
|
583
|
+
##
|
584
|
+
# Add a named completion proc to this tool. The completion may be
|
585
|
+
# referenced by name when adding a flag or an arg. See
|
586
|
+
# {Toys::Completion.create} for detailed information on how to specify a
|
587
|
+
# completion.
|
588
|
+
#
|
589
|
+
# @param name [String] The name of the completion.
|
590
|
+
# @param completion [Proc,Toys::Completion::Base,Object] The completion to
|
591
|
+
# add. You can provide either a completion object, or a spec understood
|
592
|
+
# by {Toys::Completion.create}.
|
593
|
+
# @param options [Hash] Additional options to pass to the completion.
|
594
|
+
# @param block [Proc] Optional block used to create a completion. See
|
595
|
+
# {Toys::Completion.create}.
|
596
|
+
# @return [self]
|
597
|
+
#
|
598
|
+
def add_completion(name, completion = nil, **options, &block)
|
599
|
+
# Source available in the toys-core gem
|
600
|
+
end
|
601
|
+
|
602
|
+
##
|
603
|
+
# Add a named template class to this tool.
|
604
|
+
# You may provide a template class or a block that configures one.
|
605
|
+
#
|
606
|
+
# @param name [String] The name of the template.
|
607
|
+
# @param template_class [Class] The template class.
|
608
|
+
# @param block [Proc] Define the template class here if a `template_class`
|
609
|
+
# is not provided directly.
|
610
|
+
# @return [self]
|
611
|
+
#
|
612
|
+
def add_template(name, template_class = nil, &block)
|
613
|
+
# Source available in the toys-core gem
|
614
|
+
end
|
615
|
+
|
616
|
+
##
|
617
|
+
# Disable argument parsing for this tool.
|
618
|
+
#
|
619
|
+
# @return [self]
|
620
|
+
#
|
621
|
+
def disable_argument_parsing
|
622
|
+
# Source available in the toys-core gem
|
623
|
+
end
|
624
|
+
|
625
|
+
##
|
626
|
+
# Enforce that flags must come before args for this tool.
|
627
|
+
# You may disable enforcement by passoing `false` for the state.
|
628
|
+
#
|
629
|
+
# @param state [Boolean]
|
630
|
+
# @return [self]
|
631
|
+
#
|
632
|
+
def enforce_flags_before_args(state = true)
|
633
|
+
# Source available in the toys-core gem
|
634
|
+
end
|
635
|
+
|
636
|
+
##
|
637
|
+
# Require that flags must match exactly. (If false, flags can match an
|
638
|
+
# unambiguous substring.)
|
639
|
+
#
|
640
|
+
# @param state [Boolean]
|
641
|
+
# @return [self]
|
642
|
+
#
|
643
|
+
def require_exact_flag_match(state = true)
|
644
|
+
# Source available in the toys-core gem
|
645
|
+
end
|
646
|
+
|
647
|
+
##
|
648
|
+
# Add a flag group to the group list.
|
649
|
+
#
|
650
|
+
# The type should be one of the following symbols:
|
651
|
+
# * `:optional` All flags in the group are optional
|
652
|
+
# * `:required` All flags in the group are required
|
653
|
+
# * `:exactly_one` Exactly one flag in the group must be provided
|
654
|
+
# * `:at_least_one` At least one flag in the group must be provided
|
655
|
+
# * `:at_most_one` At most one flag in the group must be provided
|
656
|
+
#
|
657
|
+
# @param type [Symbol] The type of group. Default is `:optional`.
|
658
|
+
# @param desc [String,Array<String>,Toys::WrappableString] Short
|
659
|
+
# description for the group. See {Toys::ToolDefinition#desc} for a
|
660
|
+
# description of allowed formats. Defaults to `"Flags"`.
|
661
|
+
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
|
662
|
+
# Long description for the flag group. See
|
663
|
+
# {Toys::ToolDefinition#long_desc} for a description of allowed
|
664
|
+
# formats. Defaults to the empty array.
|
665
|
+
# @param name [String,Symbol,nil] The name of the group, or nil for no
|
666
|
+
# name.
|
667
|
+
# @param report_collisions [Boolean] If `true`, raise an exception if a
|
668
|
+
# the given name is already taken. If `false`, ignore. Default is
|
669
|
+
# `true`.
|
670
|
+
# @param prepend [Boolean] If `true`, prepend rather than append the
|
671
|
+
# group to the list. Default is `false`.
|
672
|
+
# @return [self]
|
673
|
+
#
|
674
|
+
def add_flag_group(type: :optional, desc: nil, long_desc: nil,
|
675
|
+
name: nil, report_collisions: true, prepend: false)
|
676
|
+
# Source available in the toys-core gem
|
677
|
+
end
|
678
|
+
|
679
|
+
##
|
680
|
+
# Add a flag to the current tool. Each flag must specify a key which
|
681
|
+
# the script may use to obtain the flag value from the context.
|
682
|
+
# You may then provide the flags themselves in `OptionParser` form.
|
683
|
+
#
|
684
|
+
# @param key [String,Symbol] The key to use to retrieve the value from
|
685
|
+
# the execution context.
|
686
|
+
# @param flags [Array<String>] The flags in OptionParser format. If empty,
|
687
|
+
# a flag will be inferred from the key.
|
688
|
+
# @param accept [Object] An acceptor that validates and/or converts the
|
689
|
+
# value. You may provide either the name of an acceptor you have
|
690
|
+
# defined, or one of the default acceptors provided by OptionParser.
|
691
|
+
# Optional. If not specified, accepts any value as a string.
|
692
|
+
# @param default [Object] The default value. This is the value that will
|
693
|
+
# be set in the context if this flag is not provided on the command
|
694
|
+
# line. Defaults to `nil`.
|
695
|
+
# @param handler [Proc,nil,:set,:push] An optional handler for
|
696
|
+
# setting/updating the value. A handler is a proc taking two
|
697
|
+
# arguments, the given value and the previous value, returning the
|
698
|
+
# new value that should be set. You may also specify a predefined
|
699
|
+
# named handler. The `:set` handler (the default) replaces the
|
700
|
+
# previous value (effectively `-> (val, _prev) { val }`). The
|
701
|
+
# `:push` handler expects the previous value to be an array and
|
702
|
+
# pushes the given value onto it; it should be combined with setting
|
703
|
+
# `default: []` and is intended for "multi-valued" flags.
|
704
|
+
# @param complete_flags [Object] A specifier for shell tab completion
|
705
|
+
# for flag names associated with this flag. By default, a
|
706
|
+
# {Toys::Flag::DefaultCompletion} is used, which provides the flag's
|
707
|
+
# names as completion candidates. To customize completion, set this to
|
708
|
+
# a hash of options to pass to the constructor for
|
709
|
+
# {Toys::Flag::DefaultCompletion}, or pass any other spec recognized
|
710
|
+
# by {Toys::Completion.create}.
|
711
|
+
# @param complete_values [Object] A specifier for shell tab completion
|
712
|
+
# for flag values associated with this flag. Pass any spec
|
713
|
+
# recognized by {Toys::Completion.create}.
|
714
|
+
# @param report_collisions [Boolean] Raise an exception if a flag is
|
715
|
+
# requested that is already in use or marked as disabled. Default is
|
716
|
+
# true.
|
717
|
+
# @param group [Toys::FlagGroup,String,Symbol,nil] Group for
|
718
|
+
# this flag. You may provide a group name, a FlagGroup object, or
|
719
|
+
# `nil` which denotes the default group.
|
720
|
+
# @param desc [String,Array<String>,Toys::WrappableString] Short
|
721
|
+
# description for the flag. See {Toys::ToolDefinition#desc} for a
|
722
|
+
# description of allowed formats. Defaults to the empty string.
|
723
|
+
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
|
724
|
+
# Long description for the flag. See {Toys::ToolDefinition#long_desc}
|
725
|
+
# for a description of allowed formats. Defaults to the empty array.
|
726
|
+
# @param display_name [String] A display name for this flag, used in help
|
727
|
+
# text and error messages.
|
728
|
+
# @return [self]
|
729
|
+
#
|
730
|
+
def add_flag(key, flags = [],
|
731
|
+
accept: nil, default: nil, handler: nil, complete_flags: nil,
|
732
|
+
complete_values: nil, report_collisions: true, group: nil, desc: nil,
|
733
|
+
long_desc: nil, display_name: nil)
|
734
|
+
# Source available in the toys-core gem
|
735
|
+
end
|
736
|
+
|
737
|
+
##
|
738
|
+
# Mark one or more flags as disabled, preventing their use by any
|
739
|
+
# subsequent flag definition. This may be used to prevent middleware from
|
740
|
+
# defining a particular flag.
|
741
|
+
#
|
742
|
+
# @param flags [String...] The flags to disable
|
743
|
+
# @return [self]
|
744
|
+
#
|
745
|
+
def disable_flag(*flags)
|
746
|
+
# Source available in the toys-core gem
|
747
|
+
end
|
748
|
+
|
749
|
+
##
|
750
|
+
# Add a required positional argument to the current tool. You must specify
|
751
|
+
# a key which the script may use to obtain the argument value from the
|
752
|
+
# context.
|
753
|
+
#
|
754
|
+
# @param key [String,Symbol] The key to use to retrieve the value from
|
755
|
+
# the execution context.
|
756
|
+
# @param accept [Object] An acceptor that validates and/or converts the
|
757
|
+
# value. You may provide either the name of an acceptor you have
|
758
|
+
# defined, or one of the default acceptors provided by OptionParser.
|
759
|
+
# Optional. If not specified, accepts any value as a string.
|
760
|
+
# @param complete [Object] A specifier for shell tab completion. See
|
761
|
+
# {Toys::Completion.create} for recognized formats.
|
762
|
+
# @param display_name [String] A name to use for display (in help text and
|
763
|
+
# error reports). Defaults to the key in upper case.
|
764
|
+
# @param desc [String,Array<String>,Toys::WrappableString] Short
|
765
|
+
# description for the arg. See {Toys::ToolDefinition#desc} for a
|
766
|
+
# description of allowed formats. Defaults to the empty string.
|
767
|
+
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
|
768
|
+
# Long description for the arg. See {Toys::ToolDefinition#long_desc}
|
769
|
+
# for a description of allowed formats. Defaults to the empty array.
|
770
|
+
# @return [self]
|
771
|
+
#
|
772
|
+
def add_required_arg(key, accept: nil, complete: nil, display_name: nil,
|
773
|
+
desc: nil, long_desc: nil)
|
774
|
+
# Source available in the toys-core gem
|
775
|
+
end
|
776
|
+
|
777
|
+
##
|
778
|
+
# Add an optional positional argument to the current tool. You must specify
|
779
|
+
# a key which the script may use to obtain the argument value from the
|
780
|
+
# context. If an optional argument is not given on the command line, the
|
781
|
+
# value is set to the given default.
|
782
|
+
#
|
783
|
+
# @param key [String,Symbol] The key to use to retrieve the value from
|
784
|
+
# the execution context.
|
785
|
+
# @param default [Object] The default value. This is the value that will
|
786
|
+
# be set in the context if this argument is not provided on the command
|
787
|
+
# line. Defaults to `nil`.
|
788
|
+
# @param accept [Object] An acceptor that validates and/or converts the
|
789
|
+
# value. You may provide either the name of an acceptor you have
|
790
|
+
# defined, or one of the default acceptors provided by OptionParser.
|
791
|
+
# Optional. If not specified, accepts any value as a string.
|
792
|
+
# @param complete [Object] A specifier for shell tab completion. See
|
793
|
+
# {Toys::Completion.create} for recognized formats.
|
794
|
+
# @param display_name [String] A name to use for display (in help text and
|
795
|
+
# error reports). Defaults to the key in upper case.
|
796
|
+
# @param desc [String,Array<String>,Toys::WrappableString] Short
|
797
|
+
# description for the arg. See {Toys::ToolDefinition#desc} for a
|
798
|
+
# description of allowed formats. Defaults to the empty string.
|
799
|
+
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
|
800
|
+
# Long description for the arg. See {Toys::ToolDefinition#long_desc}
|
801
|
+
# for a description of allowed formats. Defaults to the empty array.
|
802
|
+
# @return [self]
|
803
|
+
#
|
804
|
+
def add_optional_arg(key, default: nil, accept: nil, complete: nil,
|
805
|
+
display_name: nil, desc: nil, long_desc: nil)
|
806
|
+
# Source available in the toys-core gem
|
807
|
+
end
|
808
|
+
|
809
|
+
##
|
810
|
+
# Specify what should be done with unmatched positional arguments. You must
|
811
|
+
# specify a key which the script may use to obtain the remaining args
|
812
|
+
# from the context.
|
813
|
+
#
|
814
|
+
# @param key [String,Symbol] The key to use to retrieve the value from
|
815
|
+
# the execution context.
|
816
|
+
# @param default [Object] The default value. This is the value that will
|
817
|
+
# be set in the context if no unmatched arguments are provided on the
|
818
|
+
# command line. Defaults to the empty array `[]`.
|
819
|
+
# @param accept [Object] An acceptor that validates and/or converts the
|
820
|
+
# value. You may provide either the name of an acceptor you have
|
821
|
+
# defined, or one of the default acceptors provided by OptionParser.
|
822
|
+
# Optional. If not specified, accepts any value as a string.
|
823
|
+
# @param complete [Object] A specifier for shell tab completion. See
|
824
|
+
# {Toys::Completion.create} for recognized formats.
|
825
|
+
# @param display_name [String] A name to use for display (in help text and
|
826
|
+
# error reports). Defaults to the key in upper case.
|
827
|
+
# @param desc [String,Array<String>,Toys::WrappableString] Short
|
828
|
+
# description for the arg. See {Toys::ToolDefinition#desc} for a
|
829
|
+
# description of allowed formats. Defaults to the empty string.
|
830
|
+
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
|
831
|
+
# Long description for the arg. See {Toys::ToolDefinition#long_desc}
|
832
|
+
# for a description of allowed formats. Defaults to the empty array.
|
833
|
+
# @return [self]
|
834
|
+
#
|
835
|
+
def set_remaining_args(key, default: [], accept: nil, complete: nil,
|
836
|
+
display_name: nil, desc: nil, long_desc: nil)
|
837
|
+
# Source available in the toys-core gem
|
838
|
+
end
|
839
|
+
|
840
|
+
##
|
841
|
+
# Set the run handler block
|
842
|
+
#
|
843
|
+
# @param proc [Proc] The runnable block
|
844
|
+
#
|
845
|
+
def run_handler=(proc)
|
846
|
+
# Source available in the toys-core gem
|
847
|
+
end
|
848
|
+
|
849
|
+
##
|
850
|
+
# Set the interrupt handler.
|
851
|
+
#
|
852
|
+
# @param handler [Proc,Symbol] The interrupt handler
|
853
|
+
#
|
854
|
+
def interrupt_handler=(handler)
|
855
|
+
# Source available in the toys-core gem
|
856
|
+
end
|
857
|
+
|
858
|
+
##
|
859
|
+
# Set the usage error handler.
|
860
|
+
#
|
861
|
+
# @param handler [Proc,Symbol] The usage error handler
|
862
|
+
#
|
863
|
+
def usage_error_handler=(handler)
|
864
|
+
# Source available in the toys-core gem
|
865
|
+
end
|
866
|
+
|
867
|
+
##
|
868
|
+
# Add an initializer.
|
869
|
+
#
|
870
|
+
# @param proc [Proc] The initializer block
|
871
|
+
# @param args [Object...] Arguments to pass to the initializer
|
872
|
+
# @param kwargs [keywords] Keyword arguments to pass to the initializer
|
873
|
+
# @return [self]
|
874
|
+
#
|
875
|
+
def add_initializer(proc, *args, **kwargs)
|
876
|
+
# Source available in the toys-core gem
|
877
|
+
end
|
878
|
+
|
879
|
+
##
|
880
|
+
# Set the custom context directory.
|
881
|
+
#
|
882
|
+
# See {#custom_context_directory} for details.
|
883
|
+
#
|
884
|
+
# @param dir [String]
|
885
|
+
#
|
886
|
+
def custom_context_directory=(dir)
|
887
|
+
# Source available in the toys-core gem
|
888
|
+
end
|
889
|
+
|
890
|
+
##
|
891
|
+
# Set the completion strategy for this ToolDefinition.
|
892
|
+
#
|
893
|
+
# See {#completion} for details.
|
894
|
+
#
|
895
|
+
# @param spec [Object]
|
896
|
+
#
|
897
|
+
def completion=(spec)
|
898
|
+
# Source available in the toys-core gem
|
899
|
+
end
|
900
|
+
|
901
|
+
##
|
902
|
+
# Return the effective context directory.
|
903
|
+
# If there is a custom context directory, uses that. Otherwise, looks for
|
904
|
+
# a custom context directory up the tool ancestor chain. If none is
|
905
|
+
# found, uses the default context directory from the source info. It is
|
906
|
+
# possible for there to be no context directory at all, in which case,
|
907
|
+
# returns nil.
|
908
|
+
#
|
909
|
+
# @return [String] The effective context directory path.
|
910
|
+
# @return [nil] if there is no effective context directory.
|
911
|
+
#
|
912
|
+
def context_directory
|
913
|
+
# Source available in the toys-core gem
|
914
|
+
end
|
915
|
+
|
916
|
+
##
|
917
|
+
# Causes this tool to delegate to another tool.
|
918
|
+
#
|
919
|
+
# @param target [Array<String>] The full path to the delegate tool.
|
920
|
+
# @return [self]
|
921
|
+
#
|
922
|
+
def delegate_to(target)
|
923
|
+
# Source available in the toys-core gem
|
924
|
+
end
|
925
|
+
end
|
926
|
+
end
|