module Shellwords

Escapes a string so that it can be safely used in a Bourne shell command line. str can be a non-string object that responds to to_s.

str must not contain NUL characters because of nature of exec system call.

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

argv = Shellwords.escape("It's better to give than to receive")
argv #=> "It\\'s\\ better\\ to\\ give\\ than\\ to\\ receive"

String#shellescape is a shorthand for this function.

argv = "It's better to give than to receive".shellescape
argv #=> "It\\'s\\ better\\ to\\ give\\ than\\ to\\ receive"

# Search files in lib for method definitions
pattern = "^[ \t]*def "
open("| grep -Ern -e #{pattern.shellescape} lib") { |grep|
  grep.each_line { |line|
    file, lineno, matched_line = line.split(':', 3)
    # ...
  }
}

It is the 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 as bytes.

Returns an empty quoted String if str has a length of zero.

# File shellwords.rb, line 158
def shellescape(str)
  str = str.to_s

  # An empty argument will be skipped, so return empty quotes.
  return "''".dup if str.empty?

  # Shellwords cannot contain NUL characters.
  raise ArgumentError, "NUL character" if str.index("\0")

  str = str.dup

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

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

  return str
end

Builds a command line string from an argument list, array.

All elements are joined into a single string with fields separated by a space, where each element is escaped for the Bourne shell and stringified using to_s. See also Shellwords.shellescape.

ary = ["There's", "a", "time", "and", "place", "for", "everything"]
argv = Shellwords.join(ary)
argv #=> "There\\'s a time and place for everything"

Array#shelljoin is a shortcut for this function.

ary = ["Don't", "rock", "the", "boat"]
argv = ary.shelljoin
argv #=> "Don\\'t rock the boat"

You can also mix non-string objects in the elements as allowed in Array#join.

output = `#{['ps', '-p', $$].shelljoin}`

# File shellwords.rb, line 208
def shelljoin(array)
  array.map { |arg| shellescape(arg) }.join(' ')
end

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"]

line must not contain NUL characters because of nature of exec system call.

Note, however, that this is not a command line parser. Shell metacharacters except for the single and double quotes and backslash are not treated as such.

argv = Shellwords.split('ruby my_prog.rb | less')
argv #=> ["ruby", "my_prog.rb", "|", "less"]

String#shellsplit is a shortcut for this function.

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

# File shellwords.rb, line 90
def shellsplit(line)
  words = []
  field = String.new
  line.scan(/\G\s*(?>([^\0\s\\\'\"]+)|'([^\0\']*)'|"((?:[^\0\"\\]|\\[^\0])*)"|(\\[^\0]?)|(\S))(\s|\z)?/m) do
    |word, sq, dq, esc, garbage, sep|
    if garbage
      b = $~.begin(0)
      line = $~[0]
      line = "..." + line if b > 0
      raise ArgumentError, "#{garbage == "\0" ? 'Nul character' : 'Unmatched quote'} at #{b}: #{line}"
    end
    # 2.2.3 Double-Quotes:
    #
    #   The <backslash> shall retain its special meaning as an
    #   escape character only when followed by one of the following
    #   characters when considered special:
    #
    #   $ ` " \ <newline>
    field << (word || sq || (dq && dq.gsub(/\\([$`"\\\n])/, '\\1')) || esc.gsub(/\\(.)/, '\\1'))
    if sep
      words << field
      field = String.new
    end
  end
  words
end

Escapes a string so that it can be safely used in a Bourne shell command line. str can be a non-string object that responds to to_s.

str must not contain NUL characters because of nature of exec system call.

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

argv = Shellwords.escape("It's better to give than to receive")
argv #=> "It\\'s\\ better\\ to\\ give\\ than\\ to\\ receive"

String#shellescape is a shorthand for this function.

argv = "It's better to give than to receive".shellescape
argv #=> "It\\'s\\ better\\ to\\ give\\ than\\ to\\ receive"

# Search files in lib for method definitions
pattern = "^[ \t]*def "
open("| grep -Ern -e #{pattern.shellescape} lib") { |grep|
  grep.each_line { |line|
    file, lineno, matched_line = line.split(':', 3)
    # ...
  }
}

It is the 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 as bytes.

Returns an empty quoted String if str has a length of zero.

# File shellwords.rb, line 158
def shellescape(str)
  str = str.to_s

  # An empty argument will be skipped, so return empty quotes.
  return "''".dup if str.empty?

  # Shellwords cannot contain NUL characters.
  raise ArgumentError, "NUL character" if str.index("\0")

  str = str.dup

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

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

  return str
end

Builds a command line string from an argument list, array.

All elements are joined into a single string with fields separated by a space, where each element is escaped for the Bourne shell and stringified using to_s. See also Shellwords.shellescape.

ary = ["There's", "a", "time", "and", "place", "for", "everything"]
argv = Shellwords.join(ary)
argv #=> "There\\'s a time and place for everything"

Array#shelljoin is a shortcut for this function.

ary = ["Don't", "rock", "the", "boat"]
argv = ary.shelljoin
argv #=> "Don\\'t rock the boat"

You can also mix non-string objects in the elements as allowed in Array#join.

output = `#{['ps', '-p', $$].shelljoin}`

# File shellwords.rb, line 208
def shelljoin(array)
  array.map { |arg| shellescape(arg) }.join(' ')
end

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"]

line must not contain NUL characters because of nature of exec system call.

Note, however, that this is not a command line parser. Shell metacharacters except for the single and double quotes and backslash are not treated as such.

argv = Shellwords.split('ruby my_prog.rb | less')
argv #=> ["ruby", "my_prog.rb", "|", "less"]

String#shellsplit is a shortcut for this function.

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

# File shellwords.rb, line 90
def shellsplit(line)
  words = []
  field = String.new
  line.scan(/\G\s*(?>([^\0\s\\\'\"]+)|'([^\0\']*)'|"((?:[^\0\"\\]|\\[^\0])*)"|(\\[^\0]?)|(\S))(\s|\z)?/m) do
    |word, sq, dq, esc, garbage, sep|
    if garbage
      b = $~.begin(0)
      line = $~[0]
      line = "..." + line if b > 0
      raise ArgumentError, "#{garbage == "\0" ? 'Nul character' : 'Unmatched quote'} at #{b}: #{line}"
    end
    # 2.2.3 Double-Quotes:
    #
    #   The <backslash> shall retain its special meaning as an
    #   escape character only when followed by one of the following
    #   characters when considered special:
    #
    #   $ ` " \ <newline>
    field << (word || sq || (dq && dq.gsub(/\\([$`"\\\n])/, '\\1')) || esc.gsub(/\\(.)/, '\\1'))
    if sep
      words << field
      field = String.new
    end
  end
  words
end