class MiniMagick::Tool
Abstract class that wraps command-line tools. It shouldn't be used directly, but through one of its subclasses (e.g. {MiniMagick::Tool::Mogrify}). Use this class if you want to be closer to the metal and execute ImageMagick commands directly, but still with a nice Ruby interface.
@example
MiniMagick::Tool::Mogrify.new do |builder| builder.resize "500x500" builder << "path/to/image.jpg" end
Constants
- CREATION_OPERATORS
Attributes
@private
@private
Public Class Methods
Aside from classic instantiation, it also accepts a block, and then executes the command in the end.
@example
version = MiniMagick::Tool::Identify.new { |b| b.version } puts version
@return [MiniMagick::Tool, String] If no block is given, returns an
instance of the tool, if block is given, returns the output of the command.
# File lib/mini_magick/tool.rb, line 35 def self.new(*args) instance = super(*args) if block_given? yield instance instance.call else instance end end
@param whiny [Boolean] Whether to raise errors on exit codes different
than 0
@example
MiniMagick::Tool::Identify.new(whiny: false) do |identify| identify.help # returns exit status 1, which would otherwise throw an error end
# File lib/mini_magick/tool.rb, line 55 def initialize(name, options = {}) warn "MiniMagick::Tool.new(false) is deprecated and will be removed in MiniMagick 5, use MiniMagick::Tool.new(whiny: false) instead." if !options.is_a?(Hash) @name = name @args = [] @whiny = options.is_a?(Hash) ? options.fetch(:whiny, MiniMagick.whiny) : options end
# File lib/mini_magick/tool.rb, line 261 def self.option_methods @option_methods ||= ( tool = new(whiny: false) tool << "-help" help_page = tool.call(stderr: false) cli_options = help_page.scan(/^\s+-[a-z\-]+/).map(&:strip) if tool.name == "mogrify" && MiniMagick.graphicsmagick? # These options were undocumented before 2015-06-14 (see gm bug 302) cli_options |= %w[-box -convolve -gravity -linewidth -mattecolor -render -shave] end cli_options.map { |o| o[1..-1].tr('-','_') } ) end
Public Instance Methods
Changes the last operator to its “plus” form.
@example
MiniMagick::Tool::Mogrify.new do |mogrify| mogrify.antialias.+ mogrify.distort.+("Perspective", "0,0,4,5 89,0,45,46") end # executes `mogrify +antialias +distort Perspective '0,0,4,5 89,0,45,46'`
@return [self]
# File lib/mini_magick/tool.rb, line 163 def +(*values) args[-1] = args[-1].sub(/^-/, '+') self.merge!(values) self end
Appends raw options, useful for appending image paths.
@return [self]
# File lib/mini_magick/tool.rb, line 136 def <<(arg) args << arg.to_s self end
Executes the command that has been built up.
@example
mogrify = MiniMagick::Tool::Mogrify.new mogrify.resize("500x500") mogrify << "path/to/image.jpg" mogrify.call # executes `mogrify -resize 500x500 path/to/image.jpg`
@example
mogrify = MiniMagick::Tool::Mogrify.new # build the command mogrify.call do |stdout, stderr, status| # ... end
@yield [Array] Optionally yields stdout, stderr, and exit status
@return [String] Returns the output of the command
# File lib/mini_magick/tool.rb, line 83 def call(*args) options = args[-1].is_a?(Hash) ? args.pop : {} warn "Passing whiny to MiniMagick::Tool#call is deprecated and will be removed in MiniMagick 5, use MiniMagick::Tool.new(whiny: false) instead." if args.any? whiny = args.fetch(0, @whiny) options[:whiny] = whiny options[:stderr] = false if block_given? shell = MiniMagick::Shell.new stdout, stderr, status = shell.run(command, options) yield stdout, stderr, status if block_given? stdout.chomp("\n") end
This option is a valid ImageMagick option, but it's also a Ruby method, so we need to override it so that it correctly acts as an option method.
# File lib/mini_magick/tool.rb, line 236 def clone(*args) self << '-clone' self.merge!(args) self end
The currently built-up command.
@return [Array<String>]
@example
mogrify = MiniMagick::Tool::Mogrify.new mogrify.resize "500x500" mogrify.contrast mogrify.command #=> ["mogrify", "-resize", "500x500", "-contrast"]
# File lib/mini_magick/tool.rb, line 109 def command [*executable, *args] end
The executable used for this tool. Respects {MiniMagick::Configuration#cli} and {MiniMagick::Configuration#cli_path}.
@return [Array<String>]
@example
MiniMagick.configure { |config| config.cli = :graphicsmagick } identify = MiniMagick::Tool::Identify.new identify.executable #=> ["gm", "identify"]
# File lib/mini_magick/tool.rb, line 124 def executable exe = [name] exe.unshift "gm" if MiniMagick.graphicsmagick? exe.unshift File.join(MiniMagick.cli_path, exe.shift) if MiniMagick.cli_path exe end
Merges a list of raw options.
@return [self]
# File lib/mini_magick/tool.rb, line 146 def merge!(new_args) new_args.each { |arg| self << arg } self end
Any undefined method will be transformed into a CLI option
mogrify = MiniMagick::Tool.new("mogrify") mogrify.adaptive_blur("...") mogrify.foo_bar mogrify.command.join(" ") "mogrify -adaptive-blur ... -foo-bar"
# File lib/mini_magick/tool.rb, line 250 def method_missing(name, *args) option = "-#{name.to_s.tr('_', '-')}" self << option self.merge!(args) self end
# File lib/mini_magick/tool.rb, line 257 def respond_to_missing?(method_name, include_private = false) true end
Create an ImageMagick stack in the command (surround.
@example
MiniMagick::Tool::Convert.new do |convert| convert << "wand.gif" convert.stack do |stack| stack << "wand.gif" stack.rotate(30) end convert.append.+ convert << "images.gif" end # executes `convert wand.gif \( wizard.gif -rotate 30 \) +append images.gif`
# File lib/mini_magick/tool.rb, line 184 def stack self << "(" yield self self << ")" end
Adds ImageMagick's pseudo-filename `-` for standard input.
@example
identify = MiniMagick::Tool::Identify.new identify.stdin identify.call(stdin: image_content) # executes `identify -` with the given standard input
# File lib/mini_magick/tool.rb, line 199 def stdin self << "-" end
Adds ImageMagick's pseudo-filename `-` for standard output.
@example
content = MiniMagick::Tool::Convert.new do |convert| convert << "input.jpg" convert.auto_orient convert.stdout end # executes `convert input.jpg -auto-orient -` which returns file contents
# File lib/mini_magick/tool.rb, line 214 def stdout self << "-" end