gubbins-shell 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +19 -0
- data/LICENSE +289 -0
- data/README.md +186 -0
- data/lib/gubbins/shell.rb +4 -0
- data/lib/shell/all.rb +34 -0
- data/lib/shell/base_64.rb +40 -0
- data/lib/shell/clam_av.rb +68 -0
- data/lib/shell/command.rb +1400 -0
- data/lib/shell/convert.rb +312 -0
- data/lib/shell/errors.rb +89 -0
- data/lib/shell/exiftool.rb +15 -0
- data/lib/shell/file.rb +84 -0
- data/lib/shell/ghostscript.rb +239 -0
- data/lib/shell/identify.rb +111 -0
- data/lib/shell/img2_pdf.rb +47 -0
- data/lib/shell/magick.rb +111 -0
- data/lib/shell/open_ssl.rb +26 -0
- data/lib/shell/optional_dependencies.rb +36 -0
- data/lib/shell/path.rb +40 -0
- data/lib/shell/pdf_detach.rb +86 -0
- data/lib/shell/pdffonts.rb +73 -0
- data/lib/shell/pdfimages.rb +48 -0
- data/lib/shell/pdfinfo.rb +79 -0
- data/lib/shell/pdftocairo.rb +24 -0
- data/lib/shell/pdftotext.rb +32 -0
- data/lib/shell/ping.rb +50 -0
- data/lib/shell/power_array.rb +42 -0
- data/lib/shell/seven_zip.rb +142 -0
- data/lib/shell/tesseract.rb +120 -0
- data/lib/shell/testing/mock/shell/clam_av.rb +12 -0
- data/lib/shell/testing/mock/shell/command.rb +241 -0
- data/lib/shell/testing/mock/shell/configurator.rb +223 -0
- data/lib/shell/testing/mock/shell/convert.rb +12 -0
- data/lib/shell/testing/mock/shell/file.rb +12 -0
- data/lib/shell/testing/mock/shell/ghostscript.rb +13 -0
- data/lib/shell/testing/mock/shell/identify.rb +11 -0
- data/lib/shell/testing/mock/shell/open_ssl.rb +11 -0
- data/lib/shell/testing/mock/shell/tesseract.rb +12 -0
- data/lib/shell/testing/mock/shell/unzip.rb +20 -0
- data/lib/shell/testing/mock/shell/zip.rb +11 -0
- data/lib/shell/testing.rb +15 -0
- data/lib/shell/tiff_2_pdf.rb +19 -0
- data/lib/shell/unzip.rb +137 -0
- data/lib/shell/version.rb +5 -0
- data/lib/shell/zbar.rb +123 -0
- data/lib/shell/zip.rb +52 -0
- data/lib/shell.rb +16 -0
- metadata +116 -0
|
@@ -0,0 +1,1400 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "open3"
|
|
4
|
+
require "pathname"
|
|
5
|
+
require "active_support"
|
|
6
|
+
require "active_support/core_ext/string/inflections"
|
|
7
|
+
require_relative "optional_dependencies"
|
|
8
|
+
|
|
9
|
+
module Shell
|
|
10
|
+
# `Shell::Command` allows you to create wrapper classes for executing shell commands
|
|
11
|
+
# with a simple DSL.
|
|
12
|
+
#
|
|
13
|
+
# This is what a minimal example looks like:
|
|
14
|
+
#
|
|
15
|
+
# ```ruby
|
|
16
|
+
# module Shell
|
|
17
|
+
# class Pgrep < Command
|
|
18
|
+
# command_path "/usr/bin/pgrep"
|
|
19
|
+
# end
|
|
20
|
+
# end
|
|
21
|
+
# ```
|
|
22
|
+
#
|
|
23
|
+
# This command can now be executed with `.exec`:
|
|
24
|
+
#
|
|
25
|
+
# ```ruby
|
|
26
|
+
# Shell::Pgrep.exec
|
|
27
|
+
# # => Command: /usr/bin/pgrep
|
|
28
|
+
# # PID: 38443
|
|
29
|
+
# # Status: 2 (failure)
|
|
30
|
+
# # Stdout: 0 Bytes
|
|
31
|
+
# # Sterr: 145 Bytes
|
|
32
|
+
# ```
|
|
33
|
+
#
|
|
34
|
+
# The return value of `.exec` is a `Shell::Command::Result`:
|
|
35
|
+
#
|
|
36
|
+
# ```ruby
|
|
37
|
+
# r = Shell::Pgrep.exec
|
|
38
|
+
# # => Command: /usr/bin/pgrep
|
|
39
|
+
# # PID: 38448
|
|
40
|
+
# # Status: 2 (failure)
|
|
41
|
+
# # Stdout: 0 Bytes
|
|
42
|
+
# # Sterr: 145 Bytes
|
|
43
|
+
# r.success?
|
|
44
|
+
# # => false
|
|
45
|
+
# r.failure?
|
|
46
|
+
# # => true
|
|
47
|
+
# r.status
|
|
48
|
+
# # => 2
|
|
49
|
+
# r.stdout
|
|
50
|
+
# # => ""
|
|
51
|
+
# r.stderr
|
|
52
|
+
# # => "usage: pgrep [-Lfilnoqvx] [-d delim] [-F pidfile] [-G gid]\n [...]"
|
|
53
|
+
# ```
|
|
54
|
+
#
|
|
55
|
+
# In addition to these methods, wrappers can use the `Result#value` attribute
|
|
56
|
+
# to return custom values:
|
|
57
|
+
#
|
|
58
|
+
# ```ruby
|
|
59
|
+
# r.value
|
|
60
|
+
# # => nil
|
|
61
|
+
# ```
|
|
62
|
+
#
|
|
63
|
+
# If desired, use `Result#raise_failures` to have your `Command` raise an exception
|
|
64
|
+
# on non-zero exit codes. `#raise_failures` returns `self` and is thus chainable:
|
|
65
|
+
#
|
|
66
|
+
# ```ruby
|
|
67
|
+
# value =
|
|
68
|
+
# Shell::Pgrep.exec
|
|
69
|
+
# .raise_failures
|
|
70
|
+
# .value
|
|
71
|
+
# ```
|
|
72
|
+
#
|
|
73
|
+
# ### Shell arguments, options and flags
|
|
74
|
+
#
|
|
75
|
+
# As a rule of thumb: arguments passed to `.exec` become positioned shell command arguments,
|
|
76
|
+
# keyword arguments become options or flags:
|
|
77
|
+
#
|
|
78
|
+
# ```ruby
|
|
79
|
+
# Shell::Pgrep.exec "rails", foo: 1, x: 2
|
|
80
|
+
# # => Command: /usr/bin/pgrep --foo 1 -x 2 rails
|
|
81
|
+
# ```
|
|
82
|
+
#
|
|
83
|
+
# To pass a flag, supply a keyword argumente with a `nil` value:
|
|
84
|
+
#
|
|
85
|
+
# ```ruby
|
|
86
|
+
# Shell::Pgrep.exec "rails", foo: nil, x: nil
|
|
87
|
+
# # => Command: /usr/bin/pgrep --foo -x rails
|
|
88
|
+
# ```
|
|
89
|
+
#
|
|
90
|
+
# For ease of use, `Symbol` arguments also become flags:
|
|
91
|
+
#
|
|
92
|
+
# ```ruby
|
|
93
|
+
# Shell::Pgrep.exec "rails", :foo, :x
|
|
94
|
+
# # => Command: /usr/bin/pgrep --foo -x rails
|
|
95
|
+
# ```
|
|
96
|
+
#
|
|
97
|
+
# ### Formatting options
|
|
98
|
+
#
|
|
99
|
+
# In the default setting `option_prefix :auto`:
|
|
100
|
+
#
|
|
101
|
+
# ```ruby
|
|
102
|
+
# module Shell
|
|
103
|
+
# class Pgrep < Command
|
|
104
|
+
# command_path "/usr/bin/pgrep"
|
|
105
|
+
# option_prefix :auto
|
|
106
|
+
# end
|
|
107
|
+
# end
|
|
108
|
+
# ```
|
|
109
|
+
#
|
|
110
|
+
# , short options are prefixed with "-", longer options with "--":
|
|
111
|
+
#
|
|
112
|
+
# ```ruby
|
|
113
|
+
# Shell::Pgrep.exec "rails", foo: 1, x: 2
|
|
114
|
+
# # => Command: /usr/bin/pgrep --foo 1 -x 2 rails
|
|
115
|
+
# ```
|
|
116
|
+
#
|
|
117
|
+
# If the command you are wrapping expects differently, set your prefix as a `String`:
|
|
118
|
+
#
|
|
119
|
+
# ```ruby
|
|
120
|
+
# module Shell
|
|
121
|
+
# class Pgrep < Command
|
|
122
|
+
# command_path "/usr/bin/pgrep"
|
|
123
|
+
# option_prefix "-"
|
|
124
|
+
# end
|
|
125
|
+
# end
|
|
126
|
+
#
|
|
127
|
+
# Shell::Pgrep.exec "rails", foo: 1, x: 2
|
|
128
|
+
# # => Command: /usr/bin/pgrep -foo 1 -x 2 rails
|
|
129
|
+
# ```
|
|
130
|
+
#
|
|
131
|
+
# The order of positional arguments and options can be swapped with
|
|
132
|
+
# `positional_parameters: :first`:
|
|
133
|
+
#
|
|
134
|
+
# ```ruby
|
|
135
|
+
# module Shell
|
|
136
|
+
# class Pgrep < Command
|
|
137
|
+
# command_path "/usr/bin/pgrep"
|
|
138
|
+
# positional_parameters :first
|
|
139
|
+
# end
|
|
140
|
+
# end
|
|
141
|
+
#
|
|
142
|
+
# Shell::Pgrep.exec "rails", foo: 1, x: 2
|
|
143
|
+
# # => Command: /usr/bin/pgrep rails --foo 1 -x 2
|
|
144
|
+
# ```
|
|
145
|
+
#
|
|
146
|
+
# ### Transforming options
|
|
147
|
+
#
|
|
148
|
+
# The translation from "`.exec` method argument" to "shell command argument" can
|
|
149
|
+
# be controlled through the `transform_options` macro:
|
|
150
|
+
#
|
|
151
|
+
# ```ruby
|
|
152
|
+
# module Shell
|
|
153
|
+
# class Pgrep < Command
|
|
154
|
+
# command_path "/usr/bin/pgrep"
|
|
155
|
+
#
|
|
156
|
+
# transform_options include_ancestors: :a
|
|
157
|
+
# end
|
|
158
|
+
# end
|
|
159
|
+
#
|
|
160
|
+
# Shell::Pgrep.exec "rails", :include_ancestors
|
|
161
|
+
# # => Command: /usr/bin/pgrep -a rails
|
|
162
|
+
# ```
|
|
163
|
+
#
|
|
164
|
+
# If the replacement value (here: `:a`) is a `Symbol`, it will be prefixed according to
|
|
165
|
+
# the `option_prefix` settings. `String` replacement values are passed through unformatted:
|
|
166
|
+
#
|
|
167
|
+
# ```ruby
|
|
168
|
+
# module Shell
|
|
169
|
+
# class Pgrep < Command
|
|
170
|
+
# command_path "/usr/bin/pgrep"
|
|
171
|
+
#
|
|
172
|
+
# transform_options include_ancestors: "!a"
|
|
173
|
+
# end
|
|
174
|
+
# end
|
|
175
|
+
#
|
|
176
|
+
# Shell::Pgrep.exec "rails", :include_ancestors
|
|
177
|
+
# # => Command: /usr/bin/pgrep !a rails
|
|
178
|
+
# ```
|
|
179
|
+
#
|
|
180
|
+
# If you need even more control - for example, because the command in question does not
|
|
181
|
+
# tolerate whitespace between option name and value - you can pass a string with a `#VALUE#`
|
|
182
|
+
# placeholder:
|
|
183
|
+
#
|
|
184
|
+
# ```ruby
|
|
185
|
+
# module Shell
|
|
186
|
+
# class Pgrep < Command
|
|
187
|
+
# command_path "/usr/bin/pgrep"
|
|
188
|
+
#
|
|
189
|
+
# transform_options some_option: "-x#VALUE#"
|
|
190
|
+
# end
|
|
191
|
+
# end
|
|
192
|
+
#
|
|
193
|
+
# Shell::Pgrep.exec "rails", some_option: "foo"
|
|
194
|
+
# # => Command: /usr/bin/pgrep -xfoo rails
|
|
195
|
+
# ```
|
|
196
|
+
#
|
|
197
|
+
# ### Result#value
|
|
198
|
+
#
|
|
199
|
+
# If STDOUT is not enough and you want to control the return value of your command, use
|
|
200
|
+
# `Result#value`. Take the output of `git --version` as an example:
|
|
201
|
+
#
|
|
202
|
+
# ```ruby
|
|
203
|
+
# module Shell
|
|
204
|
+
# class Git < Command
|
|
205
|
+
# command_path `which git`
|
|
206
|
+
# end
|
|
207
|
+
# end
|
|
208
|
+
#
|
|
209
|
+
# Shell::Git.exec(:version).stdout
|
|
210
|
+
# # => "git version 2.16.1"
|
|
211
|
+
# ```
|
|
212
|
+
#
|
|
213
|
+
# We now want to provide a convenience method on our wrapper that returns the plain version
|
|
214
|
+
# number only, and we will pass that parsed value back by setting it on `Result#value`:
|
|
215
|
+
#
|
|
216
|
+
# ```ruby
|
|
217
|
+
# module Shell
|
|
218
|
+
# class Git < Command
|
|
219
|
+
# command_path `which git`
|
|
220
|
+
#
|
|
221
|
+
# # `Shell::Command.version` is already taken, so we name the method `.get_version`
|
|
222
|
+
# def self.get_version
|
|
223
|
+
# result = exec(:version)
|
|
224
|
+
#
|
|
225
|
+
# return result if result.failure?
|
|
226
|
+
#
|
|
227
|
+
# result.value =
|
|
228
|
+
# result.stdout
|
|
229
|
+
# .split(" ")
|
|
230
|
+
# .last
|
|
231
|
+
#
|
|
232
|
+
# result
|
|
233
|
+
# end
|
|
234
|
+
# end
|
|
235
|
+
# end
|
|
236
|
+
#
|
|
237
|
+
# Shell::Git.get_version.value
|
|
238
|
+
# # => "2.16.1"
|
|
239
|
+
# ```
|
|
240
|
+
#
|
|
241
|
+
# A more compact way of dealing with command success or failure exists through two block
|
|
242
|
+
# handlers, `Result#on_success` and `Result#on_failure`. They both yield the `Result` object:
|
|
243
|
+
#
|
|
244
|
+
# ```ruby
|
|
245
|
+
# module Shell
|
|
246
|
+
# class Git < Command
|
|
247
|
+
# command_path `which git`
|
|
248
|
+
#
|
|
249
|
+
# def self.get_version
|
|
250
|
+
# exec(:version).on_success do |result|
|
|
251
|
+
# result.value =
|
|
252
|
+
# result.stdout
|
|
253
|
+
# .split(" ")
|
|
254
|
+
# .last
|
|
255
|
+
# end
|
|
256
|
+
# end
|
|
257
|
+
# end
|
|
258
|
+
# end
|
|
259
|
+
#
|
|
260
|
+
# Shell::Git.get_version.value
|
|
261
|
+
# # => "2.16.1"
|
|
262
|
+
# ```
|
|
263
|
+
#
|
|
264
|
+
# ### Supporting multiple versions of a command
|
|
265
|
+
#
|
|
266
|
+
# Every `Shell::Command` can support multiple versions of a shell command and help you
|
|
267
|
+
# abstract away the differences between them. This is useful for upgrade situations or
|
|
268
|
+
# to deal with differences between environments.
|
|
269
|
+
#
|
|
270
|
+
# One such example is `tesseract`, where the option format has changed between versions
|
|
271
|
+
# 3 and 4 - the older version expects long-form options to be prefixed with "-", while
|
|
272
|
+
# version 4 moved to the more common "--" prefix.
|
|
273
|
+
#
|
|
274
|
+
# To support multiple versions, use the `detect_version {}` and `version(:identifier) {}`
|
|
275
|
+
# DSL macros. For `tesseract`, our version 3 base class looks like this:
|
|
276
|
+
#
|
|
277
|
+
# ```ruby
|
|
278
|
+
# module Shell
|
|
279
|
+
# class Tesseract < Command
|
|
280
|
+
# command_path `which tesseract`
|
|
281
|
+
# option_prefix "-"
|
|
282
|
+
# positional_parameters :first
|
|
283
|
+
# end
|
|
284
|
+
# end
|
|
285
|
+
# ```
|
|
286
|
+
#
|
|
287
|
+
# We now add a detector block that returns an identifier for the installed version of
|
|
288
|
+
# `tesseract`:
|
|
289
|
+
#
|
|
290
|
+
# ```ruby
|
|
291
|
+
# module Shell
|
|
292
|
+
# class Tesseract < Command
|
|
293
|
+
# command_path `which tesseract`
|
|
294
|
+
# option_prefix "-"
|
|
295
|
+
# positional_parameters :first
|
|
296
|
+
#
|
|
297
|
+
# detect_version do
|
|
298
|
+
# exec_base("--version").on_success do |result|
|
|
299
|
+
# result.value =
|
|
300
|
+
# result.stdout
|
|
301
|
+
# .lines
|
|
302
|
+
# .first
|
|
303
|
+
# .split(" ")
|
|
304
|
+
# .last
|
|
305
|
+
# .first
|
|
306
|
+
# end
|
|
307
|
+
# end
|
|
308
|
+
# end
|
|
309
|
+
# end
|
|
310
|
+
# ```
|
|
311
|
+
#
|
|
312
|
+
# Your detector can return a `String`, a `Symbol` or `nil`. It can return them either
|
|
313
|
+
# directly or set on `Result#value`, which is what we are doing above.
|
|
314
|
+
#
|
|
315
|
+
# It's important to note that you cannot call `.exec` in your detector! `.exec` depends
|
|
316
|
+
# on the version being detected, so calling it from inside the detector leads to an
|
|
317
|
+
# infinite loop. Explicitely execute the command base class with `.exec_base` instead.
|
|
318
|
+
#
|
|
319
|
+
# Now we'll define a `version` which overrides the configuration of the `Shell::Tesseract`
|
|
320
|
+
# class when we have detected version 4 to be installed:
|
|
321
|
+
#
|
|
322
|
+
# ```ruby
|
|
323
|
+
# module Shell
|
|
324
|
+
# class Tesseract < Command
|
|
325
|
+
# command_path `which tesseract`
|
|
326
|
+
# option_prefix "-"
|
|
327
|
+
# positional_parameters :first
|
|
328
|
+
#
|
|
329
|
+
# detect_version do
|
|
330
|
+
# exec_base("--version").on_success do |result|
|
|
331
|
+
# result.value =
|
|
332
|
+
# result.stdout
|
|
333
|
+
# .lines
|
|
334
|
+
# .first
|
|
335
|
+
# .split(" ")
|
|
336
|
+
# .last
|
|
337
|
+
# .first
|
|
338
|
+
# end
|
|
339
|
+
# end
|
|
340
|
+
#
|
|
341
|
+
# version("4") do
|
|
342
|
+
# option_prefix :auto
|
|
343
|
+
# end
|
|
344
|
+
# end
|
|
345
|
+
# end
|
|
346
|
+
# ```
|
|
347
|
+
#
|
|
348
|
+
# Now whenever you call `.exec` for the first time, your version detector block is
|
|
349
|
+
# executed. If it returns "4", our alternate configuration is used; if it returns
|
|
350
|
+
# `nil` or a different version string, the base class is used instead.
|
|
351
|
+
#
|
|
352
|
+
# ### Timeouts
|
|
353
|
+
#
|
|
354
|
+
# Commands can be configured to abort execution after a specified time limit by passing
|
|
355
|
+
# a `timeout:` parameter to `.exec`. The timeout is specified in seconds and accepts both
|
|
356
|
+
# integers and floats.
|
|
357
|
+
#
|
|
358
|
+
# When a timeout occurs:
|
|
359
|
+
# 1. The process receives a SIGTERM signal (graceful termination)
|
|
360
|
+
# 2. After 0.5 seconds, a SIGKILL signal is sent if the process is still alive
|
|
361
|
+
# 3. A `Shell::Errors::CommandTimeout` exception is raised
|
|
362
|
+
#
|
|
363
|
+
# ```ruby
|
|
364
|
+
# module Shell
|
|
365
|
+
# class SlowCommand < Command
|
|
366
|
+
# command_path "/usr/bin/some_slow_command"
|
|
367
|
+
# end
|
|
368
|
+
# end
|
|
369
|
+
#
|
|
370
|
+
# # Execute with a 30 second timeout
|
|
371
|
+
# Shell::SlowCommand.exec("large_file.txt", timeout: 30)
|
|
372
|
+
# ```
|
|
373
|
+
#
|
|
374
|
+
# The timeout exception includes useful debugging information:
|
|
375
|
+
#
|
|
376
|
+
# ```ruby
|
|
377
|
+
# begin
|
|
378
|
+
# Shell::SlowCommand.exec("huge_file.txt", timeout: 10)
|
|
379
|
+
# rescue Shell::Errors::CommandTimeout => e
|
|
380
|
+
# puts "Command: #{e.command}" # Full command that was executed
|
|
381
|
+
# puts "Timeout: #{e.timeout_seconds}s" # Timeout limit in seconds
|
|
382
|
+
# puts "PID: #{e.pid}" # Process ID
|
|
383
|
+
# end
|
|
384
|
+
# ```
|
|
385
|
+
#
|
|
386
|
+
# Timeouts can be combined with other features like stdin/stdout redirection:
|
|
387
|
+
#
|
|
388
|
+
# ```ruby
|
|
389
|
+
# # Timeout with stdin data
|
|
390
|
+
# Shell::SomeCommand.exec(
|
|
391
|
+
# "input.txt",
|
|
392
|
+
# stdin: "data to process",
|
|
393
|
+
# timeout: 60
|
|
394
|
+
# )
|
|
395
|
+
#
|
|
396
|
+
# # Timeout with stdout redirection
|
|
397
|
+
# Shell::SomeCommand.exec(
|
|
398
|
+
# "input.txt",
|
|
399
|
+
# stdout: "/tmp/output.txt",
|
|
400
|
+
# timeout: 120
|
|
401
|
+
# )
|
|
402
|
+
# ```
|
|
403
|
+
#
|
|
404
|
+
# You can also wrap commands with custom timeout handling in your wrapper classes:
|
|
405
|
+
#
|
|
406
|
+
# ```ruby
|
|
407
|
+
# module Shell
|
|
408
|
+
# class ImageProcessor < Command
|
|
409
|
+
# command_path "/usr/bin/convert"
|
|
410
|
+
#
|
|
411
|
+
# def self.process_with_timeout(input_file, output_file, max_seconds: 300)
|
|
412
|
+
# exec(input_file, output_file, timeout: max_seconds)
|
|
413
|
+
# .raise_failures
|
|
414
|
+
# .on_success { |r| puts "Processing complete" }
|
|
415
|
+
# rescue Shell::Errors::CommandTimeout => e
|
|
416
|
+
# # Handle timeout gracefully
|
|
417
|
+
# Rails.logger.warn("Image processing timed out: #{e.message}")
|
|
418
|
+
# nil
|
|
419
|
+
# end
|
|
420
|
+
# end
|
|
421
|
+
# end
|
|
422
|
+
# ```
|
|
423
|
+
#
|
|
424
|
+
# For commands that should never hang, you can set a reasonable default timeout:
|
|
425
|
+
#
|
|
426
|
+
# ```ruby
|
|
427
|
+
# module Shell
|
|
428
|
+
# class NetworkCommand < Command
|
|
429
|
+
# command_path "/usr/bin/curl"
|
|
430
|
+
#
|
|
431
|
+
# def self.fetch_with_default_timeout(url, timeout: 30)
|
|
432
|
+
# exec(url, timeout: timeout)
|
|
433
|
+
# end
|
|
434
|
+
# end
|
|
435
|
+
# end
|
|
436
|
+
# ```
|
|
437
|
+
#
|
|
438
|
+
# ### Inheritance
|
|
439
|
+
#
|
|
440
|
+
# `Shell::Command` classes inherit their parents configuration:
|
|
441
|
+
#
|
|
442
|
+
# ```ruby
|
|
443
|
+
# module Shell
|
|
444
|
+
# class Pgrep < Command
|
|
445
|
+
# command_path "/usr/bin/pgrep"
|
|
446
|
+
# positional_parameters :first
|
|
447
|
+
# end
|
|
448
|
+
#
|
|
449
|
+
# class Pgrep2 < Pgrep
|
|
450
|
+
# end
|
|
451
|
+
# end
|
|
452
|
+
#
|
|
453
|
+
# Shell::Pgrep2.exec "rails", foo: 1, x: 2
|
|
454
|
+
# # => Command: /usr/bin/pgrep rails --foo=1 -x 2
|
|
455
|
+
# ```
|
|
456
|
+
class Command
|
|
457
|
+
extend OptionalDependencies
|
|
458
|
+
|
|
459
|
+
# How long a child process which is being terminated gets to exit after SIGTERM,
|
|
460
|
+
# before it is sent SIGKILL
|
|
461
|
+
#
|
|
462
|
+
# @return [Float] seconds
|
|
463
|
+
TERMINATION_GRACE_PERIOD = 0.5
|
|
464
|
+
|
|
465
|
+
# The `Result` class is the return value you receive from a successful or unsuccessful
|
|
466
|
+
# command execution. It provides you with `#stdout`, `#stderr` and the {Process::Status}
|
|
467
|
+
# at `#status`. Its `#value` attribute can be set with custom return data by the executed
|
|
468
|
+
# command.
|
|
469
|
+
#
|
|
470
|
+
# It also provides some chainable block helpers for convenience:
|
|
471
|
+
#
|
|
472
|
+
# ```ruby
|
|
473
|
+
# result = Shell::SomeCommand.exec
|
|
474
|
+
#
|
|
475
|
+
# result.on_success { |result| puts "Success: #{result.value}" }
|
|
476
|
+
# .on_failure { |result| puts "Failure: #{result.stderr}" }
|
|
477
|
+
# ```
|
|
478
|
+
#
|
|
479
|
+
# If you prefer unsuccessful commands to raise an exception, use `#raise_failures`:
|
|
480
|
+
#
|
|
481
|
+
# ```ruby
|
|
482
|
+
# Shell::SomeCommand.exec
|
|
483
|
+
# .raise_failures
|
|
484
|
+
# .on_success { |result| puts "Success: #{result.value}" }
|
|
485
|
+
# ```
|
|
486
|
+
class Result
|
|
487
|
+
attr_reader :command_path
|
|
488
|
+
attr_reader :command_options
|
|
489
|
+
attr_reader :stdout
|
|
490
|
+
attr_reader :stdout_path
|
|
491
|
+
attr_reader :stdout_size
|
|
492
|
+
attr_reader :stderr
|
|
493
|
+
attr_accessor :value
|
|
494
|
+
|
|
495
|
+
# The exception raised while turning the command's output into {#value}
|
|
496
|
+
#
|
|
497
|
+
# The command itself may have exited cleanly; if its output could not be
|
|
498
|
+
# processed, the result is a {#failure?} all the same.
|
|
499
|
+
#
|
|
500
|
+
# @return [Exception, nil]
|
|
501
|
+
attr_accessor :post_processing_failure
|
|
502
|
+
|
|
503
|
+
# @param path [String]
|
|
504
|
+
# @param args [Array<String>]
|
|
505
|
+
# @param stdout [String] the contents of STDOUT
|
|
506
|
+
# @param stdout_path [String] the path to the file STDOUT was redirected to; alternative to `:stdout`
|
|
507
|
+
# @param stderr [String]
|
|
508
|
+
# @param status [Process::Status]
|
|
509
|
+
def initialize(path:, args:, stderr:, status:, stdout: nil, stdout_path: nil)
|
|
510
|
+
@command_path = path
|
|
511
|
+
@command_options = args
|
|
512
|
+
@stdout = stdout
|
|
513
|
+
@stdout_path = stdout_path
|
|
514
|
+
@stderr = stderr
|
|
515
|
+
@status = status
|
|
516
|
+
@ignored_exit_codes = []
|
|
517
|
+
|
|
518
|
+
@stdout_size =
|
|
519
|
+
if stdout_path
|
|
520
|
+
::File.readable?(stdout_path) ? ::File.size(stdout_path) : "?"
|
|
521
|
+
else
|
|
522
|
+
stdout ? stdout.size : 0
|
|
523
|
+
end
|
|
524
|
+
end
|
|
525
|
+
|
|
526
|
+
# The full command that was executed
|
|
527
|
+
#
|
|
528
|
+
# @return [String]
|
|
529
|
+
def command
|
|
530
|
+
([command_path] + command_options).join(" ")
|
|
531
|
+
end
|
|
532
|
+
|
|
533
|
+
# The commands exit status code
|
|
534
|
+
#
|
|
535
|
+
# @return [Integer]
|
|
536
|
+
def status
|
|
537
|
+
@status.exitstatus
|
|
538
|
+
end
|
|
539
|
+
|
|
540
|
+
# Was the command executed successfully?
|
|
541
|
+
#
|
|
542
|
+
# @return [Boolean]
|
|
543
|
+
def success?
|
|
544
|
+
return false if post_processing_failure
|
|
545
|
+
|
|
546
|
+
@status.success? || @ignored_exit_codes.include?(status)
|
|
547
|
+
end
|
|
548
|
+
|
|
549
|
+
# Was the command executed unsuccessfully?
|
|
550
|
+
#
|
|
551
|
+
# @return [Boolean]
|
|
552
|
+
def failure?
|
|
553
|
+
!success?
|
|
554
|
+
end
|
|
555
|
+
|
|
556
|
+
# Mark one or more non-zero exit codes as "successful"
|
|
557
|
+
#
|
|
558
|
+
# These exit codes will not mark the result as {#failed?}
|
|
559
|
+
# or raise `Shell::Errors::CommandUnsuccessful`.
|
|
560
|
+
#
|
|
561
|
+
# @param code_or_codes [Integer, Array<Integer>]
|
|
562
|
+
# @return [self]
|
|
563
|
+
def consider_successful(code_or_codes)
|
|
564
|
+
@ignored_exit_codes.push(*code_or_codes)
|
|
565
|
+
|
|
566
|
+
self
|
|
567
|
+
end
|
|
568
|
+
|
|
569
|
+
# Execute the given block if the command was successful
|
|
570
|
+
#
|
|
571
|
+
# @yield [self]
|
|
572
|
+
# @return [self]
|
|
573
|
+
def on_success
|
|
574
|
+
yield self if success?
|
|
575
|
+
|
|
576
|
+
self
|
|
577
|
+
end
|
|
578
|
+
|
|
579
|
+
# Execute the given block on successful execution with exception handling
|
|
580
|
+
#
|
|
581
|
+
# Unlike {#on_success}, an exception raised by the block does not escape:
|
|
582
|
+
# it marks the result as a {#failure?} and becomes its `#value`.
|
|
583
|
+
#
|
|
584
|
+
# @yield [self]
|
|
585
|
+
# @return [self]
|
|
586
|
+
def post_process
|
|
587
|
+
yield self if success?
|
|
588
|
+
|
|
589
|
+
self
|
|
590
|
+
rescue StandardError => e
|
|
591
|
+
self.post_processing_failure = e
|
|
592
|
+
self.value = e
|
|
593
|
+
|
|
594
|
+
self
|
|
595
|
+
end
|
|
596
|
+
|
|
597
|
+
# Execute the given block if the command was unsuccessful
|
|
598
|
+
#
|
|
599
|
+
# @yield [self]
|
|
600
|
+
# @return [self]
|
|
601
|
+
def on_failure
|
|
602
|
+
yield self if failure?
|
|
603
|
+
|
|
604
|
+
self
|
|
605
|
+
end
|
|
606
|
+
|
|
607
|
+
# Information returned from the command about an error situation
|
|
608
|
+
#
|
|
609
|
+
# Usually, but not always STDERR. Can be overloaded by `Result`
|
|
610
|
+
# subclasses.
|
|
611
|
+
#
|
|
612
|
+
# @return [String]
|
|
613
|
+
def error_output
|
|
614
|
+
post_processing_failure ? post_processing_failure.message : stderr
|
|
615
|
+
end
|
|
616
|
+
|
|
617
|
+
# Raise a `Shell::Errors::CommandUnsuccessful` exception if the
|
|
618
|
+
# command was unsuccessful
|
|
619
|
+
#
|
|
620
|
+
# If the failure was in post-processing the command's output, the
|
|
621
|
+
# exception raised there is the error's `#cause`.
|
|
622
|
+
#
|
|
623
|
+
# @raise [Shell::Errors::CommandUnsuccessful]
|
|
624
|
+
# @return [self]
|
|
625
|
+
def raise_failures
|
|
626
|
+
if failure?
|
|
627
|
+
raise Shell::Errors::CommandUnsuccessful.new(inspect), cause: post_processing_failure
|
|
628
|
+
end
|
|
629
|
+
|
|
630
|
+
self
|
|
631
|
+
end
|
|
632
|
+
|
|
633
|
+
def inspect
|
|
634
|
+
stdout_formatted =
|
|
635
|
+
stdout_path ? "<file: #{stdout_path}> #{stdout_size} Bytes" : "#{stdout_size} Bytes"
|
|
636
|
+
|
|
637
|
+
<<~EOT
|
|
638
|
+
Command: #{command}
|
|
639
|
+
PID: #{@status.pid}
|
|
640
|
+
Status: #{status} (#{ success? ? 'successful' : 'failure' })
|
|
641
|
+
Stdout: #{stdout_formatted}
|
|
642
|
+
Stderr: #{ (stderr.lines[0]&.chomp || '') + "... (#{stderr.size} Bytes)" if failure?}
|
|
643
|
+
#{"Post-processing failed: #{post_processing_failure.class}: #{post_processing_failure.message}" if post_processing_failure}
|
|
644
|
+
EOT
|
|
645
|
+
end
|
|
646
|
+
end
|
|
647
|
+
|
|
648
|
+
class << self
|
|
649
|
+
# @return [Symbol] whether positional parameters `:first`
|
|
650
|
+
# (before the options) or `:last` (after the options)
|
|
651
|
+
attr_reader :positional_parameters_position
|
|
652
|
+
|
|
653
|
+
# Get or set the path to the commands binary
|
|
654
|
+
#
|
|
655
|
+
# @param value [String, Pathname]
|
|
656
|
+
# @return [Pathname]
|
|
657
|
+
def command_path(value = nil)
|
|
658
|
+
if value
|
|
659
|
+
@command_path = Pathname.new(value.chomp.strip).freeze
|
|
660
|
+
else
|
|
661
|
+
@command_path
|
|
662
|
+
end
|
|
663
|
+
end
|
|
664
|
+
|
|
665
|
+
# Get or set the prefix used by the command for
|
|
666
|
+
# command options ("--" or "-"). Set to `:auto` to use
|
|
667
|
+
# "-" for single-character flags and "--" for longer ones.
|
|
668
|
+
#
|
|
669
|
+
# Subclasses default to :auto.
|
|
670
|
+
#
|
|
671
|
+
# @param value [String]
|
|
672
|
+
# @return [Pathname]
|
|
673
|
+
def option_prefix(value = nil)
|
|
674
|
+
if value
|
|
675
|
+
@option_prefix = value.freeze
|
|
676
|
+
else
|
|
677
|
+
@option_prefix
|
|
678
|
+
end
|
|
679
|
+
end
|
|
680
|
+
|
|
681
|
+
# Get or set whether positional parameters come `:first`
|
|
682
|
+
# (before the options) or `:last` (after the options).
|
|
683
|
+
#
|
|
684
|
+
# Subclasses default to :last.
|
|
685
|
+
#
|
|
686
|
+
# @example
|
|
687
|
+
# ```
|
|
688
|
+
# # Positional parameters last
|
|
689
|
+
# some_command --foo -l example.txt
|
|
690
|
+
#
|
|
691
|
+
# # Positional parameters first
|
|
692
|
+
# some_command example.txt --foo -l
|
|
693
|
+
# ```
|
|
694
|
+
#
|
|
695
|
+
# @param value [Symbol, nil] `:first` or `:last`. `:last` if not set.
|
|
696
|
+
# @return [Symbol, nil]
|
|
697
|
+
def positional_parameters(value = nil)
|
|
698
|
+
if value
|
|
699
|
+
@positional_parameters_position = value.freeze
|
|
700
|
+
else
|
|
701
|
+
@positional_parameters_position
|
|
702
|
+
end
|
|
703
|
+
end
|
|
704
|
+
|
|
705
|
+
# Get or set a transformation table for option names
|
|
706
|
+
#
|
|
707
|
+
# Set the Hash in the format
|
|
708
|
+
# `<Ruby keyword argument name> => <Command line option name>`
|
|
709
|
+
#
|
|
710
|
+
# As a replacement, provide a `Symbol` for simple renamings; your
|
|
711
|
+
# classes prefixing and value separation settings will be
|
|
712
|
+
# automatically applied.
|
|
713
|
+
#
|
|
714
|
+
# Provide `String` replacements for more control; these must contain
|
|
715
|
+
# the prefix as well.
|
|
716
|
+
#
|
|
717
|
+
# @example
|
|
718
|
+
# ```ruby
|
|
719
|
+
# class SomeCommand < Command
|
|
720
|
+
# command_path `which some_command`
|
|
721
|
+
# # `option_prefix` is set to its default of :auto
|
|
722
|
+
#
|
|
723
|
+
# transform_options {
|
|
724
|
+
# foo: :dFoo,
|
|
725
|
+
# bar: "!bar"
|
|
726
|
+
# }
|
|
727
|
+
# end
|
|
728
|
+
#
|
|
729
|
+
# SomeCommand.exec(foo: "one", bar: "two")
|
|
730
|
+
# .command
|
|
731
|
+
# # => "some_command --dFoo=one !bar=two"
|
|
732
|
+
#
|
|
733
|
+
# @param value [String]
|
|
734
|
+
# @return [Pathname]
|
|
735
|
+
def transform_options(**kargs)
|
|
736
|
+
if kargs.any?
|
|
737
|
+
@transform_options = kargs.freeze
|
|
738
|
+
else
|
|
739
|
+
@transform_options
|
|
740
|
+
end
|
|
741
|
+
end
|
|
742
|
+
|
|
743
|
+
# Get or set the state for `dasherize_options`
|
|
744
|
+
#
|
|
745
|
+
# When `true`, underscores in option names will be
|
|
746
|
+
# converted into dashes, e.g. `:some_option` => `--some-option`.
|
|
747
|
+
#
|
|
748
|
+
# @param value [Boolean, nil]
|
|
749
|
+
# @return [Boolean, nil]
|
|
750
|
+
def dasherize_options(value = nil)
|
|
751
|
+
if value.nil?
|
|
752
|
+
@dasherize_options
|
|
753
|
+
else
|
|
754
|
+
@dasherize_options = value
|
|
755
|
+
end
|
|
756
|
+
end
|
|
757
|
+
|
|
758
|
+
# Dynamically generated subclasses configured with the
|
|
759
|
+
# `version("identifier") {}` macro, indexed by name
|
|
760
|
+
#
|
|
761
|
+
# @return [Hash{Symbol,String=>Class}]
|
|
762
|
+
def versions
|
|
763
|
+
@versions || {}
|
|
764
|
+
end
|
|
765
|
+
|
|
766
|
+
# Macro for providing a version detector block
|
|
767
|
+
#
|
|
768
|
+
# The return value of your block decides which version
|
|
769
|
+
# configuration is used. If your block returns `nil` or
|
|
770
|
+
# an unknown identifier, the base class is used instead.
|
|
771
|
+
#
|
|
772
|
+
# @example
|
|
773
|
+
# ```ruby
|
|
774
|
+
# class SomeCommand < Command
|
|
775
|
+
# detect_version do
|
|
776
|
+
# "4"
|
|
777
|
+
# end
|
|
778
|
+
#
|
|
779
|
+
# version("4") do
|
|
780
|
+
# end
|
|
781
|
+
# end
|
|
782
|
+
# ```
|
|
783
|
+
#
|
|
784
|
+
# One important note: do not call `.exec` inside your
|
|
785
|
+
# detector block, as that leads to an infinite loop. Execute
|
|
786
|
+
# the base class command with `.exec_base` instead.
|
|
787
|
+
#
|
|
788
|
+
# @yieldreturn [String,Symbol,nil] an identifier as defined by a
|
|
789
|
+
# `version(:identifier) {}` macro, or `nil` to use the base class
|
|
790
|
+
# @return [void]
|
|
791
|
+
def detect_version(&block)
|
|
792
|
+
if block_given?
|
|
793
|
+
@version_detector = block
|
|
794
|
+
else
|
|
795
|
+
instance_eval(&@version_detector) if @version_detector
|
|
796
|
+
end
|
|
797
|
+
end
|
|
798
|
+
|
|
799
|
+
# An identifier for the version of the command that is
|
|
800
|
+
# installed. Only available if the command supports versions.
|
|
801
|
+
#
|
|
802
|
+
# @return [String, nil]
|
|
803
|
+
def detected_version
|
|
804
|
+
@detected_version ||= begin
|
|
805
|
+
result = detect_version
|
|
806
|
+
|
|
807
|
+
result.is_a?(Result) ? result.value : result
|
|
808
|
+
end
|
|
809
|
+
end
|
|
810
|
+
|
|
811
|
+
# DSL macro for defining a version of this command
|
|
812
|
+
#
|
|
813
|
+
# This creates a subclass of the current command class; your
|
|
814
|
+
# block is executed in the scope of that subclass.
|
|
815
|
+
#
|
|
816
|
+
# The subclass inherits all settings from its parent. You can
|
|
817
|
+
# then override them as required.
|
|
818
|
+
#
|
|
819
|
+
# @example
|
|
820
|
+
# ```ruby
|
|
821
|
+
# class SomeCommand < Command
|
|
822
|
+
# command_path "/usr/bin/some_command"
|
|
823
|
+
#
|
|
824
|
+
# detect_version do
|
|
825
|
+
# exec_base("--version").stdout
|
|
826
|
+
# .split(".")
|
|
827
|
+
# .first
|
|
828
|
+
# end
|
|
829
|
+
#
|
|
830
|
+
# version("4") do
|
|
831
|
+
# command_path "/usr/bin/some_command4"
|
|
832
|
+
# end
|
|
833
|
+
# end
|
|
834
|
+
# ```
|
|
835
|
+
#
|
|
836
|
+
# @param identifier [String, Symbol]
|
|
837
|
+
# @yield
|
|
838
|
+
# @return [void]
|
|
839
|
+
def version(identifier, &block)
|
|
840
|
+
@versions[identifier] = Class.new(self, &block)
|
|
841
|
+
end
|
|
842
|
+
|
|
843
|
+
# We give our `Command` subclasses the default values of the parent class
|
|
844
|
+
def inherited(subclass)
|
|
845
|
+
super
|
|
846
|
+
|
|
847
|
+
subclass.instance_variable_set(:@command_path, command_path.dup)
|
|
848
|
+
subclass.instance_variable_set(:@option_prefix, option_prefix.dup)
|
|
849
|
+
subclass.instance_variable_set(:@dasherize_options, dasherize_options.dup)
|
|
850
|
+
subclass.instance_variable_set(:@transform_options, transform_options.dup)
|
|
851
|
+
subclass.instance_variable_set(:@positional_parameters_position, positional_parameters_position.dup)
|
|
852
|
+
subclass.instance_variable_set(:@version_detector, @version_detector.dup)
|
|
853
|
+
subclass.instance_variable_set(:@versions, versions.dup)
|
|
854
|
+
end
|
|
855
|
+
end
|
|
856
|
+
|
|
857
|
+
# Prefix single-character flags with a "-" and longer options with "--" by default,
|
|
858
|
+
# ie `some_command -f --option`
|
|
859
|
+
option_prefix :auto
|
|
860
|
+
# Convert underscores in options to dashes by default, e.g.
|
|
861
|
+
# `:some_option` => `--some-option`
|
|
862
|
+
dasherize_options true
|
|
863
|
+
# Positional parameters come as last arguments, after the options by default
|
|
864
|
+
positional_parameters :last
|
|
865
|
+
|
|
866
|
+
def self.versioned_new
|
|
867
|
+
(versions[detected_version] || self).new
|
|
868
|
+
end
|
|
869
|
+
|
|
870
|
+
# Execute the command
|
|
871
|
+
#
|
|
872
|
+
# If the subclass has support for multiple versions configured,
|
|
873
|
+
# the installed version will be detected first and the appropriate
|
|
874
|
+
# configuration initialised.
|
|
875
|
+
#
|
|
876
|
+
# @see {#exec}
|
|
877
|
+
def self.exec(*args, **kargs, &block)
|
|
878
|
+
versioned_new.exec(*args, **kargs, &block)
|
|
879
|
+
end
|
|
880
|
+
|
|
881
|
+
# Execute the command through the base configuration, without
|
|
882
|
+
# performing version detection
|
|
883
|
+
#
|
|
884
|
+
# @see {#exec}
|
|
885
|
+
def self.exec_base(*args, **kargs, &block)
|
|
886
|
+
new.exec(*args, **kargs, &block)
|
|
887
|
+
end
|
|
888
|
+
|
|
889
|
+
# Execute the command
|
|
890
|
+
#
|
|
891
|
+
# In general, give keyword arguments for command options or flags and
|
|
892
|
+
# arguments for positional arguments.
|
|
893
|
+
#
|
|
894
|
+
# @example
|
|
895
|
+
# ```ruby
|
|
896
|
+
# Shell::SomeCommand.exec("example.txt", "other_file.txt", foo: :bar)
|
|
897
|
+
# .command
|
|
898
|
+
# # => "some_command --foo bar example.txt other_file.txt"
|
|
899
|
+
# ```
|
|
900
|
+
#
|
|
901
|
+
# Option flags can be set through keyword arguments with `nil` values:
|
|
902
|
+
#
|
|
903
|
+
# @example
|
|
904
|
+
# ```ruby
|
|
905
|
+
# Shell::SomeCommand.exec("example.txt", foo: nil)
|
|
906
|
+
# .command
|
|
907
|
+
# # => "some_command --foo example.txt"
|
|
908
|
+
# ```
|
|
909
|
+
#
|
|
910
|
+
# For convenience, arguments passed as `Symbol` are treated as flags
|
|
911
|
+
# as well:
|
|
912
|
+
#
|
|
913
|
+
# @example
|
|
914
|
+
# ```ruby
|
|
915
|
+
# Shell::SomeCommand.exec("example.txt", :foo)
|
|
916
|
+
# .command
|
|
917
|
+
# # => "some_command --foo example.txt"
|
|
918
|
+
# ```
|
|
919
|
+
#
|
|
920
|
+
# `Fs::File` objects can also be passed directly as arguments:
|
|
921
|
+
#
|
|
922
|
+
# @example
|
|
923
|
+
# ```ruby
|
|
924
|
+
# upload = Fs::Files::UserUpload.new(path: "/some/file.pdf")
|
|
925
|
+
# Shell::SomeCommand.exec(upload, :foo)
|
|
926
|
+
# ```
|
|
927
|
+
#
|
|
928
|
+
# If you need to pass the same option multiple times and thus cannot
|
|
929
|
+
# use keyword arguments, pass a nested array instead:
|
|
930
|
+
#
|
|
931
|
+
# @example
|
|
932
|
+
# ```ruby
|
|
933
|
+
# Shell::SomeCommand.exec("example.txt", [[:foo, "first_value"], [:foo, "second_value"]])
|
|
934
|
+
# .command
|
|
935
|
+
# # => "some_command --foo first_value --foo second_value example.txt"
|
|
936
|
+
# ```
|
|
937
|
+
#
|
|
938
|
+
# @param stdin [String, IO, nil] if given, defines the STDIN input for the command
|
|
939
|
+
# @param stdout [String, #path, nil] if given, redirects STDOUT to this file path
|
|
940
|
+
# @param timeout [Numeric, nil] if given, the command will be terminated after this many seconds
|
|
941
|
+
# @param chdir [String, #to_path, nil] if given, the command runs in this working directory.
|
|
942
|
+
# Only the child process changes directory, unlike `Dir.chdir`, which is global to the
|
|
943
|
+
# process and raises when another thread is inside a `Dir.chdir` block.
|
|
944
|
+
# @return [Shell::Command::Result]
|
|
945
|
+
def exec(*args, stdin: nil, stdout: nil, timeout: nil, chdir: nil, **kargs)
|
|
946
|
+
execute(*args, stdin: stdin, stdout: stdout, timeout: timeout, chdir: chdir, **kargs)
|
|
947
|
+
end
|
|
948
|
+
|
|
949
|
+
private
|
|
950
|
+
|
|
951
|
+
# @see Command.command_path
|
|
952
|
+
# @return [Pathname]
|
|
953
|
+
def command_path
|
|
954
|
+
self.class.command_path.to_s
|
|
955
|
+
end
|
|
956
|
+
|
|
957
|
+
# @see Command.option_prefix
|
|
958
|
+
# @return [String]
|
|
959
|
+
def option_prefix
|
|
960
|
+
self.class.option_prefix
|
|
961
|
+
end
|
|
962
|
+
|
|
963
|
+
# @see Command.dasherize_options
|
|
964
|
+
# @return [Boolean]
|
|
965
|
+
def dasherize_options
|
|
966
|
+
self.class.dasherize_options
|
|
967
|
+
end
|
|
968
|
+
|
|
969
|
+
# @see Command.positional_parameters_position
|
|
970
|
+
# @return [Symbol]
|
|
971
|
+
def positional_parameters_position
|
|
972
|
+
self.class.positional_parameters_position
|
|
973
|
+
end
|
|
974
|
+
|
|
975
|
+
# @see Command.transform_options
|
|
976
|
+
# @return [Hash{Symbol=>Symbol,String}]
|
|
977
|
+
def transform_options
|
|
978
|
+
self.class.transform_options || {}
|
|
979
|
+
end
|
|
980
|
+
|
|
981
|
+
# @see #exec
|
|
982
|
+
def execute(*args, stdin: nil, stdout: nil, timeout: nil, chdir: nil, **kargs)
|
|
983
|
+
command_arguments = build_command_arguments(*args, **kargs)
|
|
984
|
+
|
|
985
|
+
# We always capture STDERR; the others we only create as needed.
|
|
986
|
+
stderr_pipe_read, stderr_pipe_write = IO.pipe
|
|
987
|
+
stdout_pipe_read = nil
|
|
988
|
+
stdout_pipe_write = nil
|
|
989
|
+
stdout_path = nil
|
|
990
|
+
stdin_pipe_read = nil
|
|
991
|
+
stdin_pipe_write = nil
|
|
992
|
+
|
|
993
|
+
spawn_options = {
|
|
994
|
+
err: stderr_pipe_write
|
|
995
|
+
}
|
|
996
|
+
spawn_options[:chdir] = chdir.respond_to?(:to_path) ? chdir.to_path : chdir.to_s if chdir
|
|
997
|
+
|
|
998
|
+
if stdout
|
|
999
|
+
# Redirect stdout to file
|
|
1000
|
+
stdout_path = stdout.respond_to?(:path) ? stdout.path.to_s : stdout.to_s
|
|
1001
|
+
spawn_options[:out] = stdout_path
|
|
1002
|
+
|
|
1003
|
+
else
|
|
1004
|
+
# Capture stdout content ourselves with a pipe
|
|
1005
|
+
stdout_pipe_read, stdout_pipe_write = IO.pipe
|
|
1006
|
+
spawn_options[:out] = stdout_pipe_write
|
|
1007
|
+
end
|
|
1008
|
+
|
|
1009
|
+
if stdin
|
|
1010
|
+
if stdin.respond_to?(:read)
|
|
1011
|
+
# IO objects can be passed directly
|
|
1012
|
+
spawn_options[:in] = stdin
|
|
1013
|
+
|
|
1014
|
+
else
|
|
1015
|
+
# Strings we pass through a pipe manually
|
|
1016
|
+
stdin_pipe_read, stdin_pipe_write = IO.pipe
|
|
1017
|
+
spawn_options[:in] = stdin_pipe_read
|
|
1018
|
+
end
|
|
1019
|
+
end
|
|
1020
|
+
|
|
1021
|
+
# At this point, we have up to three pipes: for STDIN, we supply the input
|
|
1022
|
+
# INTO the spawned command, so it gets the read end. For STDOUT and STDERR,
|
|
1023
|
+
# we receive the input FROM the spawned command, so it gets the write end.
|
|
1024
|
+
|
|
1025
|
+
# Spawn the process
|
|
1026
|
+
pid = spawn_child(command_arguments, spawn_options)
|
|
1027
|
+
|
|
1028
|
+
# From here on the child is ours to clean up: if we are being asked to terminate
|
|
1029
|
+
# while it still runs, the `ensure` below terminates it as well instead of leaving
|
|
1030
|
+
# it behind.
|
|
1031
|
+
reaped = false
|
|
1032
|
+
timed_out = false
|
|
1033
|
+
stdout_reader_thread = nil
|
|
1034
|
+
stderr_reader_thread = nil
|
|
1035
|
+
|
|
1036
|
+
begin
|
|
1037
|
+
# Immediately clean up our own pipe references to pipe ends we do not use ourselves;
|
|
1038
|
+
# the spawned child process which actually does use them now has its own references.
|
|
1039
|
+
stdin_pipe_read&.close
|
|
1040
|
+
stdout_pipe_write&.close
|
|
1041
|
+
stderr_pipe_write.close
|
|
1042
|
+
|
|
1043
|
+
if stdin_pipe_write
|
|
1044
|
+
stdin_pipe_write.write(stdin)
|
|
1045
|
+
stdin_pipe_write.close
|
|
1046
|
+
end
|
|
1047
|
+
|
|
1048
|
+
# Start reader threads BEFORE waiting for the process
|
|
1049
|
+
# ---------------------------------------------------
|
|
1050
|
+
#
|
|
1051
|
+
# Why do we need threads here?
|
|
1052
|
+
#
|
|
1053
|
+
# Pipes have a limited buffer size (typically 64KB on macOS/Linux). When a child
|
|
1054
|
+
# process writes to stdout/stderr and the buffer fills up, the child BLOCKS until
|
|
1055
|
+
# the parent reads from the pipe to make room.
|
|
1056
|
+
#
|
|
1057
|
+
# Our prior version worked like this:
|
|
1058
|
+
#
|
|
1059
|
+
# 1. spawn child process
|
|
1060
|
+
# 2. wait for child to exit (Process.wait)
|
|
1061
|
+
# 3. read from pipes
|
|
1062
|
+
#
|
|
1063
|
+
# This caused a deadlock when the child's output exceeded the pipe buffer -
|
|
1064
|
+
# child blocks on write (waiting for parent to read), parent blocks on wait
|
|
1065
|
+
# (waiting for child to exit).
|
|
1066
|
+
#
|
|
1067
|
+
# The solution is reading from pipes concurrently with waiting for the process.
|
|
1068
|
+
# We spawn threads that continuously read from the pipes, preventing the buffer
|
|
1069
|
+
# from filling up. The main thread can then safely wait for the process.
|
|
1070
|
+
#
|
|
1071
|
+
# Ruby's Global VM Lock (GVL) is released during I/O operations, so when a thread
|
|
1072
|
+
# calls `pipe.read` and blocks waiting for data, other threads (including the
|
|
1073
|
+
# main thread) can run. This makes threads suitable for concurrent I/O.
|
|
1074
|
+
#
|
|
1075
|
+
# Thread lifecycle:
|
|
1076
|
+
#
|
|
1077
|
+
# 1. thread starts and immediately calls `pipe.read`
|
|
1078
|
+
# 2. thread blocks until ALL data is available (child closes its pipe end)
|
|
1079
|
+
# 3. when child exits, it closes its pipe ends automatically
|
|
1080
|
+
# 4. `read` returns with all the data, thread finishes
|
|
1081
|
+
# 5. main thread calls `thread.value` to get the result
|
|
1082
|
+
|
|
1083
|
+
# Start a thread to read stdout (if we're capturing it, not redirecting to file)
|
|
1084
|
+
# The thread will block on `read` until the child process closes its stdout,
|
|
1085
|
+
# which happens automatically when the child exits.
|
|
1086
|
+
stdout_reader_thread =
|
|
1087
|
+
if stdout_pipe_read
|
|
1088
|
+
Thread.new { stdout_pipe_read.read }
|
|
1089
|
+
end
|
|
1090
|
+
|
|
1091
|
+
# Start a thread to read stderr (we always capture stderr)
|
|
1092
|
+
stderr_reader_thread = Thread.new { stderr_pipe_read.read }
|
|
1093
|
+
|
|
1094
|
+
# While we wait here, the reader threads are draining the pipes in the background,
|
|
1095
|
+
# preventing the pipe buffer deadlock.
|
|
1096
|
+
|
|
1097
|
+
timed_out = wait_for_child(pid, timeout)
|
|
1098
|
+
reaped = true
|
|
1099
|
+
|
|
1100
|
+
ensure
|
|
1101
|
+
# Reaching this point without having reaped the child means we are being asked to
|
|
1102
|
+
# terminate while it is still running: the calling thread was killed or had an exception
|
|
1103
|
+
# raised into it, or the process is exiting. Left alone, the child would carry
|
|
1104
|
+
# on as an orphan, with nobody to read its output or to wait for it.
|
|
1105
|
+
unless reaped
|
|
1106
|
+
terminate_child(pid)
|
|
1107
|
+
release_output_readers(stdout_reader_thread, stderr_reader_thread, stdout_pipe_read, stderr_pipe_read)
|
|
1108
|
+
end
|
|
1109
|
+
end
|
|
1110
|
+
|
|
1111
|
+
if timed_out
|
|
1112
|
+
# The child was terminated for exceeding its timeout, and reaped
|
|
1113
|
+
release_output_readers(stdout_reader_thread, stderr_reader_thread, stdout_pipe_read, stderr_pipe_read)
|
|
1114
|
+
|
|
1115
|
+
raise Shell::Errors::CommandTimeout.new(
|
|
1116
|
+
command: ([command_path] + command_arguments).join(" "),
|
|
1117
|
+
timeout: timeout,
|
|
1118
|
+
pid: pid
|
|
1119
|
+
)
|
|
1120
|
+
end
|
|
1121
|
+
|
|
1122
|
+
# Collect results from reader threads
|
|
1123
|
+
#
|
|
1124
|
+
# Thread#value does two things:
|
|
1125
|
+
#
|
|
1126
|
+
# 1. it waits for the thread to finish, like `join` would
|
|
1127
|
+
# 2. it returns the result of the thread block - here, the pipe contents
|
|
1128
|
+
#
|
|
1129
|
+
# If an exception occurred in a thread, `value` will re-raise it here in the
|
|
1130
|
+
# main thread, which is good.
|
|
1131
|
+
#
|
|
1132
|
+
# At this point, the child has exited, so the threads should complete immediately
|
|
1133
|
+
# (or already have completed while we were waiting for the process).
|
|
1134
|
+
|
|
1135
|
+
stdout_content = stdout_reader_thread&.value
|
|
1136
|
+
stderr_content = stderr_reader_thread.value
|
|
1137
|
+
|
|
1138
|
+
# Now that the threads are done reading, we close our pipe ends
|
|
1139
|
+
stdout_pipe_read&.close
|
|
1140
|
+
stderr_pipe_read.close
|
|
1141
|
+
|
|
1142
|
+
# We guide the constant lookup a little with `self.class::Result`, to allow
|
|
1143
|
+
# command subclasses to provide their own `Result` subclass.
|
|
1144
|
+
# See `Shell::File` for an example.
|
|
1145
|
+
self.class::Result.new(
|
|
1146
|
+
path: command_path,
|
|
1147
|
+
args: command_arguments,
|
|
1148
|
+
stderr: stderr_content,
|
|
1149
|
+
status: $?,
|
|
1150
|
+
stdout: stdout_content,
|
|
1151
|
+
stdout_path: stdout_path
|
|
1152
|
+
)
|
|
1153
|
+
rescue IOError, SystemCallError
|
|
1154
|
+
raise Shell::Errors::ExecutionError
|
|
1155
|
+
end
|
|
1156
|
+
|
|
1157
|
+
# Starts the command as a child process
|
|
1158
|
+
#
|
|
1159
|
+
# @param arguments [Array<String>]
|
|
1160
|
+
# @param options [Hash] options for `Kernel.spawn`
|
|
1161
|
+
# @raise [Shell::Errors::CommandNotFound] if the program itself is missing
|
|
1162
|
+
# @return [Integer] the PID of the child
|
|
1163
|
+
def spawn_child(arguments, options)
|
|
1164
|
+
Kernel.spawn(command_path, *arguments, options)
|
|
1165
|
+
rescue Errno::ENOENT
|
|
1166
|
+
# ENOENT is also raised for a missing file we redirect to, so only blame the program
|
|
1167
|
+
# if it really is missing; a bare name is left to the PATH lookup `spawn` did.
|
|
1168
|
+
raise unless command_path.empty? || (command_path.include?("/") && !::File.exist?(command_path))
|
|
1169
|
+
|
|
1170
|
+
raise Shell::Errors::CommandNotFound.new(command_class: self.class, path: command_path)
|
|
1171
|
+
end
|
|
1172
|
+
|
|
1173
|
+
# Transforms arguments and keyword arguments into a correctly ordered
|
|
1174
|
+
# sequence of options, flags and positional command arguments
|
|
1175
|
+
#
|
|
1176
|
+
# @param args [Array]
|
|
1177
|
+
# @param kargs [Hash]
|
|
1178
|
+
# @return [Array<String>]
|
|
1179
|
+
def build_command_arguments(*args, **kargs)
|
|
1180
|
+
positional_args, options =
|
|
1181
|
+
preprocess_arguments(args, kargs)
|
|
1182
|
+
|
|
1183
|
+
order_command_arguments(positional: positional_args, options: stringify_options(options))
|
|
1184
|
+
end
|
|
1185
|
+
|
|
1186
|
+
# Partitions arguments and keyword arguments given to `#exec` into command options and
|
|
1187
|
+
# positional parameters.
|
|
1188
|
+
#
|
|
1189
|
+
# Generally, method keyword arguments become command options, and method arguments become
|
|
1190
|
+
# command positional arguments ("some_command file.txt").
|
|
1191
|
+
#
|
|
1192
|
+
# There are two exceptions: Symbols are shorthands for Symbol => nil keyword arguments
|
|
1193
|
+
# (:foo => "--foo"), and nested arrays are used for repeating options.
|
|
1194
|
+
#
|
|
1195
|
+
# @example
|
|
1196
|
+
# ```ruby
|
|
1197
|
+
# preprocess_arguments(["file.txt", :quiet, [[:l, 1], [:l, 2]]], { foo: "bar" })
|
|
1198
|
+
# # => [
|
|
1199
|
+
# # ["file.txt"],
|
|
1200
|
+
# # [[:quiet, nil], [:l, 1], [:l, 2], [:foo, "bar"]]
|
|
1201
|
+
# # ]
|
|
1202
|
+
# ```
|
|
1203
|
+
#
|
|
1204
|
+
# @param args [Array]
|
|
1205
|
+
# @return [Array<(Array, Array)>] one array of positional parameters and another array
|
|
1206
|
+
# of arrays for options (`[[:option_name, value]]`)
|
|
1207
|
+
def preprocess_arguments(args, kargs)
|
|
1208
|
+
positional_args = []
|
|
1209
|
+
flags = []
|
|
1210
|
+
kargs = kargs.to_a
|
|
1211
|
+
|
|
1212
|
+
args.each do |arg|
|
|
1213
|
+
case arg
|
|
1214
|
+
when Array
|
|
1215
|
+
kargs.concat(arg)
|
|
1216
|
+
when Symbol
|
|
1217
|
+
flags << [arg, nil]
|
|
1218
|
+
else
|
|
1219
|
+
positional_args <<
|
|
1220
|
+
if arg.respond_to?(:path)
|
|
1221
|
+
arg.path.to_s
|
|
1222
|
+
else
|
|
1223
|
+
arg.to_s
|
|
1224
|
+
end
|
|
1225
|
+
end
|
|
1226
|
+
end
|
|
1227
|
+
|
|
1228
|
+
return positional_args, (flags + kargs)
|
|
1229
|
+
end
|
|
1230
|
+
|
|
1231
|
+
# Takes nested option arrays and turns them into
|
|
1232
|
+
# a flat array of strings, ready for consumption by
|
|
1233
|
+
# `Process.spawn`
|
|
1234
|
+
#
|
|
1235
|
+
# @param outer_array [Array<Array>] an array in the form
|
|
1236
|
+
# of [[:option_name, option_value], [:other_option_name, nil]...]
|
|
1237
|
+
# @return [Array<String>] an array in the form of
|
|
1238
|
+
# ["--option_name", "option value", "--other_option_name" ...]
|
|
1239
|
+
def stringify_options(outer_array)
|
|
1240
|
+
outer_array.map do |array|
|
|
1241
|
+
option_name, value = *array
|
|
1242
|
+
|
|
1243
|
+
option_name =
|
|
1244
|
+
format_option_name(option_name)
|
|
1245
|
+
value =
|
|
1246
|
+
value.path.to_s if value.respond_to?(:path)
|
|
1247
|
+
|
|
1248
|
+
if option_name.include?("#VALUE#")
|
|
1249
|
+
[option_name.gsub("#VALUE#", value.to_s)]
|
|
1250
|
+
elsif value
|
|
1251
|
+
[option_name, value.to_s]
|
|
1252
|
+
else
|
|
1253
|
+
[option_name]
|
|
1254
|
+
end
|
|
1255
|
+
end.flatten
|
|
1256
|
+
end
|
|
1257
|
+
|
|
1258
|
+
# Transforms option name symbols into transformed and
|
|
1259
|
+
# prefixed strings, according to class settings
|
|
1260
|
+
#
|
|
1261
|
+
# @param option_name [Symbol]
|
|
1262
|
+
# @return [String]
|
|
1263
|
+
def format_option_name(option_name)
|
|
1264
|
+
if transform_options.key?(option_name)
|
|
1265
|
+
option_name = transform_options[option_name]
|
|
1266
|
+
end
|
|
1267
|
+
|
|
1268
|
+
if option_name.is_a?(Symbol)
|
|
1269
|
+
option_name = option_name.to_s.dasherize if dasherize_options
|
|
1270
|
+
|
|
1271
|
+
option_prefix_for(option_name) + option_name
|
|
1272
|
+
else
|
|
1273
|
+
option_name
|
|
1274
|
+
end
|
|
1275
|
+
end
|
|
1276
|
+
|
|
1277
|
+
# Returns the appropriate prefix for an option,
|
|
1278
|
+
# eg. the "--" in "--option=value"
|
|
1279
|
+
#
|
|
1280
|
+
# @param option_name [Symbol]
|
|
1281
|
+
# @return [String]
|
|
1282
|
+
def option_prefix_for(option_name)
|
|
1283
|
+
if option_prefix == :auto
|
|
1284
|
+
option_name.size == 1 ? "-" : "--"
|
|
1285
|
+
else
|
|
1286
|
+
option_prefix
|
|
1287
|
+
end
|
|
1288
|
+
end
|
|
1289
|
+
|
|
1290
|
+
# Orders options and positional arguments according to
|
|
1291
|
+
# the class setting
|
|
1292
|
+
#
|
|
1293
|
+
# @param positional [Array<String>]
|
|
1294
|
+
# @param options [Array<String>]
|
|
1295
|
+
# @return [Array<String>]
|
|
1296
|
+
def order_command_arguments(positional:, options:)
|
|
1297
|
+
case positional_parameters_position
|
|
1298
|
+
when :first
|
|
1299
|
+
positional + options
|
|
1300
|
+
when :last
|
|
1301
|
+
options + positional
|
|
1302
|
+
else
|
|
1303
|
+
raise "unsupported value for positional_parameters_position: #{positional_parameters_position}"
|
|
1304
|
+
end
|
|
1305
|
+
end
|
|
1306
|
+
|
|
1307
|
+
# Check if a process is still alive
|
|
1308
|
+
#
|
|
1309
|
+
# Uses signal 0 which checks process existence without affecting it
|
|
1310
|
+
#
|
|
1311
|
+
# Waits for the child process to exit, and reaps it
|
|
1312
|
+
#
|
|
1313
|
+
# With a `timeout`, the child is terminated once it has been running for longer.
|
|
1314
|
+
#
|
|
1315
|
+
# @param pid [Integer] the process ID of the child
|
|
1316
|
+
# @param timeout [Numeric, nil] seconds the child may run for
|
|
1317
|
+
# @return [Boolean] true if the child had to be terminated for exceeding `timeout`
|
|
1318
|
+
def wait_for_child(pid, timeout)
|
|
1319
|
+
unless timeout
|
|
1320
|
+
Process.wait(pid)
|
|
1321
|
+
return false
|
|
1322
|
+
end
|
|
1323
|
+
|
|
1324
|
+
deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
|
|
1325
|
+
|
|
1326
|
+
# The documentation for Process::WNOHANG says "do not block if no child available",
|
|
1327
|
+
# but that is misleading — it actually makes .waitpid nonblocking and only returns
|
|
1328
|
+
# the PID after the process has exited, `nil` otherwise.
|
|
1329
|
+
until Process.waitpid(pid, Process::WNOHANG)
|
|
1330
|
+
if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
|
|
1331
|
+
terminate_child(pid)
|
|
1332
|
+
return true
|
|
1333
|
+
end
|
|
1334
|
+
|
|
1335
|
+
sleep(0.05)
|
|
1336
|
+
end
|
|
1337
|
+
|
|
1338
|
+
false
|
|
1339
|
+
end
|
|
1340
|
+
|
|
1341
|
+
# Terminates a child process and reaps it: SIGTERM first, SIGKILL if it is still
|
|
1342
|
+
# alive after {TERMINATION_GRACE_PERIOD}
|
|
1343
|
+
#
|
|
1344
|
+
# Safe to call for a child which has exited or been reaped already.
|
|
1345
|
+
#
|
|
1346
|
+
# @param pid [Integer] the process ID of the child
|
|
1347
|
+
# @return [void]
|
|
1348
|
+
def terminate_child(pid)
|
|
1349
|
+
# Also reaps the child if it has exited in the meantime. Checking before signalling
|
|
1350
|
+
# keeps us from signalling a process ID which has been reaped and reused.
|
|
1351
|
+
return if Process.waitpid(pid, Process::WNOHANG)
|
|
1352
|
+
|
|
1353
|
+
Process.kill("TERM", pid)
|
|
1354
|
+
|
|
1355
|
+
grace_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + TERMINATION_GRACE_PERIOD
|
|
1356
|
+
|
|
1357
|
+
until Process.waitpid(pid, Process::WNOHANG)
|
|
1358
|
+
if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= grace_deadline
|
|
1359
|
+
Process.kill("KILL", pid)
|
|
1360
|
+
Process.waitpid(pid)
|
|
1361
|
+
return
|
|
1362
|
+
end
|
|
1363
|
+
|
|
1364
|
+
sleep(0.01)
|
|
1365
|
+
end
|
|
1366
|
+
rescue Errno::ESRCH, Errno::ECHILD
|
|
1367
|
+
# Already gone, and reaped
|
|
1368
|
+
end
|
|
1369
|
+
|
|
1370
|
+
# Lets the threads reading the child's output finish, and closes our end of the pipes
|
|
1371
|
+
#
|
|
1372
|
+
# The child is dead by now, which closes its ends of the pipes and lets the readers
|
|
1373
|
+
# return with whatever they have buffered. The brief wait is a safety net: a reader
|
|
1374
|
+
# which has not finished by then is killed, so threads cannot leak.
|
|
1375
|
+
#
|
|
1376
|
+
# @param stdout_reader [Thread, nil]
|
|
1377
|
+
# @param stderr_reader [Thread, nil]
|
|
1378
|
+
# @param stdout_pipe [IO, nil]
|
|
1379
|
+
# @param stderr_pipe [IO, nil]
|
|
1380
|
+
# @return [void]
|
|
1381
|
+
def release_output_readers(stdout_reader, stderr_reader, stdout_pipe, stderr_pipe)
|
|
1382
|
+
[stdout_reader, stderr_reader].compact.each do |reader|
|
|
1383
|
+
reader.join(1)
|
|
1384
|
+
reader.kill if reader.alive?
|
|
1385
|
+
end
|
|
1386
|
+
|
|
1387
|
+
stdout_pipe&.close
|
|
1388
|
+
stderr_pipe&.close
|
|
1389
|
+
end
|
|
1390
|
+
|
|
1391
|
+
# @param pid [Integer] the process ID to check
|
|
1392
|
+
# @return [Boolean] true if the process is alive, false otherwise
|
|
1393
|
+
def process_alive?(pid)
|
|
1394
|
+
Process.kill(0, pid)
|
|
1395
|
+
true
|
|
1396
|
+
rescue Errno::ESRCH
|
|
1397
|
+
false
|
|
1398
|
+
end
|
|
1399
|
+
end
|
|
1400
|
+
end
|