module Chef::Mixin::ShellOut

Public Instance Methods

a_to_s(*args) click to toggle source

Helper for subclasses to convert an array of string args into a string. It will compact nil or empty strings in the array and will join the array elements with spaces, without introducing any double spaces for nil/empty elements.

@param args [String] variable number of string arguments @return [String] nicely concatenated string or empty string

# File lib/chef/mixin/shell_out.rb, line 140
def a_to_s(*args)
  # can't quite deprecate this yet
  #Chef.deprecated(:package_misc, "a_to_s is deprecated use shell_out_compact or shell_out_compact_timeout instead")
  args.flatten.reject { |i| i.nil? || i == "" }.map(&:to_s).join(" ")
end
clean_array(*args) click to toggle source

Helper for subclasses to reject nil out of an array. It allows using the array form of #shell_out (which avoids the need to surround arguments with quote marks to deal with shells).

Usage:

shell_out!(*clean_array("useradd", universal_options, useradd_options, new_resource.username))

universal_options and useradd_options can be nil, empty array, empty string, strings or arrays and the result makes sense.

keeping this separate from #shell_out!() makes it a bit easier to write expectations against the #shell_out args and be able to omit nils and such in the tests (and to test that the nils are being rejected correctly).

@param args [String] variable number of string arguments @return [Array] array of strings with nil and null string rejection

# File lib/chef/mixin/shell_out.rb, line 162
def clean_array(*args)
  args.flatten.compact.map(&:to_s)
end
shell_out(*args, **options) click to toggle source

we use 'en_US.UTF-8' by default because we parse localized strings in English as an API and generally must support UTF-8 unicode.

# File lib/chef/mixin/shell_out.rb, line 105
def shell_out(*args, **options)
  options = options.dup
  env_key = options.has_key?(:env) ? :env : :environment
  options[env_key] = {
    "LC_ALL" => Chef::Config[:internal_locale],
    "LANGUAGE" => Chef::Config[:internal_locale],
    "LANG" => Chef::Config[:internal_locale],
    env_path => sanitized_path,
  }.update(options[env_key] || {})
  shell_out_command(*args, **options)
end
shell_out!(*command_args) click to toggle source

call #shell_out (using en_US.UTF-8) and raise errors

# File lib/chef/mixin/shell_out.rb, line 118
def shell_out!(*command_args)
  cmd = shell_out(*command_args)
  cmd.error!
  cmd
end
shell_out_compact(*args, **options) click to toggle source

PREFERRED APIS:

#shell_out_compact and #shell_out_compact! flatten their array arguments and remove nils and pass the resultant array to shell_out. this actually eliminates spaces-in-args bugs because this:

#shell_out!(“command #{arg}”)

becomes two arguments if arg has spaces and requires quotations:

#shell_out!(“command '#{arg}'”)

using #shell_out_compact! this becomes:

#shell_out_compact!(“command”, arg)

and spaces in the arg just works and it does not become two arguments (and the shell quoting around the argument must actually be removed).

there's also an implicit join between all the array elements, and nested arrays are flattened which means that odd where-do-i-put-the-spaces options handling just works, and instead of this:

opts = ""                     # needs to be empty string for when foo and bar are both missing
opts << " -foo" if needs_foo? # needs the leading space on both of these
opts << " -bar" if needs_bar?
shell_out!("cmd#{opts}")      # have to think way too hard about why there's no space here

becomes:

opts = []
opts << "-foo" if needs_foo?
opts << "-bar" if needs_bar?
shell_out_compact!("cmd", opts)

and opts can be an empty array or nil and it'll work out fine.

generally its best to use #shell_out_compact! in code and setup expectations on #shell_out! in tests

# File lib/chef/mixin/shell_out.rb, line 64
def shell_out_compact(*args, **options)
  if options.empty?
    shell_out(*clean_array(*args))
  else
    shell_out(*clean_array(*args), **options)
  end
end
shell_out_compact!(*args, **options) click to toggle source
# File lib/chef/mixin/shell_out.rb, line 72
def shell_out_compact!(*args, **options)
  if options.empty?
    shell_out!(*clean_array(*args))
  else
    shell_out!(*clean_array(*args), **options)
  end
end
shell_out_compact_timeout(*args, **options) click to toggle source

helper sugar for resources that support passing timeouts to #shell_out

# File lib/chef/mixin/shell_out.rb, line 82
def shell_out_compact_timeout(*args, **options)
  raise "object is not a resource that supports timeouts" unless respond_to?(:new_resource) && new_resource.respond_to?(:timeout)
  options_dup = options.dup
  options_dup[:timeout] = new_resource.timeout if new_resource.timeout
  options_dup[:timeout] = 900 unless options_dup.key?(:timeout)
  shell_out_compact(*args, **options_dup)
end
shell_out_compact_timeout!(*args, **options) click to toggle source
# File lib/chef/mixin/shell_out.rb, line 90
def shell_out_compact_timeout!(*args, **options)
  raise "object is not a resource that supports timeouts" unless respond_to?(:new_resource) && new_resource.respond_to?(:timeout)
  options_dup = options.dup
  options_dup[:timeout] = new_resource.timeout if new_resource.timeout
  options_dup[:timeout] = 900 unless options_dup.key?(:timeout)
  shell_out_compact!(*args, **options_dup)
end
shell_out_with_systems_locale(*command_args) click to toggle source
# File lib/chef/mixin/shell_out.rb, line 124
def shell_out_with_systems_locale(*command_args)
  shell_out_command(*command_args)
end
shell_out_with_systems_locale!(*command_args) click to toggle source
# File lib/chef/mixin/shell_out.rb, line 128
def shell_out_with_systems_locale!(*command_args)
  cmd = shell_out_with_systems_locale(*command_args)
  cmd.error!
  cmd
end

Private Instance Methods

env_path() click to toggle source
# File lib/chef/mixin/shell_out.rb, line 183
def env_path
  if Chef::Platform.windows?
    "Path"
  else
    "PATH"
  end
end
io_for_live_stream() click to toggle source
# File lib/chef/mixin/shell_out.rb, line 175
def io_for_live_stream
  if STDOUT.tty? && !Chef::Config[:daemon] && Chef::Log.debug?
    STDOUT
  else
    nil
  end
end
shell_out_command(*command_args) click to toggle source
# File lib/chef/mixin/shell_out.rb, line 168
def shell_out_command(*command_args)
  cmd = Mixlib::ShellOut.new(*command_args)
  cmd.live_stream ||= io_for_live_stream
  cmd.run_command
  cmd
end