Module Bio::Command
In: lib/bio/command.rb

Bio::Command

Bio::Command is a collection of useful methods for execution of external commands or web applications. Any wrapper class for applications shall use this class.

Library internal use only. Users should not directly use it.

Methods

Constants

UNSAFE_CHARS_UNIX = /[^A-Za-z0-9\_\-\.\:\,\/\@\x1b\x80-\xfe]/n
QUOTE_CHARS_WINDOWS = /[^A-Za-z0-9\_\-\.\:\,\/\@\\]/n
UNESCAPABLE_CHARS = /[\x00-\x08\x10-\x1a\x1c-\x1f\x7f\xff]/n

Public Instance methods

Executes the program. Automatically select popen for Windows environment and fork for the others. A block must be given. An IO object is passed to the block.

Available options:

  :chdir => "path" : changes working directory to the specified path.

Arguments:

  • (required) cmd: Array containing String objects
  • (optional) options: Hash
Returns:(undefined)

[Source]

     # File lib/bio/command.rb, line 145
145:   def call_command(cmd, options = {}, &block) #:yields: io
146:     case RUBY_PLATFORM
147:     when /mswin32|bccwin32/
148:       call_command_popen(cmd, options, &block)
149:     else
150:       call_command_fork(cmd, options, &block)
151:     end
152:   end

Executes the program via fork (by using IO.popen("-")) and exec. A block must be given. An IO object is passed to the block.

From the view point of security, this method is recommended rather than call_command_popen.


Arguments:

  • (required) cmd: Array containing String objects
  • (optional) options: Hash
Returns:(undefined)

[Source]

     # File lib/bio/command.rb, line 196
196:   def call_command_fork(cmd, options = {})
197:     dir = options[:chdir]
198:     cmd = safe_command_line_array(cmd)
199:     IO.popen("-", "r+") do |io|
200:       if io then
201:         # parent
202:         yield io
203:       else
204:         # child
205:         # chdir to options[:chdir] if available
206:         begin
207:           Dir.chdir(dir) if dir
208:         rescue Exception
209:           Process.exit!(1)
210:         end
211:         # executing the command
212:         begin
213:           Kernel.exec(*cmd)
214:         rescue Errno::ENOENT, Errno::EACCES
215:           Process.exit!(127)
216:         rescue Exception
217:         end
218:         Process.exit!(1)
219:       end
220:     end
221:   end

Executes the program via Open3.popen3 A block must be given. IO objects are passed to the block.

You would use this method only when you really need to get stderr.


Arguments:

  • (required) cmd: Array containing String objects
Returns:(undefined)

[Source]

     # File lib/bio/command.rb, line 232
232:   def call_command_open3(cmd)
233:     cmd = safe_command_line_array(cmd)
234:     Open3.popen3(*cmd) do |pin, pout, perr|
235:       yield pin, pout, perr
236:     end
237:   end

Executes the program via IO.popen for OS which doesn‘t support fork. A block must be given. An IO object is passed to the block.


Arguments:

  • (required) cmd: Array containing String objects
  • (optional) options: Hash
Returns:(undefined)

[Source]

     # File lib/bio/command.rb, line 161
