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,397 @@
|
|
1
|
+
module Toys
|
2
|
+
##
|
3
|
+
# **_Defined in the toys-core gem_**
|
4
|
+
#
|
5
|
+
# An internal class that parses command line arguments for a tool.
|
6
|
+
#
|
7
|
+
# Generally, you should not need to use this class directly. It is called
|
8
|
+
# from {Toys::CLI}.
|
9
|
+
#
|
10
|
+
class ArgParser
|
11
|
+
##
|
12
|
+
# **_Defined in the toys-core gem_**
|
13
|
+
#
|
14
|
+
# Base representation of a usage error reported by the ArgParser.
|
15
|
+
#
|
16
|
+
# This functions similarly to an exception, but is not raised. Rather, it
|
17
|
+
# is returned in the {Toys::ArgParser#errors} array.
|
18
|
+
#
|
19
|
+
class UsageError
|
20
|
+
##
|
21
|
+
# Create a UsageError given a message and common data
|
22
|
+
#
|
23
|
+
# @param message [String] The basic error message.
|
24
|
+
# @param name [String,nil] The name of the element (normally flag or
|
25
|
+
# positional argument) that reported the error, or nil if there is
|
26
|
+
# no definite element.
|
27
|
+
# @param value [String,nil] The value that was rejected, or nil if not
|
28
|
+
# applicable.
|
29
|
+
# @param suggestions [Array<String>,nil] An array of suggestions from
|
30
|
+
# DidYouMean, or nil if not applicable.
|
31
|
+
#
|
32
|
+
def initialize(message, name: nil, value: nil, suggestions: nil)
|
33
|
+
# Source available in the toys-core gem
|
34
|
+
end
|
35
|
+
|
36
|
+
##
|
37
|
+
# The basic error message. Does not include suggestions, if any.
|
38
|
+
#
|
39
|
+
# @return [String]
|
40
|
+
#
|
41
|
+
attr_reader :message
|
42
|
+
|
43
|
+
##
|
44
|
+
# The name of the element (normally a flag or positional argument) that
|
45
|
+
# reported the error.
|
46
|
+
#
|
47
|
+
# @return [String] The element name.
|
48
|
+
# @return [nil] if there is no definite element source.
|
49
|
+
#
|
50
|
+
attr_reader :name
|
51
|
+
|
52
|
+
##
|
53
|
+
# The value that was rejected.
|
54
|
+
#
|
55
|
+
# @return [String] the value string
|
56
|
+
# @return [nil] if a value is not applicable to this error.
|
57
|
+
#
|
58
|
+
attr_reader :value
|
59
|
+
|
60
|
+
##
|
61
|
+
# An array of suggestions from DidYouMean.
|
62
|
+
#
|
63
|
+
# @return [Array<String>] array of suggestions.
|
64
|
+
# @return [nil] if suggestions are not applicable to this error.
|
65
|
+
#
|
66
|
+
attr_reader :suggestions
|
67
|
+
|
68
|
+
##
|
69
|
+
# A fully formatted error message including suggestions.
|
70
|
+
#
|
71
|
+
# @return [String]
|
72
|
+
#
|
73
|
+
def full_message
|
74
|
+
# Source available in the toys-core gem
|
75
|
+
end
|
76
|
+
alias to_s full_message
|
77
|
+
end
|
78
|
+
|
79
|
+
##
|
80
|
+
# **_Defined in the toys-core gem_**
|
81
|
+
#
|
82
|
+
# A UsageError indicating a value was provided for a flag that does not
|
83
|
+
# take a value.
|
84
|
+
#
|
85
|
+
class FlagValueNotAllowedError < UsageError
|
86
|
+
##
|
87
|
+
# Create a FlagValueNotAllowedError.
|
88
|
+
#
|
89
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
90
|
+
# which case an appropriate default is supplied.
|
91
|
+
# @param name [String] The name of the flag. Normally required.
|
92
|
+
#
|
93
|
+
def initialize(message = nil, name: nil)
|
94
|
+
# Source available in the toys-core gem
|
95
|
+
end
|
96
|
+
end
|
97
|
+
|
98
|
+
##
|
99
|
+
# **_Defined in the toys-core gem_**
|
100
|
+
#
|
101
|
+
# A UsageError indicating a value was not provided for a flag that requires
|
102
|
+
# a value.
|
103
|
+
#
|
104
|
+
class FlagValueMissingError < UsageError
|
105
|
+
##
|
106
|
+
# Create a FlagValueMissingError.
|
107
|
+
#
|
108
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
109
|
+
# which case an appropriate default is supplied.
|
110
|
+
# @param name [String] The name of the flag. Normally required.
|
111
|
+
#
|
112
|
+
def initialize(message = nil, name: nil)
|
113
|
+
# Source available in the toys-core gem
|
114
|
+
end
|
115
|
+
end
|
116
|
+
|
117
|
+
##
|
118
|
+
# **_Defined in the toys-core gem_**
|
119
|
+
#
|
120
|
+
# A UsageError indicating a flag name was not recognized.
|
121
|
+
#
|
122
|
+
class FlagUnrecognizedError < UsageError
|
123
|
+
##
|
124
|
+
# Create a FlagUnrecognizedError.
|
125
|
+
#
|
126
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
127
|
+
# which case an appropriate default is supplied.
|
128
|
+
# @param value [String] The requested flag name. Normally required.
|
129
|
+
# @param suggestions [Array<String>] An array of suggestions to present
|
130
|
+
# to the user. Optional.
|
131
|
+
#
|
132
|
+
def initialize(message = nil, value: nil, suggestions: nil)
|
133
|
+
# Source available in the toys-core gem
|
134
|
+
end
|
135
|
+
end
|
136
|
+
|
137
|
+
##
|
138
|
+
# **_Defined in the toys-core gem_**
|
139
|
+
#
|
140
|
+
# A UsageError indicating a flag name prefix was given that matched
|
141
|
+
# multiple flags.
|
142
|
+
#
|
143
|
+
class FlagAmbiguousError < UsageError
|
144
|
+
##
|
145
|
+
# Create a FlagAmbiguousError.
|
146
|
+
#
|
147
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
148
|
+
# which case an appropriate default is supplied.
|
149
|
+
# @param value [String] The requested flag name. Normally required.
|
150
|
+
# @param suggestions [Array<String>] An array of suggestions to present
|
151
|
+
# to the user. Optional.
|
152
|
+
#
|
153
|
+
def initialize(message = nil, value: nil, suggestions: nil)
|
154
|
+
# Source available in the toys-core gem
|
155
|
+
end
|
156
|
+
end
|
157
|
+
|
158
|
+
##
|
159
|
+
# **_Defined in the toys-core gem_**
|
160
|
+
#
|
161
|
+
# A UsageError indicating a flag did not accept the value given it.
|
162
|
+
#
|
163
|
+
class FlagValueUnacceptableError < UsageError
|
164
|
+
##
|
165
|
+
# Create a FlagValueUnacceptableError.
|
166
|
+
#
|
167
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
168
|
+
# which case an appropriate default is supplied.
|
169
|
+
# @param name [String] The name of the flag. Normally required.
|
170
|
+
# @param value [String] The value given. Normally required.
|
171
|
+
# @param suggestions [Array<String>] An array of suggestions to present
|
172
|
+
# to the user. Optional.
|
173
|
+
#
|
174
|
+
def initialize(message = nil, name: nil, value: nil, suggestions: nil)
|
175
|
+
# Source available in the toys-core gem
|
176
|
+
end
|
177
|
+
end
|
178
|
+
|
179
|
+
##
|
180
|
+
# **_Defined in the toys-core gem_**
|
181
|
+
#
|
182
|
+
# A UsageError indicating a positional argument did not accept the value
|
183
|
+
# given it.
|
184
|
+
#
|
185
|
+
class ArgValueUnacceptableError < UsageError
|
186
|
+
##
|
187
|
+
# Create an ArgValueUnacceptableError.
|
188
|
+
#
|
189
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
190
|
+
# which case an appropriate default is supplied.
|
191
|
+
# @param name [String] The name of the argument. Normally required.
|
192
|
+
# @param value [String] The value given. Normally required.
|
193
|
+
# @param suggestions [Array<String>] An array of suggestions to present
|
194
|
+
# to the user. Optional.
|
195
|
+
#
|
196
|
+
def initialize(message = nil, name: nil, value: nil, suggestions: nil)
|
197
|
+
# Source available in the toys-core gem
|
198
|
+
end
|
199
|
+
end
|
200
|
+
|
201
|
+
##
|
202
|
+
# **_Defined in the toys-core gem_**
|
203
|
+
#
|
204
|
+
# A UsageError indicating a required positional argument was not fulfilled.
|
205
|
+
#
|
206
|
+
class ArgMissingError < UsageError
|
207
|
+
##
|
208
|
+
# Create an ArgMissingError.
|
209
|
+
#
|
210
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
211
|
+
# which case an appropriate default is supplied.
|
212
|
+
# @param name [String] The name of the argument. Normally required.
|
213
|
+
#
|
214
|
+
def initialize(message = nil, name: nil)
|
215
|
+
# Source available in the toys-core gem
|
216
|
+
end
|
217
|
+
end
|
218
|
+
|
219
|
+
##
|
220
|
+
# **_Defined in the toys-core gem_**
|
221
|
+
#
|
222
|
+
# A UsageError indicating extra arguments were supplied.
|
223
|
+
#
|
224
|
+
class ExtraArgumentsError < UsageError
|
225
|
+
##
|
226
|
+
# Create an ExtraArgumentsError.
|
227
|
+
#
|
228
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
229
|
+
# which case an appropriate default is supplied.
|
230
|
+
# @param value [String] The first extra argument. Normally required.
|
231
|
+
# @param values [Array<String>] All extra arguments. Normally required.
|
232
|
+
#
|
233
|
+
def initialize(message = nil, value: nil, values: nil)
|
234
|
+
# Source available in the toys-core gem
|
235
|
+
end
|
236
|
+
end
|
237
|
+
|
238
|
+
##
|
239
|
+
# **_Defined in the toys-core gem_**
|
240
|
+
#
|
241
|
+
# A UsageError indicating the given subtool name does not exist.
|
242
|
+
#
|
243
|
+
class ToolUnrecognizedError < UsageError
|
244
|
+
##
|
245
|
+
# Create a ToolUnrecognizedError.
|
246
|
+
#
|
247
|
+
# @param message [String,nil] A custom message. Normally omitted, in
|
248
|
+
# which case an appropriate default is supplied.
|
249
|
+
# @param value [String] The requested subtool. Normally required.
|
250
|
+
# @param values [Array<String>] The full path of the requested tool.
|
251
|
+
# Normally required.
|
252
|
+
# @param suggestions [Array<String>] An array of suggestions to present
|
253
|
+
# to the user. Optional.
|
254
|
+
#
|
255
|
+
def initialize(message = nil, value: nil, values: nil, suggestions: nil)
|
256
|
+
# Source available in the toys-core gem
|
257
|
+
end
|
258
|
+
end
|
259
|
+
|
260
|
+
##
|
261
|
+
# **_Defined in the toys-core gem_**
|
262
|
+
#
|
263
|
+
# A UsageError indicating a flag group constraint was not fulfilled.
|
264
|
+
#
|
265
|
+
class FlagGroupConstraintError < UsageError
|
266
|
+
##
|
267
|
+
# Create a FlagGroupConstraintError.
|
268
|
+
#
|
269
|
+
# @param message [String] The message. Required.
|
270
|
+
#
|
271
|
+
def initialize(message)
|
272
|
+
# Source available in the toys-core gem
|
273
|
+
end
|
274
|
+
end
|
275
|
+
|
276
|
+
##
|
277
|
+
# Create an argument parser for a particular tool.
|
278
|
+
#
|
279
|
+
# @param cli [Toys::CLI] The CLI in effect.
|
280
|
+
# @param tool [Toys::ToolDefinition] The tool defining the argument format.
|
281
|
+
# @param default_data [Hash] Additional initial data (such as verbosity).
|
282
|
+
# @param require_exact_flag_match [Boolean] Whether to require flag matches
|
283
|
+
# be exact (not partial). Default is false.
|
284
|
+
#
|
285
|
+
def initialize(cli, tool, default_data: {}, require_exact_flag_match: false)
|
286
|
+
# Source available in the toys-core gem
|
287
|
+
end
|
288
|
+
|
289
|
+
##
|
290
|
+
# The tool definition governing this parser.
|
291
|
+
# @return [Toys::ToolDefinition]
|
292
|
+
#
|
293
|
+
attr_reader :tool
|
294
|
+
|
295
|
+
##
|
296
|
+
# All command line arguments that have been parsed.
|
297
|
+
# @return [Array<String>]
|
298
|
+
#
|
299
|
+
attr_reader :parsed_args
|
300
|
+
|
301
|
+
##
|
302
|
+
# Extra positional args that were not matched.
|
303
|
+
# @return [Array<String>]
|
304
|
+
#
|
305
|
+
attr_reader :unmatched_positional
|
306
|
+
|
307
|
+
##
|
308
|
+
# Flags that were not matched.
|
309
|
+
# @return [Array<String>]
|
310
|
+
#
|
311
|
+
attr_reader :unmatched_flags
|
312
|
+
|
313
|
+
##
|
314
|
+
# All args that were not matched.
|
315
|
+
# @return [Array<String>]
|
316
|
+
#
|
317
|
+
attr_reader :unmatched_args
|
318
|
+
|
319
|
+
##
|
320
|
+
# The collected tool data from parsed arguments.
|
321
|
+
# @return [Hash]
|
322
|
+
#
|
323
|
+
attr_reader :data
|
324
|
+
|
325
|
+
##
|
326
|
+
# An array of parse error messages.
|
327
|
+
# @return [Array<Toys::ArgParser::UsageError>]
|
328
|
+
#
|
329
|
+
attr_reader :errors
|
330
|
+
|
331
|
+
##
|
332
|
+
# The current flag definition whose value is still pending
|
333
|
+
#
|
334
|
+
# @return [Toys::Flag] The pending flag definition
|
335
|
+
# @return [nil] if there is no pending flag
|
336
|
+
#
|
337
|
+
attr_reader :active_flag_def
|
338
|
+
|
339
|
+
##
|
340
|
+
# Whether flags are currently allowed. Returns false after `--` is received.
|
341
|
+
# @return [Boolean]
|
342
|
+
#
|
343
|
+
def flags_allowed?
|
344
|
+
# Source available in the toys-core gem
|
345
|
+
end
|
346
|
+
|
347
|
+
##
|
348
|
+
# Determine if this parser is finished
|
349
|
+
# @return [Boolean]
|
350
|
+
#
|
351
|
+
def finished?
|
352
|
+
# Source available in the toys-core gem
|
353
|
+
end
|
354
|
+
|
355
|
+
##
|
356
|
+
# The argument definition that will be applied to the next argument.
|
357
|
+
#
|
358
|
+
# @return [Toys::PositionalArg] The next argument definition.
|
359
|
+
# @return [nil] if all arguments have been filled.
|
360
|
+
#
|
361
|
+
def next_arg_def
|
362
|
+
# Source available in the toys-core gem
|
363
|
+
end
|
364
|
+
|
365
|
+
##
|
366
|
+
# Incrementally parse a single string or an array of strings
|
367
|
+
#
|
368
|
+
# @param args [String,Array<String>]
|
369
|
+
# @return [self]
|
370
|
+
#
|
371
|
+
def parse(args)
|
372
|
+
# Source available in the toys-core gem
|
373
|
+
end
|
374
|
+
|
375
|
+
##
|
376
|
+
# Complete parsing. This should be called after all arguments have been
|
377
|
+
# processed. It does a final check for any errors, including:
|
378
|
+
#
|
379
|
+
# * The arguments ended with a flag that was expecting a value but wasn't
|
380
|
+
# provided.
|
381
|
+
# * One or more required arguments were never given a value.
|
382
|
+
# * One or more extra arguments were provided.
|
383
|
+
# * Restrictions defined in one or more flag groups were not fulfilled.
|
384
|
+
#
|
385
|
+
# Any errors are added to the errors array. It also fills in final values
|
386
|
+
# for `Context::Key::USAGE_ERRORS` and `Context::Key::ARGS`.
|
387
|
+
#
|
388
|
+
# After this method is called, this object is locked down, and no
|
389
|
+
# additional arguments may be parsed.
|
390
|
+
#
|
391
|
+
# @return [self]
|
392
|
+
#
|
393
|
+
def finish
|
394
|
+
# Source available in the toys-core gem
|
395
|
+
end
|
396
|
+
end
|
397
|
+
end
|