# frozen-string-literal: true
# == Manipulates strings like the UNIX Bourne shell
# 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 the Shell & Utilities volume of the IEEE
# Std 1003.1-2008, 2016 Edition [1].
# You can use Shellwords to parse a string into a Bourne shell friendly Array.
# argv = Shellwords.split('three blind "mice"')
# argv #=> ["three", "blind", "mice"]
# Once you've required Shellwords, you can use the #split alias
# argv = "see how they run".shellsplit
# argv #=> ["see", "how", "they", "run"]
# They treat quotes as special characters, so an unmatched quote will
# cause an ArgumentError.
# 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
# that Shellwords.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 for Array, Array#shelljoin.
# 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
# * Akinori MUSHA <knu@iDaemons.org>
# * Akinori MUSHA <knu@iDaemons.org> (current maintainer)
# 1: {IEEE Std 1003.1-2008, 2016 Edition, the Shell & Utilities volume}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/contents.html]
# Splits a string into an array of tokens in the same way the UNIX
# argv = Shellwords.split('here are "two words"')
# argv #=> ["here", "are", "two words"]
# 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"]
line.scan(/\G\s*(?>([^\s\\\'\"]+)|'([^\']*)'|"((?:[^\"\\]|\\.)*)"|(\\.?)|(\S))(\s|\z)?/m) do
|word, sq, dq, esc, garbage, sep|
raise ArgumentError, "Unmatched quote: #{line.inspect}" if garbage
# The <backslash> shall retain its special meaning as an
# escape character only when followed by one of the following
# characters when considered special:
field << (word || sq || (dq && dq.gsub(/\\([$`"\\\n])/, '\\1')) || esc.gsub(/\\(.)/, '\\1'))
alias shellwords shellsplit
module_function :shellsplit, :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
# 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.
# An empty argument will be skipped, so return empty quotes.
return "''".dup if str.empty?
# Treat multibyte characters as is. It is the caller's responsibility
# to encode the string in the right encoding for the shell
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.
module_function :shellescape
# 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
# 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 #=> "Don\\'t rock the boat"
# You can also mix non-string objects in the elements as allowed in Array#join.
# output = `#{['ps', '-p', $$].shelljoin}`
array.map { |arg| shellescape(arg) }.join(' ')
module_function :shelljoin
# str.shellsplit => array
# Splits +str+ into an array of tokens in the same way the UNIX
# See Shellwords.shellsplit for details.
# str.shellescape => string
# Escapes +str+ so that it can be safely used in a Bourne shell
# See Shellwords.shellescape for details.
# array.shelljoin => string
# Builds a command line string from an argument list +array+ joining
# all elements escaped for the Bourne shell and separated by a space.
# See Shellwords.shelljoin for details.
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
