Module: Shellwords

Defined in:
lib/shellwords.rb

Overview

This module manipulates strings according to the word parsing rules of the UNIX Bourne shell.

The shellwords() function was originally a port of shellwords.pl, but modified to conform to POSIX / SUSv3 (IEEE Std 1003.1-2001).

Authors:

- Wakou Aoyama
- Akinori MUSHA <[email protected]>

Contact:

- Akinori MUSHA <[email protected]> (current maintainer)

Class Method Summary collapse

Class Method Details

.shellescape(str) ⇒ Object Also known as: escape

Escapes a string so that it can be safely used in a Bourne shell command line.

Note that a resulted string should be used unquoted and is not intended for use in double quotes nor in single quotes.

open("| grep #{Shellwords.escape(pattern)} file") { |pipe|
  # ...
}

String#shellescape is a shorthand for this function.

open("| grep #{pattern.shellescape} file") { |pipe|
  # ...
}

It is caller’s responsibility to encode the string in the right encoding for the shell environment where this string is used. Multibyte characters are treated as multibyte characters, not bytes.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/shellwords.rb', line 73

def shellescape(str)
  # An empty argument will be skipped, so return empty quotes.
  return "''" if str.empty?

  str = str.dup

  # Treat multibyte characters as is.  It is caller's responsibility
  # to encode the string in the right encoding for the shell
  # environment.
  str.gsub!(/([^A-Za-z0-9_\-.,:\/@\n])/, "\\\\\\1")

  # A LF cannot be escaped with a backslash because a backslash + LF
  # combo is regarded as line continuation and simply ignored.
  str.gsub!(/\n/, "'\n'")

  return str
end

.shelljoin(array) ⇒ Object Also known as: join

Builds a command line string from an argument list array joining all elements escaped for Bourne shell and separated by a space.

open('|' + Shellwords.join(['grep', pattern, *files])) { |pipe|
  # ...
}

Array#shelljoin is a shorthand for this function.

open('|' + ['grep', pattern, *files].shelljoin) { |pipe|
  # ...
}



110
111
112
 
# File 'lib/shellwords.rb', line 110

def shelljoin(array)
  array.map { |arg| shellescape(arg) }.join(' ')
end

.shellsplit(line) ⇒ Object Also known as: split

Splits a string into an array of tokens in the same way the UNIX Bourne shell does.

argv = Shellwords.split('here are "two words"')
argv #=> ["here", "are", "two words"]

String#shellsplit is a shorthand for this function.

argv = 'here are "two words"'.shellsplit
argv #=> ["here", "are", "two words"]



30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/shellwords.rb', line 30

def shellsplit(line)
  words = []
  field = ''
  line.scan(/\G\s*(?>([^\s\\\'\"]+)|'([^\']*)'|"((?:[^\"\\]|\\.)*)"|(\\.?)|(\S))(\s|\z)?/m) do
    |word, sq, dq, esc, garbage, sep|
    raise ArgumentError, "Unmatched double quote: #{line.inspect}" if garbage
    field << (word || sq || (dq || esc).gsub(/\\(.)/, '\\1'))
    if sep
      words << field
      field = ''
    end
  end
  words
end

.shellwords ⇒ Object

Splits a string into an array of tokens in the same way the UNIX Bourne shell does.

argv = Shellwords.split('here are "two words"')
argv #=> ["here", "are", "two words"]

String#shellsplit is a shorthand for this function.

argv = 'here are "two words"'.shellsplit
argv #=> ["here", "are", "two words"]



45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/shellwords.rb', line 45

def shellsplit(line)
  words = []
  field = ''
  line.scan(/\G\s*(?>([^\s\\\'\"]+)|'([^\']*)'|"((?:[^\"\\]|\\.)*)"|(\\.?)|(\S))(\s|\z)?/m) do
    |word, sq, dq, esc, garbage, sep|
    raise ArgumentError, "Unmatched double quote: #{line.inspect}" if garbage
    field << (word || sq || (dq || esc).gsub(/\\(.)/, '\\1'))
    if sep
      words << field
      field = ''
    end
  end
  words
end