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/magick.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, Magick, Mogrify, MogrifyRestricted, Montage, Stream

Constant Summary collapse

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

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.



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

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"



259
260
261
262
263
264
 
# File 'lib/mini_magick/tool.rb', line 259

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

Instance Attribute Details

#args ⇒ Object (readonly) 



45
46
47
 
# File 'lib/mini_magick/tool.rb', line 45

def args
  @args
end

#name ⇒ Object (readonly) 



45
46
47
 
# File 'lib/mini_magick/tool.rb', line 45

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.



33
34
35
36
37
38
39
40
41
42
 
# File 'lib/mini_magick/tool.rb', line 33

def self.new(*args)
  instance = super(*args)

  if block_given?
    yield instance
    instance.call
  else
    instance
  end
end

.option_methods ⇒ Object 



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/mini_magick/tool.rb', line 266

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) 


172
173
174
175
176
 
# File 'lib/mini_magick/tool.rb', line 172

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

#<<(arg) ⇒ self

Appends raw options, useful for appending image paths.

Returns:

  • (self) 


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

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



81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/mini_magick/tool.rb', line 81

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.



245
246
247
248
249
 
# File 'lib/mini_magick/tool.rb', line 245

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


107
108
109
 
# File 'lib/mini_magick/tool.rb', line 107

def command
  [*executable, *args]
end

#executable ⇒ Array<String>

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

Examples:

MiniMagick.configure { |config| config.cli = :graphicsmagick }
identify = MiniMagick::Tool::Identify.new
identify.executable #=> ["gm", "identify"]
MiniMagick.configure do |config|
  config.cli = :graphicsmagick
  config.cli_prefix = ['firejail', '--force']
end
identify = MiniMagick::Tool::Identify.new
identify.executable #=> ["firejail", "--force", "gm", "identify"]

Returns:

  • (Array<String>) 


131
132
133
134
135
136
137
138
 
# File 'lib/mini_magick/tool.rb', line 131

def executable
  exe = [name]
  exe.unshift "magick" if MiniMagick.imagemagick7? && name != "magick"
  exe.unshift "gm" if MiniMagick.graphicsmagick?
  exe.unshift File.join(MiniMagick.cli_path, exe.shift) if MiniMagick.cli_path
  Array(MiniMagick.cli_prefix).reverse_each { |p| exe.unshift p } if MiniMagick.cli_prefix
  exe
end

#merge!(new_args) ⇒ self

Merges a list of raw options.

Returns:

  • (self) 


155
156
157
158
 
# File 'lib/mini_magick/tool.rb', line 155

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"



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

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



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

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


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

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


223
224
225
 
# File 'lib/mini_magick/tool.rb', line 223

def stdout
  self << "-"
end