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,
lib/mini_magick/tool/mogrify_restricted.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, MogrifyRestricted, Montage, Stream

Constant Summary collapse

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, options = {}) ⇒ Tool

Returns a new instance of Tool.

Examples:

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

Parameters:

  • whiny (Boolean) —

    Whether to raise errors on exit codes different than 0.



55
56
57
58
59
60
61
 
# 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

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"



250
251
252
253
254
255
 
# 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

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

.option_methods ⇒ Object 



261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# 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

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) 


163
164
165
166
167
 
# File 'lib/mini_magick/tool.rb', line 163

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

#<<(arg) ⇒ self

Appends raw options, useful for appending image paths.

Returns:

  • (self) 


136
137
138
139
 
# File 'lib/mini_magick/tool.rb', line 136

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

#call(*args) {|Array| ... } ⇒ 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`
mogrify = MiniMagick::Tool::Mogrify.new
# build the command
mogrify.call do |stdout, stderr, status|
  # ...
end

Yields:

  • (Array) —

    Optionally yields stdout, stderr, and exit status

Returns:

  • (String) —

    Returns the output of the command



83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# 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

#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.



236
237
238
239
240
 
# File 'lib/mini_magick/tool.rb', line 236

def clone(*args)
  self << '-clone'
  self.merge!(args)
  self
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>) 


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

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>) 


124
125
126
127
128
129
 
# 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

#merge!(new_args) ⇒ self

Merges a list of raw options.

Returns:

  • (self) 


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

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"



225
226
227
228
229
230
 
# File 'lib/mini_magick/tool.rb', line 225

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) 


257
258
259
 
# File 'lib/mini_magick/tool.rb', line 257

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:



184
185
186
187
188
 
# File 'lib/mini_magick/tool.rb', line 184

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

#stdin ⇒ Object

Adds ImageMagick’s pseudo-filename ‘-` for standard input.

Examples:

identify = MiniMagick::Tool::Identify.new
identify.stdin
identify.call(stdin: image_content)
# executes `identify -` with the given standard input


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

def stdin
  self << "-"
end

#stdout ⇒ Object

Adds ImageMagick’s pseudo-filename ‘-` for standard output.

Examples:

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


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

def stdout
  self << "-"
end