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,721 @@
1
+ module Toys
2
+ module Utils
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # A service that executes subprocesses.
7
+ #
8
+ # This service provides a convenient interface for controlling spawned
9
+ # processes and their streams. It also provides shortcuts for common cases
10
+ # such as invoking Ruby in a subprocess or capturing output in a string.
11
+ #
12
+ # This class is not loaded by default. Before using it directly, you should
13
+ # `require "toys/utils/exec"`
14
+ #
15
+ # ### Controlling processes
16
+ #
17
+ # A process can be started in the *foreground* or the *background*. If you
18
+ # start a foreground process, it will "take over" your standard input and
19
+ # output streams by default, and it will keep control until it completes.
20
+ # If you start a background process, its streams will be redirected to null
21
+ # by default, and control will be returned to you immediately.
22
+ #
23
+ # When a process is running, you can control it using a
24
+ # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
25
+ # the process's input and output streams, send it signals, or wait for it
26
+ # to complete.
27
+ #
28
+ # When running a process in the foreground, the controller will be yielded
29
+ # to an optional block. For example, the following code starts a process in
30
+ # the foreground and passes its output stream to a controller.
31
+ #
32
+ # exec_service.exec(["git", "init"], out: :controller) do |controller|
33
+ # loop do
34
+ # line = controller.out.gets
35
+ # break if line.nil?
36
+ # puts "Got line: #{line}"
37
+ # end
38
+ # end
39
+ #
40
+ # When running a process in the background, the controller is returned from
41
+ # the method that starts the process:
42
+ #
43
+ # controller = exec_service.exec(["git", "init"], background: true)
44
+ #
45
+ # ### Stream handling
46
+ #
47
+ # By default, subprocess streams are connected to the corresponding streams
48
+ # in the parent process. You can change this behavior, redirecting streams
49
+ # or providing ways to control them, using the `:in`, `:out`, and `:err`
50
+ # options.
51
+ #
52
+ # Three general strategies are available for custom stream handling. First,
53
+ # you may redirect to other streams such as files, IO objects, or Ruby
54
+ # strings. Some of these options map directly to options provided by the
55
+ # `Process#spawn` method. Second, you may use a controller to manipulate
56
+ # the streams programmatically. Third, you may capture output stream data
57
+ # and make it available in the result.
58
+ #
59
+ # Following is a full list of the stream handling options, along with how
60
+ # to specify them using the `:in`, `:out`, and `:err` options.
61
+ #
62
+ # * **Inherit parent stream:** You may inherit the corresponding stream
63
+ # in the parent process by passing `:inherit` as the option value. This
64
+ # is the default if the subprocess is *not* run in the background.
65
+ # * **Redirect to null:** You may redirect to a null stream by passing
66
+ # `:null` as the option value. This connects to a stream that is not
67
+ # closed but contains no data, i.e. `/dev/null` on unix systems. This
68
+ # is the default if the subprocess is run in the background.
69
+ # * **Close the stream:** You may close the stream by passing `:close` as
70
+ # the option value. This is the same as passing `:close` to
71
+ # `Process#spawn`.
72
+ # * **Redirect to a file:** You may redirect to a file. This reads from
73
+ # an existing file when connected to `:in`, and creates or appends to a
74
+ # file when connected to `:out` or `:err`. To specify a file, use the
75
+ # setting `[:file, "/path/to/file"]`. You may also, when writing a
76
+ # file, append an optional mode and permission code to the array. For
77
+ # example, `[:file, "/path/to/file", "a", 0644]`.
78
+ # * **Redirect to an IO object:** You may redirect to an IO object in the
79
+ # parent process, by passing the IO object as the option value. You may
80
+ # use any IO object. For example, you could connect the child's output
81
+ # to the parent's error using `out: $stderr`, or you could connect to
82
+ # an existing File stream. Unlike `Process#spawn`, this works for IO
83
+ # objects that do not have a corresponding file descriptor (such as
84
+ # StringIO objects). In such a case, a thread will be spawned to pipe
85
+ # the IO data through to the child process.
86
+ # * **Combine with another child stream:** You may redirect one child
87
+ # output stream to another, to combine them. To merge the child's error
88
+ # stream into its output stream, use `err: [:child, :out]`.
89
+ # * **Read from a string:** You may pass a string to the input stream by
90
+ # setting `[:string, "the string"]`. This works only for `:in`.
91
+ # * **Capture output stream:** You may capture a stream and make it
92
+ # available on the {Toys::Utils::Exec::Result} object, using the
93
+ # setting `:capture`. This works only for the `:out` and `:err`
94
+ # streams.
95
+ # * **Use the controller:** You may hook a stream to the controller using
96
+ # the setting `:controller`. You can then manipulate the stream via the
97
+ # controller. If you pass a block to {Toys::Utils::Exec#exec}, it
98
+ # yields the {Toys::Utils::Exec::Controller}, giving you access to
99
+ # streams.
100
+ #
101
+ # ### Result handling
102
+ #
103
+ # A subprocess result is represented by a {Toys::Utils::Exec::Result}
104
+ # object, which includes the exit code, the content of any captured output
105
+ # streams, and any exeption raised when attempting to run the process.
106
+ # When you run a process in the foreground, the method will return a result
107
+ # object. When you run a process in the background, you can obtain the
108
+ # result from the controller once the process completes.
109
+ #
110
+ # The following example demonstrates running a process in the foreground
111
+ # and getting the exit code:
112
+ #
113
+ # result = exec_service.exec(["git", "init"])
114
+ # puts "exit code: #{result.exit_code}"
115
+ #
116
+ # The following example demonstrates starting a process in the background,
117
+ # waiting for it to complete, and getting its exit code:
118
+ #
119
+ # controller = exec_service.exec(["git", "init"], background: true)
120
+ # result = controller.result(timeout: 1.0)
121
+ # if result
122
+ # puts "exit code: #{result.exit_code}"
123
+ # else
124
+ # puts "timed out"
125
+ # end
126
+ #
127
+ # You can also provide a callback that is executed once a process
128
+ # completes. For example:
129
+ #
130
+ # my_callback = proc do |result|
131
+ # puts "exit code: #{result.exit_code}"
132
+ # end
133
+ # exec_service.exec(["git", "init"], result_callback: my_callback)
134
+ #
135
+ # ### Configuration options
136
+ #
137
+ # A variety of options can be used to control subprocesses. These can be
138
+ # provided to any method that starts a subprocess. Youc an also set
139
+ # defaults by calling {Toys::Utils::Exec#configure_defaults}.
140
+ #
141
+ # Options that affect the behavior of subprocesses:
142
+ #
143
+ # * `:env` (Hash) Environment variables to pass to the subprocess.
144
+ # Keys represent variable names and should be strings. Values should be
145
+ # either strings or `nil`, which unsets the variable.
146
+ #
147
+ # * `:background` (Boolean) Runs the process in the background if `true`.
148
+ #
149
+ # * `:result_callback` (Proc) Called and passed the result object when
150
+ # the subprocess exits.
151
+ #
152
+ # Options for connecting input and output streams. See the section above on
153
+ # stream handling for info on the values that can be passed.
154
+ #
155
+ # * `:in` Connects the input stream of the subprocess. See the section on
156
+ # stream handling.
157
+ #
158
+ # * `:out` Connects the standard output stream of the subprocess. See the
159
+ # section on stream handling.
160
+ #
161
+ # * `:err` Connects the standard error stream of the subprocess. See the
162
+ # section on stream handling.
163
+ #
164
+ # Options related to logging and reporting:
165
+ #
166
+ # * `:logger` (Logger) Logger to use for logging the actual command. If
167
+ # not present, the command is not logged.
168
+ #
169
+ # * `:log_level` (Integer,false) Level for logging the actual command.
170
+ # Defaults to Logger::INFO if not present. You may also pass `false` to
171
+ # disable logging of the command.
172
+ #
173
+ # * `:log_cmd` (String) The string logged for the actual command.
174
+ # Defaults to the `inspect` representation of the command.
175
+ #
176
+ # * `:name` (Object) An optional object that can be used to identify this
177
+ # subprocess. It is available in the controller and result objects.
178
+ #
179
+ # In addition, the following options recognized by
180
+ # [`Process#spawn`](https://ruby-doc.org/core/Process.html#method-c-spawn)
181
+ # are supported.
182
+ #
183
+ # * `:chdir` (String) Set the working directory for the command.
184
+ #
185
+ # * `:close_others` (Boolean) Whether to close non-redirected
186
+ # non-standard file descriptors.
187
+ #
188
+ # * `:new_pgroup` (Boolean) Create new process group (Windows only).
189
+ #
190
+ # * `:pgroup` (Integer,true,nil) The process group setting.
191
+ #
192
+ # * `:umask` (Integer) Umask setting for the new process.
193
+ #
194
+ # * `:unsetenv_others` (Boolean) Clear environment variables except those
195
+ # explicitly set.
196
+ #
197
+ # Any other option key will result in an `ArgumentError`.
198
+ #
199
+ class Exec
200
+ ##
201
+ # Create an exec service.
202
+ #
203
+ # @param block [Proc] A block that is called if a key is not found. It is
204
+ # passed the unknown key, and expected to return a default value
205
+ # (which can be nil).
206
+ # @param opts [keywords] Initial default options. See {Toys::Utils::Exec}
207
+ # for a description of the options.
208
+ #
209
+ def initialize(**opts, &block)
210
+ # Source available in the toys-core gem
211
+ end
212
+
213
+ ##
214
+ # Set default options. See {Toys::Utils::Exec} for a description of the
215
+ # options.
216
+ #
217
+ # @param opts [keywords] New default options to set
218
+ # @return [self]
219
+ #
220
+ def configure_defaults(**opts)
221
+ # Source available in the toys-core gem
222
+ end
223
+
224
+ ##
225
+ # Execute a command. The command may be given as a single string to pass
226
+ # to a shell, or an array of strings indicating a posix command.
227
+ #
228
+ # If the process is not set to run in the background, and a block is
229
+ # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
230
+ #
231
+ # @param cmd [String,Array<String>] The command to execute.
232
+ # @param opts [keywords] The command options. See the section on
233
+ # configuration options in the {Toys::Utils::Exec} class docs.
234
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
235
+ # for the subprocess streams.
236
+ #
237
+ # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
238
+ # the process is running in the background.
239
+ # @return [Toys::Utils::Exec::Result] The result, if the process ran in
240
+ # the foreground.
241
+ #
242
+ def exec(cmd, **opts, &block)
243
+ # Source available in the toys-core gem
244
+ end
245
+
246
+ ##
247
+ # Spawn a ruby process and pass the given arguments to it.
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
+ # @param args [String,Array<String>] The arguments to ruby.
253
+ # @param opts [keywords] The command options. See the section on
254
+ # configuration options in the {Toys::Utils::Exec} class docs.
255
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
256
+ # for the subprocess streams.
257
+ #
258
+ # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
259
+ # the process is running in the background.
260
+ # @return [Toys::Utils::Exec::Result] The result, if the process ran in
261
+ # the foreground.
262
+ #
263
+ def exec_ruby(args, **opts, &block)
264
+ # Source available in the toys-core gem
265
+ end
266
+ alias ruby exec_ruby
267
+
268
+ ##
269
+ # Execute a proc in a fork.
270
+ #
271
+ # If the process is not set to run in the background, and a block is
272
+ # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
273
+ #
274
+ # @param func [Proc] The proc to call.
275
+ # @param opts [keywords] The command options. See the section on
276
+ # configuration options in the {Toys::Utils::Exec} class docs.
277
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
278
+ # for the subprocess streams.
279
+ #
280
+ # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
281
+ # the process is running in the background.
282
+ # @return [Toys::Utils::Exec::Result] The result, if the process ran in
283
+ # the foreground.
284
+ #
285
+ def exec_proc(func, **opts, &block)
286
+ # Source available in the toys-core gem
287
+ end
288
+
289
+ ##
290
+ # Execute a command. The command may be given as a single string to pass
291
+ # to a shell, or an array of strings indicating a posix command.
292
+ #
293
+ # Captures standard out and returns it as a string.
294
+ # Cannot be run in the background.
295
+ #
296
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
297
+ # yielded to it.
298
+ #
299
+ # @param cmd [String,Array<String>] The command to execute.
300
+ # @param opts [keywords] The command options. See the section on
301
+ # configuration options in the {Toys::Utils::Exec} class docs.
302
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
303
+ # for the subprocess streams.
304
+ #
305
+ # @return [String] What was written to standard out.
306
+ #
307
+ def capture(cmd, **opts, &block)
308
+ # Source available in the toys-core gem
309
+ end
310
+
311
+ ##
312
+ # Spawn a ruby process and pass the given arguments to it.
313
+ #
314
+ # Captures standard out and returns it as a string.
315
+ # Cannot be run in the background.
316
+ #
317
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
318
+ # yielded to it.
319
+ #
320
+ # @param args [String,Array<String>] The arguments to ruby.
321
+ # @param opts [keywords] The command options. See the section on
322
+ # configuration options in the {Toys::Utils::Exec} class docs.
323
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
324
+ # for the subprocess streams.
325
+ #
326
+ # @return [String] What was written to standard out.
327
+ #
328
+ def capture_ruby(args, **opts, &block)
329
+ # Source available in the toys-core gem
330
+ end
331
+
332
+ ##
333
+ # Execute a proc in a fork.
334
+ #
335
+ # Captures standard out and returns it as a string.
336
+ # Cannot be run in the background.
337
+ #
338
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
339
+ # yielded to it.
340
+ #
341
+ # @param func [Proc] The proc to call.
342
+ # @param opts [keywords] The command options. See the section on
343
+ # configuration options in the {Toys::Utils::Exec} class docs.
344
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
345
+ # for the subprocess streams.
346
+ #
347
+ # @return [String] What was written to standard out.
348
+ #
349
+ def capture_proc(func, **opts, &block)
350
+ # Source available in the toys-core gem
351
+ end
352
+
353
+ ##
354
+ # Execute the given string in a shell. Returns the exit code.
355
+ # Cannot be run in the background.
356
+ #
357
+ # If a block is provided, a {Toys::Utils::Exec::Controller} will be
358
+ # yielded to it.
359
+ #
360
+ # @param cmd [String] The shell command to execute.
361
+ # @param opts [keywords] The command options. See the section on
362
+ # configuration options in the {Toys::Utils::Exec} class docs.
363
+ # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
364
+ # for the subprocess streams.
365
+ #
366
+ # @return [Integer] The exit code
367
+ #
368
+ def sh(cmd, **opts, &block)
369
+ # Source available in the toys-core gem
370
+ end
371
+
372
+ ##
373
+ # **_Defined in the toys-core gem_**
374
+ #
375
+ # An object that controls a subprocess. This object is returned from an
376
+ # execution running in the background, or is yielded to a control block
377
+ # for an execution running in the foreground.
378
+ # You may use this object to interact with the subcommand's streams,
379
+ # send signals to the process, and get its result.
380
+ #
381
+ class Controller
382
+ ##
383
+ # The subcommand's name.
384
+ # @return [Object]
385
+ #
386
+ attr_reader :name
387
+
388
+ ##
389
+ # The subcommand's standard input stream (which can be written to).
390
+ #
391
+ # @return [IO] if the command was configured with `in: :controller`
392
+ # @return [nil] if the command was not configured with
393
+ # `in: :controller`
394
+ #
395
+ attr_reader :in
396
+
397
+ ##
398
+ # The subcommand's standard output stream (which can be read from).
399
+ #
400
+ # @return [IO] if the command was configured with `out: :controller`
401
+ # @return [nil] if the command was not configured with
402
+ # `out: :controller`
403
+ #
404
+ attr_reader :out
405
+
406
+ ##
407
+ # The subcommand's standard error stream (which can be read from).
408
+ #
409
+ # @return [IO] if the command was configured with `err: :controller`
410
+ # @return [nil] if the command was not configured with
411
+ # `err: :controller`
412
+ #
413
+ attr_reader :err
414
+
415
+ ##
416
+ # The process ID.
417
+ #
418
+ # Exactly one of {#exception} and {#pid} will be non-nil.
419
+ #
420
+ # @return [Integer] if the process start was successful
421
+ # @return [nil] if the process could not be started.
422
+ #
423
+ attr_reader :pid
424
+
425
+ ##
426
+ # The exception raised when the process failed to start.
427
+ #
428
+ # Exactly one of {#exception} and {#pid} will be non-nil.
429
+ #
430
+ # @return [Exception] if the process failed to start.
431
+ # @return [nil] if the process start was successful.
432
+ #
433
+ attr_reader :exception
434
+
435
+ ##
436
+ # Captures the remaining data in the given stream.
437
+ # After calling this, do not read directly from the stream.
438
+ #
439
+ # @param which [:out,:err] Which stream to capture
440
+ # @return [self]
441
+ #
442
+ def capture(which)
443
+ # Source available in the toys-core gem
444
+ end
445
+
446
+ ##
447
+ # Captures the remaining data in the standard output stream.
448
+ # After calling this, do not read directly from the stream.
449
+ #
450
+ # @return [self]
451
+ #
452
+ def capture_out
453
+ # Source available in the toys-core gem
454
+ end
455
+
456
+ ##
457
+ # Captures the remaining data in the standard error stream.
458
+ # After calling this, do not read directly from the stream.
459
+ #
460
+ # @return [self]
461
+ #
462
+ def capture_err
463
+ # Source available in the toys-core gem
464
+ end
465
+
466
+ ##
467
+ # Redirects the remainder of the given stream.
468
+ #
469
+ # You may specify the stream as an IO or IO-like object, or as a file
470
+ # specified by its path. If specifying a file, you may optionally
471
+ # provide the mode and permissions for the call to `File#open`. You can
472
+ # also specify the value `:null` to indicate the null file.
473
+ #
474
+ # After calling this, do not interact directly with the stream.
475
+ #
476
+ # @param which [:in,:out,:err] Which stream to redirect
477
+ # @param io [IO,StringIO,String,:null] Where to redirect the stream
478
+ # @param io_args [Object...] The mode and permissions for opening the
479
+ # file, if redirecting to/from a file.
480
+ # @return [self]
481
+ #
482
+ def redirect(which, io, *io_args)
483
+ # Source available in the toys-core gem
484
+ end
485
+
486
+ ##
487
+ # Redirects the remainder of the standard input stream.
488
+ #
489
+ # You may specify the stream as an IO or IO-like object, or as a file
490
+ # specified by its path. If specifying a file, you may optionally
491
+ # provide the mode and permissions for the call to `File#open`. You can
492
+ # also specify the value `:null` to indicate the null file.
493
+ #
494
+ # After calling this, do not interact directly with the stream.
495
+ #
496
+ # @param io [IO,StringIO,String,:null] Where to redirect the stream
497
+ # @param io_args [Object...] The mode and permissions for opening the
498
+ # file, if redirecting from a file.
499
+ # @return [self]
500
+ #
501
+ def redirect_in(io, *io_args)
502
+ # Source available in the toys-core gem
503
+ end
504
+
505
+ ##
506
+ # Redirects the remainder of the standard output stream.
507
+ #
508
+ # You may specify the stream as an IO or IO-like object, or as a file
509
+ # specified by its path. If specifying a file, you may optionally
510
+ # provide the mode and permissions for the call to `File#open`. You can
511
+ # also specify the value `:null` to indicate the null file.
512
+ #
513
+ # After calling this, do not interact directly with the stream.
514
+ #
515
+ # @param io [IO,StringIO,String,:null] Where to redirect the stream
516
+ # @param io_args [Object...] The mode and permissions for opening the
517
+ # file, if redirecting to a file.
518
+ # @return [self]
519
+ #
520
+ def redirect_out(io, *io_args)
521
+ # Source available in the toys-core gem
522
+ end
523
+
524
+ ##
525
+ # Redirects the remainder of the standard error stream.
526
+ #
527
+ # You may specify the stream as an IO or IO-like object, or as a file
528
+ # specified by its path. If specifying a file, you may optionally
529
+ # provide the mode and permissions for the call to `File#open`.
530
+ #
531
+ # After calling this, do not interact directly with the stream.
532
+ #
533
+ # @param io [IO,StringIO,String] Where to redirect the stream
534
+ # @param io_args [Object...] The mode and permissions for opening the
535
+ # file, if redirecting to a file.
536
+ # @return [self]
537
+ #
538
+ def redirect_err(io, *io_args)
539
+ # Source available in the toys-core gem
540
+ end
541
+
542
+ ##
543
+ # Send the given signal to the process. The signal may be specified
544
+ # by name or number.
545
+ #
546
+ # @param sig [Integer,String] The signal to send.
547
+ # @return [self]
548
+ #
549
+ def kill(sig)
550
+ # Source available in the toys-core gem
551
+ end
552
+ alias signal kill
553
+
554
+ ##
555
+ # Determine whether the subcommand is still executing
556
+ #
557
+ # @return [Boolean]
558
+ #
559
+ def executing?
560
+ # Source available in the toys-core gem
561
+ end
562
+
563
+ ##
564
+ # Wait for the subcommand to complete, and return a result object.
565
+ #
566
+ # Closes the control streams if present. The stdin stream is always
567
+ # closed, even if the call times out. The stdout and stderr streams are
568
+ # closed only after the command terminates.
569
+ #
570
+ # @param timeout [Numeric,nil] The timeout in seconds, or `nil` to
571
+ # wait indefinitely.
572
+ # @return [Toys::Utils::Exec::Result] The result object
573
+ # @return [nil] if a timeout occurred.
574
+ #
575
+ def result(timeout: nil)
576
+ # Source available in the toys-core gem
577
+ end
578
+ end
579
+
580
+ ##
581
+ # **_Defined in the toys-core gem_**
582
+ #
583
+ # The result returned from a subcommand execution. This includes the
584
+ # identifying name of the execution (if any), the result status of the
585
+ # execution, and any captured stream output.
586
+ #
587
+ # Possible result statuses are:
588
+ #
589
+ # * The process failed to start. {Result#failed?} will return true, and
590
+ # {Result#exception} will return an exception describing the failure
591
+ # (often an errno).
592
+ # * The process executed and exited with a normal exit code. Either
593
+ # {Result#success?} or {Result#error?} will return true, and
594
+ # {Result.exit_code} will return the numeric exit code.
595
+ # * The process executed but was terminated by an uncaught signal.
596
+ # {Result#signaled?} will return true, and {Result#signal_code} will
597
+ # return the numeric signal code.
598
+ #
599
+ class Result
600
+ ##
601
+ # The subcommand's name.
602
+ #
603
+ # @return [Object]
604
+ #
605
+ attr_reader :name
606
+
607
+ ##
608
+ # The captured output string.
609
+ #
610
+ # @return [String] The string captured from stdout.
611
+ # @return [nil] if the command was not configured to capture stdout.
612
+ #
613
+ attr_reader :captured_out
614
+
615
+ ##
616
+ # The captured error string.
617
+ #
618
+ # @return [String] The string captured from stderr.
619
+ # @return [nil] if the command was not configured to capture stderr.
620
+ #
621
+ attr_reader :captured_err
622
+
623
+ ##
624
+ # The Ruby process status object, providing various information about
625
+ # the ending state of the process.
626
+ #
627
+ # Exactly one of {#exception} and {#status} will be non-nil.
628
+ #
629
+ # @return [Process::Status] The status, if the process was successfully
630
+ # spanwed and terminated.
631
+ # @return [nil] if the process could not be started.
632
+ #
633
+ attr_reader :status
634
+
635
+ ##
636
+ # The exception raised if a process couldn't be started.
637
+ #
638
+ # Exactly one of {#exception} and {#status} will be non-nil.
639
+ # Exactly one of {#exception}, {#exit_code}, or {#signal_code} will be
640
+ # non-nil.
641
+ #
642
+ # @return [Exception] The exception raised from process start.
643
+ # @return [nil] if the process started successfully.
644
+ #
645
+ attr_reader :exception
646
+
647
+ ##
648
+ # The numeric status code for a process that exited normally,
649
+ #
650
+ # Exactly one of {#exception}, {#exit_code}, or {#signal_code} will be
651
+ # non-nil.
652
+ #
653
+ # @return [Integer] the numeric status code, if the process started
654
+ # successfully and exited normally.
655
+ # @return [nil] if the process did not start successfully, or was
656
+ # terminated by an uncaught signal.
657
+ #
658
+ def exit_code
659
+ # Source available in the toys-core gem
660
+ end
661
+
662
+ ##
663
+ # The numeric signal code that caused process termination.
664
+ #
665
+ # Exactly one of {#exception}, {#exit_code}, or {#signal_code} will be
666
+ # non-nil.
667
+ #
668
+ # @return [Integer] The signal that caused the process to terminate.
669
+ # @return [nil] if the process did not start successfully, or executed
670
+ # and exited with a normal exit code.
671
+ #
672
+ def signal_code
673
+ # Source available in the toys-core gem
674
+ end
675
+ alias term_signal signal_code
676
+
677
+ ##
678
+ # Returns true if the subprocess failed to start, or false if the
679
+ # process was able to execute.
680
+ #
681
+ # @return [Boolean]
682
+ #
683
+ def failed?
684
+ # Source available in the toys-core gem
685
+ end
686
+
687
+ ##
688
+ # Returns true if the subprocess terminated due to an unhandled signal,
689
+ # or false if the process failed to start or exited normally.
690
+ #
691
+ # @return [Boolean]
692
+ #
693
+ def signaled?
694
+ # Source available in the toys-core gem
695
+ end
696
+
697
+ ##
698
+ # Returns true if the subprocess terminated with a zero status, or
699
+ # false if the process failed to start, terminated due to a signal, or
700
+ # returned a nonzero status.
701
+ #
702
+ # @return [Boolean]
703
+ #
704
+ def success?
705
+ # Source available in the toys-core gem
706
+ end
707
+
708
+ ##
709
+ # Returns true if the subprocess terminated with a nonzero status, or
710
+ # false if the process failed to start, terminated due to a signal, or
711
+ # returned a zero status.
712
+ #
713
+ # @return [Boolean]
714
+ #
715
+ def error?
716
+ # Source available in the toys-core gem
717
+ end
718
+ end
719
+ end
720
+ end
721
+ end