toys 0.12.1 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +2 -0
  3. data/CHANGELOG.md +44 -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,645 @@
1
+ module Toys
2
+ module StandardMixins
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # A set of helper methods for invoking subcommands. Provides shortcuts for
7
+ # common cases such as invoking Ruby in a subprocess or capturing output
8
+ # in a string. Also provides an interface for controlling a spawned
9
+ # process's streams.
10
+ #
11
+ # You may make these methods available to your tool by including the
12
+ # following directive in your tool configuration:
13
+ #
14
+ # include :exec
15
+ #
16
+ # This is a frontend for {Toys::Utils::Exec}. More information is
17
+ # available in that class's documentation.
18
+ #
19
+ # ### Controlling processes
20
+ #
21
+ # A process can be started in the *foreground* or the *background*. If you
22
+ # start a foreground process, it will "take over" your standard input and
23
+ # output streams by default, and it will keep control until it completes.
24
+ # If you start a background process, its streams will be redirected to null
25
+ # by default, and control will be returned to you immediately.
26
+ #
27
+ # When a process is running, you can control it using a
28
+ # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
29
+ # the process's input and output streams, send it signals, or wait for it
30
+ # to complete.
31
+ #
32
+ # When running a process in the foreground, the controller will be yielded
33
+ # to an optional block. For example, the following code starts a process in
34
+ # the foreground and passes its output stream to a controller.
35
+ #
36
+ # exec(["git", "init"], out: :controller) do |controller|
37
+ # loop do
38
+ # line = controller.out.gets
39
+ # break if line.nil?
40
+ # puts "Got line: #{line}"
41
+ # end
42
+ # end
43
+ #
44
+ # When running a process in the background, the controller is returned from
45
+ # the method that starts the process:
46
+ #
47
+ # controller = exec_service.exec(["git", "init"], background: true)
48
+ #
49
+ # ### Stream handling
50
+ #
51
+ # By default, subprocess streams are connected to the corresponding streams
52
+ # in the parent process. You can change this behavior, redirecting streams
53
+ # or providing ways to control them, using the `:in`, `:out`, and `:err`
54
+ # options.
55
+ #
56
+ # Three general strategies are available for custom stream handling. First,
57
+ # you may redirect to other streams such as files, IO objects, or Ruby
58
+ # strings. Some of these options map directly to options provided by the
59
+ # `Process#spawn` method. Second, you may use a controller to manipulate
60
+ # the streams programmatically. Third, you may capture output stream data
61
+ # and make it available in the result.
62
+ #
63
+ # Following is a full list of the stream handling options, along with how
64
+ # to specify them using the `:in`, `:out`, and `:err` options.
65
+ #
66
+ # * **Inherit parent stream:** You may inherit the corresponding stream
67
+ # in the parent process by passing `:inherit` as the option value. This
68
+ # is the default if the subprocess is *not* run in the background.
69
+ # * **Redirect to null:** You may redirect to a null stream by passing
70
+ # `:null` as the option value. This connects to a stream that is not
71
+ # closed but contains no data, i.e. `/dev/null` on unix systems. This
72
+ # is the default if the subprocess is run in the background.
73
+ # * **Close the stream:** You may close the stream by passing `:close` as
74
+ # the option value. This is the same as passing `:close` to
75
+ # `Process#spawn`.
76
+ # * **Redirect to a file:** You may redirect to a file. This reads from
77
+ # an existing file when connected to `:in`, and creates or appends to a
78
+ # file when connected to `:out` or `:err`. To specify a file, use the
79
+ # setting `[:file, "/path/to/file"]`. You may also, when writing a
80
+ # file, append an optional mode and permission code to the array. For
81
+ # example, `[:file, "/path/to/file", "a", 0644]`.
82
+ # * **Redirect to an IO object:** You may redirect to an IO object in the
83
+ # parent process, by passing the IO object as the option value. You may
84
+ # use any IO object. For example, you could connect the child's output
85
+ # to the parent's error using `out: $stderr`, or you could connect to
86
+ # an existing File stream. Unlike `Process#spawn`, this works for IO
87
+ # objects that do not have a corresponding file descriptor (such as
88
+ # StringIO objects). In such a case, a thread will be spawned to pipe
89
+ # the IO data through to the child process.
90
+ # * **Combine with another child stream:** You may redirect one child
91
+ # output stream to another, to combine them. To merge the child's error
92
+ # stream into its output stream, use `err: [:child, :out]`.
93
+ # * **Read from a string:** You may pass a string to the input stream by
94
+ # setting `[:string, "the string"]`. This works only for `:in`.
95
+ # * **Capture output stream:** You may capture a stream and make it
96
+ # available on the {Toys::Utils::Exec::Result} object, using the
97
+ # setting `:capture`. This works only for the `:out` and `:err`
98
+ # streams.
99
+ # * **Use the controller:** You may hook a stream to the controller using
100
+ # the setting `:controller`. You can then manipulate the stream via the
101
+ # controller. If you pass a block to {Toys::StandardMixins::Exec#exec},
102
+ # it yields the {Toys::Utils::Exec::Controller}, giving you access to
103
+ # streams.
104
+ #
105
+ # ### Result handling
106
+ #
107
+ # A subprocess result is represented by a {Toys::Utils::Exec::Result}
108
+ # object, which includes the exit code, the content of any captured output
109
+ # streams, and any exeption raised when attempting to run the process.
110
+ # When you run a process in the foreground, the method will return a result
111
+ # object. When you run a process in the background, you can obtain the
112
+ # result from the controller once the process completes.
113
+ #
114
+ # The following example demonstrates running a process in the foreground
115
+ # and getting the exit code:
116
+ #
117
+ # result = exec(["git", "init"])
118
+ # puts "exit code: #{result.exit_code}"
119
+ #
120
+ # The following example demonstrates starting a process in the background,
121
+ # waiting for it to complete, and getting its exit code:
122
+ #
123
+ # controller = exec(["git", "init"], background: true)
124
+ # result = controller.result(timeout: 1.0)
125
+ # if result
126
+ # puts "exit code: #{result.exit_code}"
127
+ # else
128
+ # puts "timed out"
129
+ # end
130
+ #
131
+ # You can also provide a callback that is executed once a process
132
+ # completes. This callback can be specified as a method name or a `Proc`
133
+ # object, and will be passed the result object. For example:
134
+ #
135
+ # def run
136
+ # exec(["git", "init"], result_callback: :handle_result)
137
+ # end
138
+ # def handle_result(result)
139
+ # puts "exit code: #{result.exit_code}"
140
+ # end
141
+ #
142
+ # Finally, you can force your tool to exit if a subprocess fails, similar
143
+ # to setting the `set -e` option in bash, by setting the
144
+ # `:exit_on_nonzero_status` option. This is often set as a default
145
+ # configuration for all subprocesses run in a tool, by passing it as an
146
+ # argument to the `include` directive:
147
+ #
148
+ # include :exec, exit_on_nonzero_status: true
149
+ #
150
+ # ### Configuration Options
151
+ #
152
+ # A variety of options can be used to control subprocesses. These can be
153
+ # provided to any method that starts a subprocess. You can also set
154
+ # defaults by passing them as keyword arguments when you `include` the
155
+ # mixin.
156
+ #
157
+ # Options that affect the behavior of subprocesses:
158
+ #
159
+ # * `:env` (Hash) Environment variables to pass to the subprocess.
160
+ # Keys represent variable names and should be strings. Values should be
161
+ # either strings or `nil`, which unsets the variable.
162
+ #
163
+ # * `:background` (Boolean) Runs the process in the background if `true`.
164
+ #
165
+ # Options related to handling results
166
+ #
167
+ # * `:result_callback` (Proc,Symbol) A procedure that is called, and
168
+ # passed the result object, when the subprocess exits. You can provide
169
+ # a `Proc` object, or the name of a method as a `Symbol`.
170
+ #
171
+ # * `:exit_on_nonzero_status` (Boolean) If set to true, a nonzero exit
172
+ # code will cause the tool to exit immediately with that same code.
173
+ #
174
+ # * `:e` (Boolean) A short name for `:exit_on_nonzero_status`.
175
+ #
176
+ # Options for connecting input and output streams. See the section above on
177
+ # stream handling for info on the values that can be passed.
178
+ #
179
+ # * `:in` Connects the input stream of the subprocess. See the section on
180
+ # stream handling.
181
+ #
182
+ # * `:out` Connects the standard output stream of the subprocess. See the
183
+ # section on stream handling.
184
+ #
185
+ # * `:err` Connects the standard error stream of the subprocess. See the
186
+ # section on stream handling.
187
+ #
188
+ # Options related to logging and reporting:
189
+ #
190
+ # * `:logger` (Logger) Logger to use for logging the actual command. If
191
+ # not present, the command is not logged.
192
+ #
193
+ # * `:log_level` (Integer,false) Level for logging the actual command.
194
+ # Defaults to Logger::INFO if not present. You may also pass `false` to
195
+ # disable logging of the command.
196
+ #
197
+ # * `:log_cmd` (String) The string logged for the actual command.
198
+ # Defaults to the `inspect` representation of the command.
199
+ #
200
+ # * `:name` (Object) An optional object that can be used to identify this
201
+ # subprocess. It is available in the controller and result objects.
202
+ #
203
+ # In addition, the following options recognized by
204
+ # [`Process#spawn`](https://ruby-doc.org/core/Process.html#method-c-spawn)
205
+ # are supported.
206
+ #
207
+ # * `:chdir` (String) Set the working directory for the command.
208
+ #
209
+ # * `:close_others` (Boolean) Whether to close non-redirected
210
+ # non-standard file descriptors.
211
+ #
212
+ # * `:new_pgroup` (Boolean) Create new process group (Windows only).
213
+ #
214
+ # * `:pgroup` (Integer,true,nil) The process group setting.
215
+ #
216
+ # * `:umask` (Integer) Umask setting for the new process.
217
+ #
218
+ # * `:unsetenv_others` (Boolean) Clear environment variables except those
219
+ # explicitly set.
220
+ #
221
+ # Any other option key will result in an `ArgumentError`.
222
+ #
223
+ module Exec
224
+ include Mixin
225
+
226
+ ##
227
+ # Context key for the executor object.
228
+ # @return [Object]
229
+ #
230
+ KEY = ::Object.new.freeze
231
+
232
+ ##
233
+ # Set default configuration options.
234
+ #
235
+ # See the {Toys::StandardMixins::Exec} module documentation for a
236
+ # description of the options.
237
+ #
238
+ # @param opts [keywords] The default options.
239
+ # @return [self]
240
+ #
241
+ def configure_exec(**opts)
242
+ # Source available in the toys-core gem
243
+ end
244
+
245
+ ##
246
+ # Execute a command. The command may be given as a single string to pass
247
+ # to a shell, or an array of strings indicating a posix command.
248
+ #
249
+ # If the process is not set to run in the background, and a block is
250
+ # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
251
+ #
252
+ # ### Examples
253
+ #
254
+ # Run a command without a shell, and print the exit code (0 for success):
255
+ #
256
+ # result = exec(["git", "init"])
257
+ # puts "exit code: #{result.exit_code}"
258
+ #
259
+ # Run a shell command:
260
+ #
261
+ # result = exec("cd mydir && git init")
262
+ # puts "exit code: #{result.exit_code}"
263
+ #
264
+ # @param cmd [String,Array<String>] The command to execute.
265
+ # @param opts [keywords] The command options. See the section on
266
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
267
+ # documentation.
268
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
269
+ # the subprocess. See the section on Controlling Processes in the
270
+ # {Toys::StandardMixins::Exec} module documentation.
271
+ #
272
+ # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
273
+ # the process is running in the background.
274
+ # @return [Toys::Utils::Exec::Result] The result, if the process ran in
275
+ # the foreground.
276
+ #
277
+ def exec(cmd, **opts, &block)
278
+ # Source available in the toys-core gem
279
+ end
280
+
281
+ ##
282
+ # Spawn a ruby process and pass the given arguments to it.
283
+ #
284
+ # If the process is not set to run in the background, and a block is
285
+ # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
286
+ #
287
+ # ### Example
288
+ #
289
+ # Execute a small script with warnings
290
+ #
291
+ # exec_ruby(["-w", "-e", "(1..10).each { |i| puts i }"])
292
+ #
293
+ # @param args [String,Array<String>] The arguments to ruby.
294
+ # @param opts [keywords] The command options. See the section on
295
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
296
+ # documentation.
297
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
298
+ # the subprocess. See the section on Controlling Processes in the
299
+ # {Toys::StandardMixins::Exec} module documentation.
300
+ #
301
+ # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
302
+ # the process is running in the background.
303
+ # @return [Toys::Utils::Exec::Result] The result, if the process ran in
304
+ # the foreground.
305
+ #
306
+ def exec_ruby(args, **opts, &block)
307
+ # Source available in the toys-core gem
308
+ end
309
+ alias ruby exec_ruby
310
+
311
+ ##
312
+ # Execute a proc in a forked subprocess.
313
+ #
314
+ # If the process is not set to run in the background, and a block is
315
+ # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
316
+ #
317
+ # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
318
+ # do not support this method because they do not support fork.
319
+ #
320
+ # ### Example
321
+ #
322
+ # Run a proc in a forked process.
323
+ #
324
+ # code = proc do
325
+ # puts "Spawned process ID is #{Process.pid}"
326
+ # end
327
+ # puts "Main process ID is #{Process.pid}"
328
+ # exec_proc(code)
329
+ #
330
+ # @param func [Proc] The proc to call.
331
+ # @param opts [keywords] The command options. See the section on
332
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
333
+ # documentation.
334
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
335
+ # the subprocess. See the section on Controlling Processes in the
336
+ # {Toys::StandardMixins::Exec} module documentation.
337
+ #
338
+ # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
339
+ # the process is running in the background.
340
+ # @return [Toys::Utils::Exec::Result] The result, if the process ran in
341
+ # the foreground.
342
+ #
343
+ def exec_proc(func, **opts, &block)
344
+ # Source available in the toys-core gem
345
+ end
346
+
347
+ ##
348
+ # Execute a tool in the current CLI in a forked process.
349
+ #
350
+ # The command may be given as a single string or an array of strings,
351
+ # representing the tool to run and the arguments to pass.
352
+ #
353
+ # If the process is not set to run in the background, and a block is
354
+ # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
355
+ #
356
+ # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
357
+ # do not support this method because they do not support fork.
358
+ #
359
+ # ### Example
360
+ #
361
+ # Run the "system update" tool and pass it an argument.
362
+ #
363
+ # exec_tool(["system", "update", "--verbose"])
364
+ #
365
+ # @param cmd [String,Array<String>] The tool to execute.
366
+ # @param opts [keywords] The command options. See the section on
367
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
368
+ # documentation.
369
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
370
+ # the subprocess. See the section on Controlling Processes in the
371
+ # {Toys::StandardMixins::Exec} module documentation.
372
+ #
373
+ # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
374
+ # the process is running in the background.
375
+ # @return [Toys::Utils::Exec::Result] The result, if the process ran in
376
+ # the foreground.
377
+ #
378
+ def exec_tool(cmd, **opts, &block)
379
+ # Source available in the toys-core gem
380
+ end
381
+
382
+ ##
383
+ # Execute a tool in a separately spawned process.
384
+ #
385
+ # The command may be given as a single string or an array of strings,
386
+ # representing the tool to run and the arguments to pass.
387
+ #
388
+ # If the process is not set to run in the background, and a block is
389
+ # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
390
+ #
391
+ # An entirely separate spawned process is run for this tool, using the
392
+ # setting of {Toys.executable_path}. Thus, this method can be run only if
393
+ # that setting is present. The normal Toys gem does set it, but if you
394
+ # are writing your own executable using Toys-Core, you will need to set
395
+ # it explicitly for this method to work. Furthermore, Bundler, if
396
+ # present, is reset to its "unbundled" environment. Thus, the tool found,
397
+ # the behavior of the CLI, and the gem environment, might not be the same
398
+ # as those of the calling tool.
399
+ #
400
+ # This method is often used if you are already in a bundle and need to
401
+ # run a tool that uses a different bundle. It may also be necessary on
402
+ # environments without "fork" (such as JRuby or Ruby on Windows).
403
+ #
404
+ # ### Example
405
+ #
406
+ # Run the "system update" tool and pass it an argument.
407
+ #
408
+ # exec_separate_tool(["system", "update", "--verbose"])
409
+ #
410
+ # @param cmd [String,Array<String>] The tool to execute.
411
+ # @param opts [keywords] The command options. See the section on
412
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
413
+ # documentation.
414
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
415
+ # the subprocess. See the section on Controlling Processes in the
416
+ # {Toys::StandardMixins::Exec} module documentation.
417
+ #
418
+ # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
419
+ # the process is running in the background.
420
+ # @return [Toys::Utils::Exec::Result] The result, if the process ran in
421
+ # the foreground.
422
+ #
423
+ def exec_separate_tool(cmd, **opts, &block)
424
+ # Source available in the toys-core gem
425
+ end
426
+
427
+ ##
428
+ # Execute a command. The command may be given as a single string to pass
429
+ # to a shell, or an array of strings indicating a posix command.
430
+ #
431
+ # Captures standard out and returns it as a string.
432
+ # Cannot be run in the background.
433
+ #
434
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
435
+ # yielded to it.
436
+ #
437
+ # ### Example
438
+ #
439
+ # Capture the output of an echo command
440
+ #
441
+ # str = capture(["echo", "hello"])
442
+ # assert_equal("hello\n", str)
443
+ #
444
+ # @param cmd [String,Array<String>] The command to execute.
445
+ # @param opts [keywords] The command options. See the section on
446
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
447
+ # documentation.
448
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
449
+ # the subprocess. See the section on Controlling Processes in the
450
+ # {Toys::StandardMixins::Exec} module documentation.
451
+ #
452
+ # @return [String] What was written to standard out.
453
+ #
454
+ def capture(cmd, **opts, &block)
455
+ # Source available in the toys-core gem
456
+ end
457
+
458
+ ##
459
+ # Spawn a ruby process and pass the given arguments to it.
460
+ #
461
+ # Captures standard out and returns it as a string.
462
+ # Cannot be run in the background.
463
+ #
464
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
465
+ # yielded to it.
466
+ #
467
+ # ### Example
468
+ #
469
+ # Capture the output of a ruby script.
470
+ #
471
+ # str = capture_ruby("-e", "(1..3).each { |i| puts i }")
472
+ # assert_equal "1\n2\n3\n", str
473
+ #
474
+ # @param args [String,Array<String>] The arguments to ruby.
475
+ # @param opts [keywords] The command options. See the section on
476
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
477
+ # documentation.
478
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
479
+ # the subprocess. See the section on Controlling Processes in the
480
+ # {Toys::StandardMixins::Exec} module documentation.
481
+ #
482
+ # @return [String] What was written to standard out.
483
+ #
484
+ def capture_ruby(args, **opts, &block)
485
+ # Source available in the toys-core gem
486
+ end
487
+
488
+ ##
489
+ # Execute a proc in a forked subprocess.
490
+ #
491
+ # Captures standard out and returns it as a string.
492
+ # Cannot be run in the background.
493
+ #
494
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
495
+ # yielded to it.
496
+ #
497
+ # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
498
+ # do not support this method because they do not support fork.
499
+ #
500
+ # ### Example
501
+ #
502
+ # Run a proc in a forked process and capture its output:
503
+ #
504
+ # code = proc do
505
+ # puts Process.pid
506
+ # end
507
+ # forked_pid = capture_proc(code).chomp
508
+ # puts "I forked PID #{forked_pid}"
509
+ #
510
+ # @param func [Proc] The proc to call.
511
+ # @param opts [keywords] The command options. See the section on
512
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
513
+ # documentation.
514
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
515
+ # the subprocess. See the section on Controlling Processes in the
516
+ # {Toys::StandardMixins::Exec} module documentation.
517
+ #
518
+ # @return [String] What was written to standard out.
519
+ #
520
+ def capture_proc(func, **opts, &block)
521
+ # Source available in the toys-core gem
522
+ end
523
+
524
+ ##
525
+ # Execute a tool in the current CLI in a forked process.
526
+ #
527
+ # Captures standard out and returns it as a string.
528
+ # Cannot be run in the background.
529
+ #
530
+ # The command may be given as a single string or an array of strings,
531
+ # representing the tool to run and the arguments to pass.
532
+ #
533
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
534
+ # yielded to it.
535
+ #
536
+ # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
537
+ # do not support this method because they do not support fork.
538
+ #
539
+ # ### Example
540
+ #
541
+ # Run the "system version" tool and capture its output.
542
+ #
543
+ # str = capture_tool(["system", "version"]).chomp
544
+ # puts "Version was #{str}"
545
+ #
546
+ # @param cmd [String,Array<String>] The tool to execute.
547
+ # @param opts [keywords] The command options. See the section on
548
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
549
+ # documentation.
550
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
551
+ # the subprocess. See the section on Controlling Processes in the
552
+ # {Toys::StandardMixins::Exec} module documentation.
553
+ #
554
+ # @return [String] What was written to standard out.
555
+ #
556
+ def capture_tool(cmd, **opts, &block)
557
+ # Source available in the toys-core gem
558
+ end
559
+
560
+ ##
561
+ # Execute a tool in a separately spawned process.
562
+ #
563
+ # Captures standard out and returns it as a string.
564
+ # Cannot be run in the background.
565
+ #
566
+ # The command may be given as a single string or an array of strings,
567
+ # representing the tool to run and the arguments to pass.
568
+ #
569
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
570
+ # yielded to it.
571
+ #
572
+ # An entirely separate spawned process is run for this tool, using the
573
+ # setting of {Toys.executable_path}. Thus, this method can be run only if
574
+ # that setting is present. The normal Toys gem does set it, but if you
575
+ # are writing your own executable using Toys-Core, you will need to set
576
+ # it explicitly for this method to work. Furthermore, Bundler, if
577
+ # present, is reset to its "unbundled" environment. Thus, the tool found,
578
+ # the behavior of the CLI, and the gem environment, might not be the same
579
+ # as those of the calling tool.
580
+ #
581
+ # This method is often used if you are already in a bundle and need to
582
+ # run a tool that uses a different bundle. It may also be necessary on
583
+ # environments without "fork" (such as JRuby or Ruby on Windows).
584
+ #
585
+ # ### Example
586
+ #
587
+ # Run the "system version" tool and capture its output.
588
+ #
589
+ # str = capture_separate_tool(["system", "version"]).chomp
590
+ # puts "Version was #{str}"
591
+ #
592
+ # @param cmd [String,Array<String>] The tool to execute.
593
+ # @param opts [keywords] The command options. See the section on
594
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
595
+ # documentation.
596
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
597
+ # the subprocess. See the section on Controlling Processes in the
598
+ # {Toys::StandardMixins::Exec} module documentation.
599
+ #
600
+ # @return [String] What was written to standard out.
601
+ #
602
+ def capture_separate_tool(cmd, **opts, &block)
603
+ # Source available in the toys-core gem
604
+ end
605
+
606
+ ##
607
+ # Execute the given string in a shell. Returns the exit code.
608
+ # Cannot be run in the background.
609
+ #
610
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
611
+ # yielded to it.
612
+ #
613
+ # ### Example
614
+ #
615
+ # Run a shell script
616
+ #
617
+ # exit_code = sh("cd mydir && git init")
618
+ # puts exit_code == 0 ? "Success!" : "Failed!"
619
+ #
620
+ # @param cmd [String] The shell command to execute.
621
+ # @param opts [keywords] The command options. See the section on
622
+ # Configuration Options in the {Toys::StandardMixins::Exec} module
623
+ # documentation.
624
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
625
+ # the subprocess. See the section on Controlling Processes in the
626
+ # {Toys::StandardMixins::Exec} module documentation.
627
+ #
628
+ # @return [Integer] The exit code
629
+ #
630
+ def sh(cmd, **opts, &block)
631
+ # Source available in the toys-core gem
632
+ end
633
+
634
+ ##
635
+ # Exit if the given status code is nonzero. Otherwise, returns 0.
636
+ #
637
+ # @param status [Integer,Process::Status,Toys::Utils::Exec::Result]
638
+ # @return [Integer]
639
+ #
640
+ def exit_on_nonzero_status(status)
641
+ # Source available in the toys-core gem
642
+ end
643
+ end
644
+ end
645
+ end
@@ -0,0 +1,18 @@
1
+ module Toys
2
+ module StandardMixins
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # A module that provides all methods in the "fileutils" standard library.
7
+ #
8
+ # You may make the methods in the `FileUtils` standard library module
9
+ # available to your tool by including the following directive in your tool
10
+ # configuration:
11
+ #
12
+ # include :fileutils
13
+ #
14
+ module Fileutils
15
+ include Mixin
16
+ end
17
+ end
18
+ end