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:

  • name (String)
  • options (Hash) (defaults to: {})

Options Hash (options):

  • :whiny (Boolean) —

    Whether to raise errors on non-zero exit codes.



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

Examples:

mogrify = MiniMagick::Tool.new("mogrify")
mogrify.adaptive_blur("...")
mogrify.foo_bar
mogrify.command.join(" ") # => "mogrify -adaptive-blur ... -foo-bar"


269
270
271
272
273
274
 
# File 'lib/mini_magick/tool.rb', line 269

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 



276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/mini_magick/tool.rb', line 276

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) 


174
175
176
177
178
 
# File 'lib/mini_magick/tool.rb', line 174

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

#<<(arg) ⇒ self

Appends raw options, useful for appending image paths.

Returns:

  • (self) 


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

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.



254
255
256
257
258
 
# File 'lib/mini_magick/tool.rb', line 254

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


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

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) 


157
158
159
160
 
# File 'lib/mini_magick/tool.rb', line 157

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

#operator ⇒ Object

Define creator operator methods

Examples:

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


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

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

#stack(*args) {|_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:



195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/mini_magick/tool.rb', line 195

def stack(*args)
  self << "("
  args.each do |value|
    case value
    when Hash   then value.each { |key, value| send(key, *value) }
    when String then self << value
    end
  end
  yield self if block_given?
  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


216
217
218
 
# File 'lib/mini_magick/tool.rb', line 216

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


231
232
233
 
# File 'lib/mini_magick/tool.rb', line 231

def stdout
  self << "-"
end