module Shellwords

Manipulates strings like the UNIX Bourne shell↑

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

Theshellwords() function was originally a port of shellwords.pl, but modified to conform tothe Shell & Utilities volume of the IEEE Std 1003.1-2008, 2016 Edition

Usage↑

You can useShellwords to parse a string into a Bourne shell friendlyArray.

require'shellwords'argv =Shellwords.split('three blind "mice"')argv#=> ["three", "blind", "mice"]

Once you’ve requiredShellwords, you can use the split aliasString#shellsplit.

argv ="see how they run".shellsplitargv#=> ["see", "how", "they", "run"]

They treat quotes as special characters, so an unmatched quote will cause anArgumentError.

argv ="they all ran after the farmer's wife".shellsplit#=> ArgumentError: Unmatched quote: ...

Shellwords also provides methods that do the opposite.Shellwords.escape, or its alias,String#shellescape, escapes shell metacharacters in a string for use in a command line.

filename ="special's.txt"system("cat -- #{filename.shellescape}")# runs "cat -- special\\'s.txt"

Note the ‘–’. Without it, cat(1) will treat the following argument as a command line option if it starts with ‘-’. It is guaranteed thatShellwords.escape converts a string to a form that a Bourne shell will parse back to the original string, but it is the programmer’s responsibility to make sure that passing an arbitrary argument to a command does no harm.

Shellwords also comes with a core extension forArray,Array#shelljoin.

dir ="Funny GIFs"argv =%W[ls -lta -- #{dir}]system(argv.shelljoin+" | less")# runs "ls -lta -- Funny\\ GIFs | less"

You can use this method to build a complete command line out of an array of arguments.

Authors↑

Contact↑

Constants

VERSION

The version number string.

Public Class Methods

Alias for:shellescape
Alias for:shelljoin
Source
# File lib/shellwords.rb, line 158defshellescape(str)str =str.to_s# An empty argument will be skipped, so return empty quotes.return"''".dupifstr.empty?# Shellwords cannot contain NUL characters.raiseArgumentError,"NUL character"ifstr.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'")returnstrend

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 toto_s.

str must not contain NUL characters because of nature ofexec 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".shellescapeargv#=> "It\\'s\\ better\\ to\\ give\\ than\\ to\\ receive"# Search files in lib for method definitionspattern ="^[ \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 quotedString ifstr has a length of zero.

Also aliased as:escape
Source
# File lib/shellwords.rb, line 208defshelljoin(array)array.map {|arg|shellescape(arg) }.join(' ')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 usingto_s. See alsoShellwords.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.shelljoinargv#=> "Don\\'t rock the boat"

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

output =`#{['ps', '-p', $$].shelljoin}`
Also aliased as:join
Source
# File lib/shellwords.rb, line 90defshellsplit(line)words = []field =String.newline.scan(/\G\s*(?>([^\0\s\\\'\"]+)|'([^\0\']*)'|"((?:[^\0\"\\]|\\[^\0])*)"|(\\[^\0]?)|(\S))(\s|\z)?/m)do|word,sq,dq,esc,garbage,sep|ifgarbageb =$~.begin(0)line =$~[0]line ="..."+lineifb>0raiseArgumentError,"#{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'))ifsepwords<<fieldfield =String.newendendwordsend

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 ofexec 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"'.shellsplitargv#=> ["here", "are", "two words"]
Also aliased as:shellwords,split
Alias for:shellsplit
Alias for:shellsplit

Private Instance Methods

Source
# File lib/shellwords.rb, line 158defshellescape(str)str =str.to_s# An empty argument will be skipped, so return empty quotes.return"''".dupifstr.empty?# Shellwords cannot contain NUL characters.raiseArgumentError,"NUL character"ifstr.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'")returnstrend

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 toto_s.

str must not contain NUL characters because of nature ofexec 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".shellescapeargv#=> "It\\'s\\ better\\ to\\ give\\ than\\ to\\ receive"# Search files in lib for method definitionspattern ="^[ \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 quotedString ifstr has a length of zero.

Also aliased as:escape
Source
# File lib/shellwords.rb, line 208defshelljoin(array)array.map {|arg|shellescape(arg) }.join(' ')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 usingto_s. See alsoShellwords.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.shelljoinargv#=> "Don\\'t rock the boat"

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

output =`#{['ps', '-p', $$].shelljoin}`
Also aliased as:join
Source
# File lib/shellwords.rb, line 90defshellsplit(line)words = []field =String.newline.scan(/\G\s*(?>([^\0\s\\\'\"]+)|'([^\0\']*)'|"((?:[^\0\"\\]|\\[^\0])*)"|(\\[^\0]?)|(\S))(\s|\z)?/m)do|word,sq,dq,esc,garbage,sep|ifgarbageb =$~.begin(0)line =$~[0]line ="..."+lineifb>0raiseArgumentError,"#{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'))ifsepwords<<fieldfield =String.newendendwordsend

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 ofexec 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"'.shellsplitargv#=> ["here", "are", "two words"]
Also aliased as:shellwords,split
Alias for:shellsplit