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.
- checksums.yaml +4 -4
- data/.yardopts +2 -0
- data/CHANGELOG.md +44 -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,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
|