module ShellQuotes

Command-Line Shell Style Quoting Made Available in Ruby.

A module designed to help simplify creation of complex Unix shell commands.

Helps you to construct (partial) Unix shell commands taking care of all of the shell-escapes wherever necessary. Covers the Bourne, Bash and csh shells.

Public Class Methods

bash_escape(*args) click to toggle source

Similar to bourne_escape, but for Bash shell.

# File lib/shell_quotes.rb, line 147
def ShellQuotes.bash_escape(*args)
        ShellQuotes.escape(shell = :bash, *args)
end
bourne_escape(*args) click to toggle source

Produces -> String

Forms a string that represents a (part of a) Bourne shell command.

Its argument(s) should be one or more hashes that use certain symbols as their keys. the values should all be of type String.

  • Symbols and their meaning:

:pass -> Left unchanged.

:command, :cmd -> Shell command. Left unchanged.

:option, :opt -> Shell command option. Left unchanged.

:file_path, :path -> A Bourne shell-escaped file path.

:stdout, :stdin -> Same as :file_path, but with a “>”, respectively a “>” character slapped in front of it to indicate STDOUT/STDIN.

:single_quote, :sq -> Value gets surrounded by single quotes and escaped as is appropriate for the Bourne shell.

:double_quote, :dq -> Value gets surrounded by double quotes and escaped as is appropriate for the Bourne shell.

:backticks, :substitute_cmd, :cmd_subst, :substitute -> Bourne shell command substitution. Value gets surrounded by backtick characters but otherwise left unchanged.

In case you want to use the same symbol more than once in order to construct a command, you may use more than one hash for arguments.

  • Examples

    - >> album = String.new("/home/me/Music/Miles Davis/Bitches' Brew")
    (...)
    - >> puts ShellQuotes.bourne_escape(:command => 'ls', :file_path => album)
    ls /home/me/Music/Miles\ Davis/Bitches\'\ Brew 
    - >> puts ShellQuotes.bourne_escape(:command => 'herrie', :stdin => album + '02 John Mclaughlin.flac')
    - herrie < /home/me/Music/Miles\ Davis/Bitches\'\ Brew/02\ John\ McLaughlin.flac 
    - >> puts ShellQuotes.bourne_escape({ :cmd => "ls ", :path => "/home/me/Music/Thelonius Monk/" }, { :path => "/home/me/Music/Miles Davis/" })
    ls  /home/me/Music/Thelonius\ Monk/ /home/me/Music/Miles\ Davis/ 
    - >> puts album.bourne_escape_file_path!
    /home/me/Music/Miles\ Davis/Bitches\'\ Brew 
    - >> system ShellQuotes.bourne_escape(:cmd => 'ls', :opt => '-l', :file_path => album)
    - >> system ShellQuotes.bourne_escape(:cmd => 'ls', :opt => '-l', :file_path => album)
    (...)
    true
  • Arguments

Hash (One or more)

# File lib/shell_quotes.rb, line 141
def ShellQuotes.bourne_escape(*args)
        ShellQuotes.escape(shell = :bourne, *args)
end
csh_escape(*args) click to toggle source

Similar to bourne_escape, but for CSH shell.

# File lib/shell_quotes.rb, line 153
def ShellQuotes.csh_escape(*args)
        ShellQuotes.escape(shell = :csh, *args)
end
escape(shell = :bourne, *args) click to toggle source
# File lib/shell_quotes.rb, line 22
        def ShellQuotes.escape(shell = :bourne, *args)
                escaped = String.new
                args.each { |arg|
                        arg.keys.each_with_index { |key, index|
                                case arg.keys[index]
                                        when :file_path, :path
                                                raise ShellQuotes::SQError,
                                                        "Value for \":#{(key).to_s}\" should be of String or Dir."\
                                                        unless ((arg[key]).is_a?(String) || (arg[key]).is_a?(Dir))
                                        when :variable
                                                raise ShellQuotes::SQError,
                                                        "Value for \":#{(key).to_s}\" should be of String or Array."\
                                                        unless ((arg[key]).is_a?(String) ||(arg[key]).is_a?(Array))
                                                raise ShellQuotes::SQError,
'Hash argument needs to have both a ":variable" and a ":double_quote" or ":dq" key.'\
                                                        unless (arg.has_key?(:double_quote) || arg.has_key?(:dq))
                                        when :replace
                                                raise ShellQuotes::SQError,
'Hash argument needs to have both a ":replace" and a ":single_quote" or ":sq" key.'\
                                                        unless (arg.has_key?(:single_quote) || arg.has_key?(:sq))
                                        else
                                                raise ShellQuotes::SQError,
                                                        "Value for \":#{(key).to_s}\" should be of String."\
                                                        unless (arg[key]).is_a?(String)
                                end
                        
                                case arg.keys[index]
                                        when :pass, :command, :cmd, :option, :opt #-- PASS
                                                #++
                                                escaped << arg[key] + ' '
                                        when :file_path, :path
                                                escaped << ((arg[key]).is_a?(String)\
                                                        ? (eval "arg[key].#{shell}_escape_file_path") + ' '\
                                                        : (eval "arg[key].#{shell}_escaped_file_path") + ' ')
                                        when :stdout
                                                escaped <<
                                                        '> ' + (eval "arg[key].#{shell}_escape_file_path") + ' '
                                        when :stdin
                                                escaped <<
                                                        '< ' + (eval "arg[key].#{shell}_escape_file_path") + ' '
                                        when :arg
                                                escaped << (eval "arg[key].#{shell}_escape_arg")
                                        when :single_quote, :sq
                                                (arg[:replace]).is_a?(String)\
                                                        ? escaped << (eval\
                                "(arg[key]).#{shell}_single_quoted(replacement = arg[:replace])")\
                                                        + ' '\
                                                        : escaped <<
                                                                (eval "(arg[key]).#{shell}_single_quoted") + ' '
                                        when :double_quote, :dq
                                                ((arg[:variable]).is_a?(String) ||\
                                                        arg[:variable].is_a?(Array))\
                                                        ? escaped <<\
                (eval "(arg[key]).#{shell}_double_quoted(variable = arg[:variable])")\
                                                                + ' '\
                                                        : escaped <<
                                                                (eval "(arg[key]).#{shell}_double_quoted") + ' '
                                        when :backticks, :cmd_substitute, :cmd_subst, :substitute
                                                escaped <<
                                                        (eval "(arg[key]).#{shell}_escape_substitute") + ' '
                                        when :replace, :variable #--      DO NOTHING
                                                #++
                                        else
                                                raise ShellQuotes::SQError,
                                                        "Unrecognized key: \":#{(key).to_s}\"."
                                end
                                }
                        }
                
                escaped
        end

