Class: MiniMagick::Tool

Inherits:
Object
  • Object
show all
Defined in:
lib/mini_magick/tool.rb

Overview

Class that wraps command-line tools directly, as opposed MiniMagick::Image which is more high-level.

Examples:

MiniMagick.mogrify do |mogrify|
  mogrify.resize "500x500"
  mogrify << "path/to/image.jpg"
end

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.identify(errors: false) do |identify|
  identify.help # returns exit status 1, which would otherwise throw an error
end

Parameters:

  • name (String)
  • options (Hash)

Options Hash (**options):

  • :errors (Boolean) —

    Whether to raise errors on non-zero exit codes.

  • :warnings (Boolean) —

    Whether to print warnings to stderrr.

  • :stdin (String, IO) —

    Content to send to standard input stream, either a string or a readable IO object.



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

def initialize(name, **options)
  @name = name
  @args = []
  @options = 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"


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

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

Instance Attribute Details

#args ⇒ Object (readonly) 



42
43
44
 
# File 'lib/mini_magick/tool.rb', line 42

def args
  @args
end

#name ⇒ Object (readonly) 



42
43
44
 
# File 'lib/mini_magick/tool.rb', line 42

def name
  @name
end

Class Method Details

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

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

Examples:

puts MiniMagick.identify(&: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.



30
31
32
33
34
35
36
37
38
39
 
# File 'lib/mini_magick/tool.rb', line 30

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

  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.mogrify 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(**options) {|Array| ... } ⇒ String

Executes the command that has been built up.

Examples:

mogrify = MiniMagick.mogrify
mogrify.resize("500x500")
mogrify << "path/to/image.jpg"
mogrify.call # executes `mogrify -resize 500x500 path/to/image.jpg`
mogrify = MiniMagick.mogrify
# 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
 
# File 'lib/mini_magick/tool.rb', line 81

def call(**options)
  options = @options.merge(options)
  options[:warnings] = 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.



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

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

#command ⇒ Array<String>

The currently built-up command.

Examples:

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

Returns:

  • (Array<String>) 


103
104
105
 
# File 'lib/mini_magick/tool.rb', line 103

def command
  [*executable, *args]
end

#executable ⇒ Array<String>

The executable used for this tool. Respects Configuration#cli_prefix.

Examples:

identify = MiniMagick.identify
identify.executable #=> ["magick", "identify"]
MiniMagick.configure do |config|
  config.cli_prefix = ['firejail', '--force']
end
identify = MiniMagick.identify
identify.executable #=> ["firejail", "--force", "magick", "identify"]

Returns:

  • (Array<String>) 


124
125
126
127
128
129
 
# File 'lib/mini_magick/tool.rb', line 124

def executable
  exe = Array(MiniMagick.cli_prefix).dup
  exe << "magick" if MiniMagick.imagemagick7? && name != "magick"
  exe << "gm" if MiniMagick.graphicsmagick
  exe << name
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

Examples:

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


232
233
234
235
236
237
 
# File 'lib/mini_magick/tool.rb', line 232

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.convert 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
189
190
191
192
193
194
 
# File 'lib/mini_magick/tool.rb', line 184

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.identify
identify.stdin
identify.call(stdin: image_content)
# executes `identify -` with the given standard input


205
206
207
 
# File 'lib/mini_magick/tool.rb', line 205

def stdin
  self << "-"
end

#stdout ⇒ Object

Adds ImageMagick's pseudo-filename - for standard output.

Examples:

content = MiniMagick.convert do |convert|
  convert << "input.jpg"
  convert.auto_orient
  convert.stdout
end
# executes `convert input.jpg -auto-orient -` which returns file contents


220
221
222
 
# File 'lib/mini_magick/tool.rb', line 220

def stdout
  self << "-"
end