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/animate.rb,
lib/mini_magick/tool/compare.rb,
lib/mini_magick/tool/conjure.rb,
lib/mini_magick/tool/convert.rb,
lib/mini_magick/tool/display.rb,
lib/mini_magick/tool/mogrify.rb,
lib/mini_magick/tool/montage.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 tile pattern label
  caption text
]

Instance Attribute Summary collapse

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"



196
197
198
199
200
201
 
# File 'lib/mini_magick/tool.rb', line 196

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

Instance Attribute Details

#args ⇒ Object (readonly) 



47
48
49
 
# File 'lib/mini_magick/tool.rb', line 47

def args
  @args
end

#name ⇒ Object (readonly) 



47
48
49
 
# File 'lib/mini_magick/tool.rb', line 47

def name
  @name
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

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

#command ⇒ Array<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

#executable ⇒ Array<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

#operator ⇒ Object

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) 


203
204
205
 
# File 'lib/mini_magick/tool.rb', line 203

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