Public Instance Methods

bash_escaped_entries(*arg) click to toggle source

Produces -> Array

similar to bourne_escaped_entries, but for Bash shell.

# File lib/shell_quotes.rb, line 259
def bash_escaped_entries(*arg)
        self.escaped_entries(
                arg = (arg[0].nil? ? Hash.new : arg[0]), shell = 'bash')
end
bash_escaped_file_path() click to toggle source

Produces -> String

Similar to bourne_escaped_file_path, but for Bash shell.

# File lib/shell_quotes.rb, line 208
def bash_escaped_file_path
        self.escaped_file_path(shell = 'bash')
end
bourne_escaped_entries(*arg) click to toggle source

Produces -> Array

Takes the enries in a Dir object and gives you their absolute paths, all escaped for the Bourne shell.

Options:

:grep -> Grep filter takes a regular expression, either as a String or a Regexp object.

:all -> Whether or not to show files that begin with a dot (.). Boolean. Defaults to false.

# File lib/shell_quotes.rb, line 250
def bourne_escaped_entries(*arg)
        self.escaped_entries(
                arg = (arg[0].nil? ? Hash.new : arg[0]), shell = 'bourne')
end
bourne_escaped_file_path() click to toggle source

Produces -> String

Convenience method for the Dir class.

Takes whatever string is in +Dir path+ to represent a file path at the Bourne shell command-line.

# File lib/shell_quotes.rb, line 200
def bourne_escaped_file_path
        self.escaped_file_path(shell = 'bourne')
end
csh_escaped_entries(*arg) click to toggle source

Produces -> Array

similar to bourne_escaped_entries, but for CSH shell.

# File lib/shell_quotes.rb, line 268
def csh_escaped_entries(*arg)
        self.escaped_entries(
                arg = (arg[0].nil? ? Hash.new : arg[0]), shell = 'csh')
end
csh_escaped_file_path() click to toggle source

Produces -> String

Similar to bourne_escaped_file_path, but for CSH shell.

# File lib/shell_quotes.rb, line 216
def csh_escaped_file_path
        self.escaped_file_path(shell = 'csh')
end
escaped_entries(arg = Hash.new, shell = 'bourne') click to toggle source

Base method for bourne_escaped_entries etc.

# File lib/shell_quotes.rb, line 222
def escaped_entries(arg = Hash.new, shell = 'bourne')
        nixing = Regexp.new(
                arg[:all].is_a?(TrueClass) ? %r/^(\.[^\.]|[^\.])/ : %r/^[^\.]/)
        slash = self.path[-1] == '/' ? '' : '/'
        grepping = arg[:grep].is_a?(Regexp)\
                        ? arg[:grep]\
                        : arg[:grep].is_a?(String) ? Regexp.new(arg[:grep]) : ''
        escaped = Array.new
        filtered = (eval "entries.grep(%r/#{nixing}/).grep(%r/#{grepping}/)")
        filtered.each { |entry| escaped << (eval\
                "(\"#{self.path}#{slash}#{entry}\").#{shell}_escape_file_path")
                }
        
        escaped
end
escaped_file_path(shell = 'bourne') click to toggle source

Base method for bourne_escaped_file_path etc.

# File lib/shell_quotes.rb, line 188
def escaped_file_path(shell = 'bourne')
        escaped = self.path

        eval "escaped.#{shell}_escape_file_path!"
end