161:   def call_command_popen(cmd, options = {})
162:     str = make_command_line(cmd)
163:     # processing options
164:     if dir = options[:chdir] then
165:       case RUBY_PLATFORM
166:       when /mswin32|bccwin32/
167:         # Unix-like dir separator is changed to Windows dir separator
168:         # by using String#gsub.
169:         dirstr = dir.gsub(/\//, "\\")
170:         chdirstr = make_command_line([ 'cd', '/D', dirstr ])
171:         str = chdirstr + ' && ' + str
172:       else
173:         # UNIX shell
174:         chdirstr = make_command_line([ 'cd', dir ])
175:         str = chdirstr + ' && ' + str
176:       end
177:     end
178:     # call command by using IO.popen
179:     IO.popen(str, "w+") do |io|
180:       io.sync = true
181:       yield io
182:     end
183:   end

Escape special characters in command line string.


Arguments:

Returns:String object

[Source]

    # File lib/bio/command.rb, line 68
68:   def escape_shell(str)
69:     case RUBY_PLATFORM
70:     when /mswin32|bccwin32/
71:       escape_shell_windows(str)
72:     else
73:       escape_shell_unix(str)
74:     end
75:   end

Escape special characters in command line string for UNIX shells.


Arguments:

Returns:String object

[Source]

    # File lib/bio/command.rb, line 57
57:   def escape_shell_unix(str)
58:     str = str.to_s
59:     raise 'cannot escape control characters' if UNESCAPABLE_CHARS =~ str
60:     str.gsub(UNSAFE_CHARS_UNIX) { |x| "\\#{x}" }
61:   end

Escape special characters in command line string for cmd.exe on Windows.


Arguments:

Returns:String object

[Source]

    # File lib/bio/command.rb, line 42
42:   def escape_shell_windows(str)
43:     str = str.to_s
44:     raise 'cannot escape control characters' if UNESCAPABLE_CHARS =~ str
45:     if QUOTE_CHARS_WINDOWS =~ str then
46:       '"' + str.gsub(/\"/, '""') + '"'
47:     else
48:       String.new(str)
49:     end
50:   end

Same as:

 http = Net::HTTP.new(...); http.post_form(path, params)

and it uses proxy if an environment variable (same as OpenURI.open_uri) is set. In addition, header can be set. (Note that Content-Type and Content-Length are automatically set by default.) uri must be a URI object, params must be a hash, and header must be a hash.


Arguments:

  • (required) http: Net::HTTP object or compatible object
  • (required) path: String
  • (optional) params: Hash containing parameters
  • (optional) header: Hash containing header strings
Returns:(same as Net::HTTP::post_form)

[Source]

     # File lib/bio/command.rb, line 481
481:   def http_post_form(http, path, params = nil, header = {})
482:     data = make_cgi_params(params)
483: 
484:     hash = {
485:       'Content-Type'   => 'application/x-www-form-urlencoded',
486:       'Content-Length' => data.length.to_s
487:     }
488:     hash.update(header)
489: 
490:     http.post(path, data, hash)
491:   end

Builds parameter string for from Hash of parameters for application/x-www-form-urlencoded.


Arguments:

  • (required) params: Hash containing parameters
Returns:String

[Source]

     # File lib/bio/command.rb, line 535
535:   def make_cgi_params(params)
536:     data = ""
537:     case params
538:     when Hash
539:       data = params.map do |key, val|
540:         make_cgi_params_key_value(key, val)
541:       end.join('&')
542:     when Array
543:       case params.first
544:       when Hash
545:         data = params.map do |hash|
546:           hash.map do |key, val|
547:             make_cgi_params_key_value(key, val)
548:           end
549:         end.join('&')
550:       when Array
551:         data = params.map do |key, val|
552:           make_cgi_params_key_value(key, val)
553:         end.join('&')
554:       when String
555:         data = params.map do |str|
556:           key, val = str.split(/\=/, 2)
557:           if val then
558:             make_cgi_params_key_value(key, val)
559:           else
560:             CGI.escape(str)
561:           end
562:         end.join('&')
563:       end
564:     when String
565:       data = URI.escape(params.strip)
566:     end
567:     return data
568:   end

Builds parameter string for from a key string and a value (or values) for application/x-www-form-urlencoded.


Arguments:

Returns:String

[Source]

     # File lib/bio/command.rb, line 578
578:   def make_cgi_params_key_value(key, value)
579:     result = []
580:     case value
581:     when Array
582:       value.each do |val|
583:         result << [key, val].map {|x| CGI.escape(x.to_s) }.join('=')
584:       end
585:     else
586:       result << [key, value].map {|x| CGI.escape(x.to_s) }.join('=')
587:     end
588:     return result
589:   end

Generate command line string with special characters escaped.


Arguments:

  • (required) ary: Array containing String objects
Returns:String object

[Source]

    # File lib/bio/command.rb, line 82
82:   def make_command_line(ary)
83:     case RUBY_PLATFORM
84:     when /mswin32|bccwin32/
85:       make_command_line_windows(ary)
86:     else
87:       make_command_line_unix(ary)
88:     end
89:   end

Generate command line string with special characters escaped for UNIX shells.


Arguments:

  • (required) ary: Array containing String objects
Returns:String object

[Source]

     # File lib/bio/command.rb, line 107
107:   def make_command_line_unix(ary)
108:     ary.collect { |str| escape_shell_unix(str) }.join(" ")
109:   end

Generate command line string with special characters escaped for cmd.exe on Windows.


Arguments:

  • (required) ary: Array containing String objects
Returns:String object

[Source]

    # File lib/bio/command.rb, line 97
97:   def make_command_line_windows(ary)
98:     ary.collect { |str| escape_shell_windows(str) }.join(" ")
99:   end

Backport of Dir.mktmpdir in Ruby 1.9.

Same as Dir.mktmpdir(prefix_suffix) in Ruby 1.9 except that prefix must be a String, nil, or omitted.


Arguments:

[Source]

     # File lib/bio/command.rb, line 367
367:   def mktmpdir(prefix = 'd', tmpdir = nil, &block)
368:     prefix = prefix.to_str
369:     begin
370:       Dir.mktmpdir(prefix, tmpdir, &block)
371:     rescue NoMethodError
372:       suffix = ''
373:       # backported from Ruby 1.9.0.
374:       # ***** Below is excerpted from Ruby 1.9.0's lib/tmpdir.rb ****
375:       # ***** Be careful about copyright. ****
376:       tmpdir ||= Dir.tmpdir
377:       t = Time.now.strftime("%Y%m%d")
378:       n = nil
379:       begin
380:         path = "#{tmpdir}/#{prefix}#{t}-#{$$}-#{rand(0x100000000).to_s(36)}"
381:         path << "-#{n}" if n
382:         path << suffix
383:         Dir.mkdir(path, 0700)
384:       rescue Errno::EEXIST
385:         n ||= 0
386:         n += 1
387:         retry
388:       end
389: 
390:       if block_given?
391:         begin
392:           yield path
393:         ensure
394:           remove_entry_secure path
395:         end
396:       else
397:         path
398:       end
399:       # ***** Above is excerpted from Ruby 1.9.0's lib/tmpdir.rb ****
400:     end
401:   end

Same as:

  Net::HTTP.new(address, port)

and it uses proxy if an environment variable (same as OpenURI.open_uri) is set.


Arguments:

  • (required) address: String containing host name or IP address
  • (optional) port: port (sanme as Net::HTTP::start)
Returns:(same as Net::HTTP.new except for proxy support)

[Source]

     # File lib/bio/command.rb, line 451
451:   def new_http(address, port = 80)
452:     uri = URI.parse("http://#{address}:#{port}")
453:     # Note: URI#find_proxy is an unofficial method defined in open-uri.rb.
454:     # If the spec of open-uri.rb would be changed, we should change below.
455:     if proxyuri = uri.find_proxy then
456:       raise 'Non-HTTP proxy' if proxyuri.class != URI::HTTP
457:       Net::HTTP.new(address, port, proxyuri.host, proxyuri.port)
458:     else
459:       Net::HTTP.new(address, port)
460:     end
461:   end

Same as: Net::HTTP.post_form(uri, params) and it uses proxy if an environment variable (same as OpenURI.open_uri) is set. In addition, header can be set. (Note that Content-Type and Content-Length are automatically set by default.) uri must be a URI object, params must be a hash, and header must be a hash.


Arguments:

  • (required) uri: URI object or String
  • (optional) params: Hash containing parameters
  • (optional) header: Hash containing header strings
Returns:(same as Net::HTTP::post_form)

[Source]

     # File lib/bio/command.rb, line 510
510:   def post_form(uri, params = nil, header = {})
511:     unless uri.is_a?(URI)
512:       uri = URI.parse(uri)
513:     end
514: 
515:     data = make_cgi_params(params)
516: 
517:     hash = {
518:       'Content-Type'   => 'application/x-www-form-urlencoded',
519:       'Content-Length' => data.length.to_s
520:     }
521:     hash.update(header)
522: 
523:     start_http(uri.host, uri.port) do |http|
524:       http.post(uri.path, data, hash)
525:     end
526:   end

Executes the program with the query (String) given to the standard input, waits the program termination, and returns the output data printed to the standard output as a string.

Automatically select popen for Windows environment and fork for the others.

Available options:

  :chdir => "path" : changes working directory to the specified path.

Arguments:

  • (required) cmd: Array containing String objects
  • (optional) query: String
  • (optional) options: Hash
Returns:String or nil

[Source]

     # File lib/bio/command.rb, line 254
254:   def query_command(cmd, query = nil, options = {})
255:     case RUBY_PLATFORM
256:     when /mswin32|bccwin32/
257:       query_command_popen(cmd, query, options)
258:     else
259:       query_command_fork(cmd, query, options)
260:     end
261:   end

Executes the program with the query (String) given to the standard input, waits the program termination, and returns the output data printed to the standard output as a string.

Fork (by using IO.popen("-")) and exec is used to execute the program.

From the view point of security, this method is recommended rather than query_command_popen.


Arguments:

  • (required) cmd: Array containing String objects
  • (optional) query: String
  • (optional) options: Hash
Returns:String or nil

[Source]

     # File lib/bio/command.rb, line 301
301:   def query_command_fork(cmd, query = nil, options = {})
302:     ret = nil
303:     call_command_fork(cmd, options) do |io|
304:       io.sync = true
305:       io.print query if query
306:       io.close_write
307:       ret = io.read
308:     end
309:     ret
310:   end

Executes the program via Open3.popen3 with the query (String) given to the stain, waits the program termination, and returns the data from stdout and stderr as an array of the strings.

You would use this method only when you really need to get stderr.


Arguments:

  • (required) cmd: Array containing String objects
  • (optional) query: String
Returns:Array containing 2 objects: output string (or nil) and stderr string (or nil)

[Source]

     # File lib/bio/command.rb, line 323
323:   def query_command_open3(cmd, query = nil)
324:     errorlog = nil
325:     cmd = safe_command_line_array(cmd)
326:     Open3.popen3(*cmd) do |pin, pout, perr|
327:       perr.sync = true
328:       t = Thread.start { errorlog = perr.read }
329:       begin
330:         pin.print query if query
331:         pin.close
332:         output = pout.read
333:       ensure
334:         t.join
335:       end
336:       [ output, errorlog ]
337:     end
338:   end

Executes the program with the query (String) given to the standard input, waits the program termination, and returns the output data printed to the standard output as a string.

IO.popen is used for OS which doesn‘t support fork.


Arguments:

  • (required) cmd: Array containing String objects
  • (optional) query: String
  • (optional) options: Hash
Returns:String or nil

[Source]

     # File lib/bio/command.rb, line 275
275:   def query_command_popen(cmd, query = nil, options = {})
276:     ret = nil
277:     call_command_popen(cmd, options) do |io|
278:       io.sync = true
279:       io.print query if query
280:       io.close_write
281:       ret = io.read
282:     end
283:     ret
284:   end

Same as OpenURI.open_uri(uri).read and it uses proxy if an environment variable (same as OpenURI.open_uri) is set.


Arguments:

  • (required) uri: URI object or String
Returns:String

[Source]

     # File lib/bio/command.rb, line 412
412:   def read_uri(uri)
413:     OpenURI.open_uri(uri).read
414:   end

Same as FileUtils.remove_entry_secure after Ruby 1.8.3. In Ruby 1.8.2 or previous version, it only shows warning message and does nothing.

It is strongly recommended using Ruby 1.8.5 or later.


Arguments:

  • (required) path: String
  • (optional) force: boolean

[Source]

     # File lib/bio/command.rb, line 349
349:   def remove_entry_secure(path, force = false)
350:     begin
351:       FileUtils.remove_entry_secure(path, force)
352:     rescue NoMethodError
353:       warn "The temporary file or directory is not removed because of the lack of FileUtils.remove_entry_secure. Use Ruby 1.8.3 or later (1.8.5 or later is strongly recommended): #{path}"
354:       nil
355:     end
356:   end

Returns an Array of command-line command and arguments that can be safely passed to Kernel.exec etc. If the given array is already safe (or empty), returns the given array.


Arguments:

  • (required) ary: Array
Returns:Array

[Source]

     # File lib/bio/command.rb, line 118
118:   def safe_command_line_array(ary)
119:     ary = ary.to_ary
120:     return ary if ary.size >= 2 or ary.empty?
121:     if ary.size != 1 then
122:       raise 'Bug: assersion of ary.size == 1 failed'
123:     end
124:     arg0 = ary[0]
125:     begin
126:       arg0 = arg0.to_ary
127:     rescue NoMethodError
128:       arg0 = [ arg0, arg0 ]
129:     end
130:     [ arg0 ]
131:   end

Same as:

  Net::HTTP.start(address, port)

and it uses proxy if an environment variable (same as OpenURI.open_uri) is set.


Arguments:

  • (required) address: String containing host name or IP address
  • (optional) port: port (sanme as Net::HTTP::start)
Returns:(same as Net::HTTP::start except for proxy support)

[Source]

     # File lib/bio/command.rb, line 427
427:   def start_http(address, port = 80, &block)
428:     uri = URI.parse("http://#{address}:#{port}")
429:     # Note: URI#find_proxy is an unofficial method defined in open-uri.rb.
430:     # If the spec of open-uri.rb would be changed, we should change below.
431:     if proxyuri = uri.find_proxy then
432:       raise 'Non-HTTP proxy' if proxyuri.class != URI::HTTP
433:       http = Net::HTTP.Proxy(proxyuri.host, proxyuri.port)
434:     else
435:       http = Net::HTTP
436:     end
437:     http.start(address, port, &block)
438:   end

[Validate]