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.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +2 -0
  3. data/CHANGELOG.md +35 -0
  4. data/LICENSE.md +1 -1
  5. data/README.md +7 -4
  6. data/builtins/system/git-cache.rb +238 -0
  7. data/builtins/system/test.rb +37 -2
  8. data/core-docs/toys/acceptor.rb +432 -0
  9. data/core-docs/toys/arg_parser.rb +397 -0
  10. data/core-docs/toys/cli.rb +493 -0
  11. data/core-docs/toys/compat.rb +2 -0
  12. data/core-docs/toys/completion.rb +329 -0
  13. data/core-docs/toys/context.rb +321 -0
  14. data/core-docs/toys/core.rb +14 -0
  15. data/core-docs/toys/dsl/base.rb +56 -0
  16. data/core-docs/toys/dsl/flag.rb +261 -0
  17. data/core-docs/toys/dsl/flag_group.rb +259 -0
  18. data/core-docs/toys/dsl/internal.rb +4 -0
  19. data/core-docs/toys/dsl/positional_arg.rb +139 -0
  20. data/core-docs/toys/dsl/tool.rb +1530 -0
  21. data/core-docs/toys/errors.rb +93 -0
  22. data/core-docs/toys/flag.rb +549 -0
  23. data/core-docs/toys/flag_group.rb +186 -0
  24. data/core-docs/toys/input_file.rb +8 -0
  25. data/core-docs/toys/loader.rb +222 -0
  26. data/core-docs/toys/middleware.rb +295 -0
  27. data/core-docs/toys/mixin.rb +142 -0
  28. data/core-docs/toys/module_lookup.rb +75 -0
  29. data/core-docs/toys/positional_arg.rb +145 -0
  30. data/core-docs/toys/settings.rb +507 -0
  31. data/core-docs/toys/source_info.rb +127 -0
  32. data/core-docs/toys/standard_middleware/add_verbosity_flags.rb +49 -0
  33. data/core-docs/toys/standard_middleware/apply_config.rb +24 -0
  34. data/core-docs/toys/standard_middleware/handle_usage_errors.rb +33 -0
  35. data/core-docs/toys/standard_middleware/set_default_descriptions.rb +222 -0
  36. data/core-docs/toys/standard_middleware/show_help.rb +190 -0
  37. data/core-docs/toys/standard_middleware/show_root_version.rb +45 -0
  38. data/core-docs/toys/standard_mixins/bundler.rb +83 -0
  39. data/core-docs/toys/standard_mixins/exec.rb +645 -0
  40. data/core-docs/toys/standard_mixins/fileutils.rb +18 -0
  41. data/core-docs/toys/standard_mixins/gems.rb +48 -0
  42. data/core-docs/toys/standard_mixins/git_cache.rb +41 -0
  43. data/core-docs/toys/standard_mixins/highline.rb +133 -0
  44. data/core-docs/toys/standard_mixins/terminal.rb +135 -0
  45. data/core-docs/toys/standard_mixins/xdg.rb +49 -0
  46. data/core-docs/toys/template.rb +112 -0
  47. data/core-docs/toys/tool_definition.rb +926 -0
  48. data/core-docs/toys/utils/completion_engine.rb +49 -0
  49. data/core-docs/toys/utils/exec.rb +721 -0
  50. data/core-docs/toys/utils/gems.rb +185 -0
  51. data/core-docs/toys/utils/git_cache.rb +353 -0
  52. data/core-docs/toys/utils/help_text.rb +134 -0
  53. data/core-docs/toys/utils/terminal.rb +310 -0
  54. data/core-docs/toys/utils/xdg.rb +253 -0
  55. data/core-docs/toys/wrappable_string.rb +120 -0
  56. data/core-docs/toys-core.rb +63 -0
  57. data/docs/guide.md +497 -156
  58. data/lib/toys/standard_cli.rb +50 -36
  59. data/lib/toys/templates/clean.rb +18 -0
  60. data/lib/toys/templates/gem_build.rb +24 -0
  61. data/lib/toys/templates/minitest.rb +21 -0
  62. data/lib/toys/templates/rake.rb +23 -3
  63. data/lib/toys/templates/rdoc.rb +29 -0
  64. data/lib/toys/templates/rspec.rb +32 -4
  65. data/lib/toys/templates/rubocop.rb +14 -1
  66. data/lib/toys/templates/yardoc.rb +55 -0
  67. data/lib/toys/testing.rb +186 -109
  68. data/lib/toys/version.rb +1 -1
  69. data/lib/toys.rb +4 -2
  70. 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