Class: MiniMagick::Tool

Inherits:
Object
  • Object
show all
Defined in:
lib/mini_magick/tool.rb,
lib/mini_magick/tool/import.rb,
lib/mini_magick/tool/stream.rb,
lib/mini_magick/tool/display.rb,
lib/mini_magick/tool/animate.rb,
lib/mini_magick/tool/compare.rb,
lib/mini_magick/tool/montage.rb,
lib/mini_magick/tool/mogrify.rb,
lib/mini_magick/tool/conjure.rb,
lib/mini_magick/tool/convert.rb,
lib/mini_magick/tool/identify.rb,
lib/mini_magick/tool/composite.rb

Overview

Abstract class that wraps command-line tools. It shouldn't be used directly, but through one of its subclasses (e.g. 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.

Examples:

MiniMagick::Tool::Mogrify.new do |builder|
  builder.resize "500x500"
  builder << "path/to/image.jpg"
end

Defined Under Namespace

Classes: Animate, Compare, Composite, Conjure, Convert, Display, Identify, Import, Mogrify, Montage, Stream

Constant Summary collapse

CREATION_OPERATORS =
%w[
xc canvas logo rose gradient radial-gradient plasma pattern label caption
text

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, whiny = MiniMagick.whiny) ⇒ Tool

Returns a new instance of Tool

Examples:

MiniMagick::Tool::Identify.new(false) do |identify|
  identify.help # returns exit status 1, which would otherwise throw an error
end

Parameters:

  • whiny (Boolean) (defaults to: MiniMagick.whiny)

    Whether to raise errors on exit codes different than 0.



55
56
57
58
59
# File 'lib/mini_magick/tool.rb', line 55

def initialize(name, whiny = MiniMagick.whiny)
  @name  = name
  @whiny = whiny
  @args  = []
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args) ⇒ Object

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"



206
207
208
209
210
211
# File 'lib/mini_magick/tool.rb', line 206

def method_missing(name, *args)
  option = "-#{name.to_s.tr('_', '-')}"
  self << option
  self.merge!(args)
  self
end

Class Method Details

.new(*args) ⇒ MiniMagick::Tool, String

Aside from classic instantiation, it also accepts a block, and then executes the command in the end.

Examples:

version = MiniMagick::Tool::Identify.new { |b| b.version }
puts version

Returns:

  • (MiniMagick::Tool, String)

    If no block is given, returns an instance of the tool, if block is given, returns the output of the command.



35
36
37
38
39
40
41
42
43
44
# 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

.option_methodsObject



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
# File 'lib/mini_magick/tool.rb', line 217

def self.option_methods
  @option_methods ||= (
    tool = new
    tool << "-help"
    help_page = tool.call(false, 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

Instance Method Details

#+(*values) ⇒ self

Changes the last operator to its "plus" form.

Examples:

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'`

Returns:

  • (self)


147
148
149
150
151
# File 'lib/mini_magick/tool.rb', line 147

def +(*values)
  args[-1] = args[-1].sub(/^-/, '+')
  self.merge!(values)
  self
end

#<<(arg) ⇒ self

Appends raw options, useful for appending image paths.

Returns:

  • (self)


120
121
122
123
# File 'lib/mini_magick/tool.rb', line 120

def <<(arg)
  args << arg.to_s
  self
end

#call(whiny = @whiny, options = {}) ⇒ String

Executes the command that has been built up.

Examples:

mogrify = MiniMagick::Tool::Mogrify.new
mogrify.resize("500x500")
mogrify << "path/to/image.jpg"
mogrify.call # executes `mogrify -resize 500x500 path/to/image.jpg`

Parameters:

  • whiny (Boolean) (defaults to: @whiny)

    Whether you want an error to be raised when ImageMagick returns an exit code of 1. You may want this because some ImageMagick's commands (identify -help) return exit code 1, even though no error happened.

Returns:

  • (String)

    Output of the command



77
78
79
80
# File 'lib/mini_magick/tool.rb', line 77

def call(whiny = @whiny, options = {})
  shell = MiniMagick::Shell.new
  shell.run(command, options.merge(whiny: whiny)).strip
end

#clone(*args) ⇒ Object

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.



192
193
194
195
196
# File 'lib/mini_magick/tool.rb', line 192

def clone(*args)
  self << '-clone'
  self.merge!(args)
  self
end

#commandArray<String>

The currently built-up command.

Examples:

mogrify = MiniMagick::Tool::Mogrify.new
mogrify.resize "500x500"
mogrify.contrast
mogrify.command #=> ["mogrify", "-resize", "500x500", "-contrast"]

Returns:

  • (Array<String>)


93
94
95
# File 'lib/mini_magick/tool.rb', line 93

def command
  [*executable, *args]
end

#executableArray<String>

The executable used for this tool. Respects Configuration#cli and Configuration#cli_path.

Examples:

MiniMagick.configure { |config| config.cli = :graphicsmagick }
identify = MiniMagick::Tool::Identify.new
identify.executable #=> ["gm", "identify"]

Returns:

  • (Array<String>)


108
109
110
111
112
113
# File 'lib/mini_magick/tool.rb', line 108

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

#merge!(new_args) ⇒ self

Merges a list of raw options.

Returns:

  • (self)


130
131
132
133
# File 'lib/mini_magick/tool.rb', line 130

def merge!(new_args)
  new_args.each { |arg| self << arg }
  self
end

#operatorObject

Define creator operator methods

mogrify = MiniMagick::Tool.new("mogrify") mogrify.canvas("khaki") mogrify.command.join(" ") #=> "mogrify canvas:khaki"



181
182
183
184
185
186
# File 'lib/mini_magick/tool.rb', line 181

CREATION_OPERATORS.each do |operator|
  define_method(operator.gsub('-', '_')) do |value = nil|
    self << "#{operator}:#{value}"
    self
  end
end

#respond_to_missing?(method_name, include_private = false) ⇒ Boolean

Returns:

  • (Boolean)


213
214
215
# File 'lib/mini_magick/tool.rb', line 213

def respond_to_missing?(method_name, include_private = false)
  true
end

#stack {|_self| ... } ⇒ Object

Create an ImageMagick stack in the command (surround.

Examples:

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`

Yields:

  • (_self)

Yield Parameters:



168
169
170
171
172
# File 'lib/mini_magick/tool.rb', line 168

def stack
  self << "("
  yield self
  self << ")"
end