rmagick 4.1.0.rc2 → 4.1.0

data/lib/rmagick/version.rb

@@ -1,5 +1,5 @@
 module Magick
-  VERSION = '4.1.0.rc2'
+  VERSION = '4.1.0'
   MIN_RUBY_VERSION = '2.3.0'
   MIN_IM_VERSION = '6.7.7'
 end

data/lib/rmagick_internal.rb

@@ -19,6 +19,7 @@ if RUBY_PLATFORM =~ /mingw/i
 end
 
 require 'English'
+require 'observer'
 require 'RMagick2.so'
 
 module Magick
@@ -28,6 +29,29 @@ module Magick
   IMAGEMAGICK_VERSION = Magick::Magick_version.split[1].split('-').first
 
   class << self
+    # Describes the image formats supported by ImageMagick.
+    # If the optional block is present, calls the block once for each image format.
+    # The first argument, +k+, is the format name. The second argument, +v+, is the
+    # properties string described below.
+    #
+    # - +B+ is "*" if the format has native blob support, or " " otherwise.
+    # - +R+ is "r" if ImageMagick can read that format, or "-" otherwise.
+    # - +W+ is "w" if ImageMagick can write that format, or "-" otherwise.
+    # - +A+ is "+" if the format supports multi-image files, or "-" otherwise.
+    #
+    # @overload formats
+    #   @return [Hash] the formats hash
+    #
+    # @overload formats
+    #   @yield [k, v]
+    #   @yieldparam k [String] the format name
+    #   @yieldparam v [String] the properties string
+    #   @return [Magick]
+    #
+    # @example
+    #   p Magick.formats
+    #   => {"3FR"=>" r-+", "3G2"=>" r-+", "3GP"=>" r-+", "A"=>"*rw+",
+    #   ...
     def formats
       @formats ||= init_formats
 
@@ -39,7 +63,26 @@ module Magick
       end
     end
 
-    # remove reference to the proc at exit
+    # If the Magick module attribute +trace_proc+ is set to a Proc object,
+    # RMagick calls the proc whenever an image is created or destroyed.
+    #
+    # You can use this proc to keep track of which images your program has created
+    # and which have been destroyed.
+    #
+    # @param p [Proc] The proc object.
+    #   The following value will be passed into the proc object.
+    #   - +which+ - A symbol that indicates which operation the proc is being called for.
+    #     If the proc is called for an image creation, the value is +:c+.
+    #     If called for an image destruction, the value is +:d+.
+    #   - +description+ - A string describing the image. This is the same string that
+    #     would be returned by calling the image's inspect method.
+    #   - +id+ - A unique identifier for the image. This identifier is not the same as the object's +object_id+.
+    #   - +method+ - The name of the method responsible for creating or destroying the image.
+    #
+    # @example
+    #   Magick.trace_proc = proc do |which, description, id, method|
+    #     ...
+    #   end
     def trace_proc=(p)
       m = Mutex.new
       m.synchronize do
@@ -67,12 +110,14 @@ module Magick
 
   class Geometry
     FLAGS = ['', '%', '!', '<', '>', '@', '^']
-    RFLAGS = { '%' => PercentGeometry,
-               '!' => AspectGeometry,
-               '<' => LessGeometry,
-               '>' => GreaterGeometry,
-               '@' => AreaGeometry,
-               '^' => MinimumGeometry }
+    RFLAGS = {
+      '%' => PercentGeometry,
+      '!' => AspectGeometry,
+      '<' => LessGeometry,
+      '>' => GreaterGeometry,
+      '@' => AreaGeometry,
+      '^' => MinimumGeometry
+    }
 
     attr_accessor :width, :height, :x, :y, :flag
 
@@ -131,7 +176,7 @@ module Magick
       str = ''
       if @width > 0
         fmt = @width.truncate == @width ? '%d' : '%.2f'
-        str << format(fmt, @width)
+        str << sprintf(fmt, @width)
         str << '%' if @flag == PercentGeometry
       end
 
@@ -139,10 +184,10 @@ module Magick
 
       if @height > 0
         fmt = @height.truncate == @height ? '%d' : '%.2f'
-        str << format(fmt, @height)
+        str << sprintf(fmt, @height)
         str << '%' if @flag == PercentGeometry
       end
-      str << format('%+d%+d', @x, @y) if @x != 0 || @y != 0
+      str << sprintf('%+d%+d', @x, @y) if @x != 0 || @y != 0
       str << FLAGS[@flag.to_i] if @flag != PercentGeometry
       str
     end
@@ -233,7 +278,7 @@ module Magick
     # Apply coordinate transformations to support scaling (s), rotation (r),
     # and translation (t). Angles are specified in radians.
     def affine(sx, rx, ry, sy, tx, ty)
-      primitive 'affine ' + format('%g,%g,%g,%g,%g,%g', sx, rx, ry, sy, tx, ty)
+      primitive 'affine ' + sprintf('%g,%g,%g,%g,%g,%g', sx, rx, ry, sy, tx, ty)
     end
 
     # Set alpha (make transparent) in image according to the specified
@@ -241,13 +286,15 @@ module Magick
     def alpha(x, y, method)
       Kernel.raise ArgumentError, 'Unknown paint method' unless PAINT_METHOD_NAMES.key?(method.to_i)
       name = Gem::Version.new(Magick::IMAGEMAGICK_VERSION) > Gem::Version.new('7.0.0') ? 'alpha ' : 'matte '
-      primitive name + format('%g,%g, %s', x, y, PAINT_METHOD_NAMES[method.to_i])
+      primitive name + sprintf('%g,%g, %s', x, y, PAINT_METHOD_NAMES[method.to_i])
     end
 
     # Draw an arc.
     def arc(start_x, start_y, end_x, end_y, start_degrees, end_degrees)
-      primitive 'arc ' + format('%g,%g %g,%g %g,%g',
-                                start_x, start_y, end_x, end_y, start_degrees, end_degrees)
+      primitive 'arc ' + sprintf(
+        '%g,%g %g,%g %g,%g',
+        start_x, start_y, end_x, end_y, start_degrees, end_degrees
+      )
     end
 
     # Draw a bezier curve.
@@ -257,12 +304,12 @@ module Magick
       elsif points.length.odd?
         Kernel.raise ArgumentError, 'odd number of arguments specified'
       end
-      primitive 'bezier ' + points.map! { |x| format('%g', x) }.join(',')
+      primitive 'bezier ' + points.map! { |x| sprintf('%g', x) }.join(',')
     end
 
     # Draw a circle
     def circle(origin_x, origin_y, perim_x, perim_y)
-      primitive 'circle ' + format('%g,%g %g,%g', origin_x, origin_y, perim_x, perim_y)
+      primitive 'circle ' + sprintf('%g,%g %g,%g', origin_x, origin_y, perim_x, perim_y)
     end
 
     # Invoke a clip-path defined by def_clip_path.
@@ -286,7 +333,7 @@ module Magick
     # point, replace, floodfill, filltoborder,reset
     def color(x, y, method)
       Kernel.raise ArgumentError, "Unknown PaintMethod: #{method}" unless PAINT_METHOD_NAMES.key?(method.to_i)
-      primitive 'color ' + format('%g,%g,%s', x, y, PAINT_METHOD_NAMES[method.to_i])
+      primitive 'color ' + sprintf('%g,%g,%s', x, y, PAINT_METHOD_NAMES[method.to_i])
     end
 
     # Specify EITHER the text decoration (none, underline, overline,
@@ -317,8 +364,10 @@ module Magick
 
     # Draw an ellipse
     def ellipse(origin_x, origin_y, width, height, arc_start, arc_end)
-      primitive 'ellipse ' + format('%g,%g %g,%g %g,%g',
-                                    origin_x, origin_y, width, height, arc_start, arc_end)
+      primitive 'ellipse ' + sprintf(
+        '%g,%g %g,%g %g,%g',
+        origin_x, origin_y, width, height, arc_start, arc_end
+      )
     end
 
     # Let anything through, but the only defined argument
@@ -384,7 +433,7 @@ module Magick
     def image(composite, x, y, width, height, image_file_path)
       Kernel.raise ArgumentError, 'Unknown composite' unless composite.is_a?(CompositeOperator)
       composite_name = composite.to_s.sub!('CompositeOp', '')
-      primitive 'image ' + format('%s %g,%g %g,%g %s', composite_name, x, y, width, height, enquote(image_file_path))
+      primitive 'image ' + sprintf('%s %g,%g %g,%g %s', composite_name, x, y, width, height, enquote(image_file_path))
     end
 
     # IM 6.5.5-8 and later
@@ -425,7 +474,7 @@ module Magick
 
     # Draw a line
     def line(start_x, start_y, end_x, end_y)
-      primitive 'line ' + format('%g,%g %g,%g', start_x, start_y, end_x, end_y)
+      primitive 'line ' + sprintf('%g,%g %g,%g', start_x, start_y, end_x, end_y)
     end
 
     # Specify drawing fill and stroke opacities. If the value is a string
@@ -447,7 +496,7 @@ module Magick
     # as the argument to the 'fill' or 'stroke' methods
     def pattern(name, x, y, width, height)
       push('defs')
-      push("pattern #{name} " + format('%g %g %g %g', x, y, width, height))
+      push("pattern #{name} " + sprintf('%g %g %g %g', x, y, width, height))
       push('graphic-context')
       yield
     ensure
@@ -458,13 +507,13 @@ module Magick
 
     # Set point to fill color.
     def point(x, y)
-      primitive 'point ' + format('%g,%g', x, y)
+      primitive 'point ' + sprintf('%g,%g', x, y)
     end
 
     # Specify the font size in points. Yes, the primitive is "font-size" but
     # in other places this value is called the "pointsize". Give it both names.
     def pointsize(points)
-      primitive 'font-size ' + format('%g', points)
+      primitive 'font-size ' + sprintf('%g', points)
     end
     alias font_size pointsize
 
@@ -475,7 +524,7 @@ module Magick
       elsif points.length.odd?
         Kernel.raise ArgumentError, 'odd number of points specified'
       end
-      primitive 'polygon ' + points.map! { |x| format('%g', x) }.join(',')
+      primitive 'polygon ' + points.map! { |x| sprintf('%g', x) }.join(',')
     end
 
     # Draw a polyline
@@ -485,7 +534,7 @@ module Magick
       elsif points.length.odd?
         Kernel.raise ArgumentError, 'odd number of points specified'
       end
-      primitive 'polyline ' + points.map! { |x| format('%g', x) }.join(',')
+      primitive 'polyline ' + points.map! { |x| sprintf('%g', x) }.join(',')
     end
 
     # Return to the previously-saved set of whatever
@@ -519,32 +568,36 @@ module Magick
 
     # Draw a rectangle
     def rectangle(upper_left_x, upper_left_y, lower_right_x, lower_right_y)
-      primitive 'rectangle ' + format('%g,%g %g,%g',
-                                      upper_left_x, upper_left_y, lower_right_x, lower_right_y)
+      primitive 'rectangle ' + sprintf(
+        '%g,%g %g,%g',
+        upper_left_x, upper_left_y, lower_right_x, lower_right_y
+      )
     end
 
     # Specify coordinate space rotation. "angle" is measured in degrees
     def rotate(angle)
-      primitive 'rotate ' + format('%g', angle)
+      primitive 'rotate ' + sprintf('%g', angle)
     end
 
     # Draw a rectangle with rounded corners
     def roundrectangle(center_x, center_y, width, height, corner_width, corner_height)
-      primitive 'roundrectangle ' + format('%g,%g,%g,%g,%g,%g',
-                                           center_x, center_y, width, height, corner_width, corner_height)
+      primitive 'roundrectangle ' + sprintf(
+        '%g,%g,%g,%g,%g,%g',
+        center_x, center_y, width, height, corner_width, corner_height
+      )
     end
 
     # Specify scaling to be applied to coordinate space on subsequent drawing commands.
     def scale(x, y)
-      primitive 'scale ' + format('%g,%g', x, y)
+      primitive 'scale ' + sprintf('%g,%g', x, y)
     end
 
     def skewx(angle)
-      primitive 'skewX ' + format('%g', angle)
+      primitive 'skewX ' + sprintf('%g', angle)
     end
 
     def skewy(angle)
-      primitive 'skewY ' + format('%g', angle)
+      primitive 'skewY ' + sprintf('%g', angle)
     end
 
     # Specify the object stroke, a color name or pattern name.
@@ -574,7 +627,7 @@ module Magick
 
     # Specify the initial offset in the dash pattern
     def stroke_dashoffset(value = 0)
-      primitive 'stroke-dashoffset ' + format('%g', value)
+      primitive 'stroke-dashoffset ' + sprintf('%g', value)
     end
 
     def stroke_linecap(value)
@@ -601,7 +654,7 @@ module Magick
 
     # Specify stroke (outline) width in pixels.
     def stroke_width(pixels)
-      primitive 'stroke-width ' + format('%g', pixels)
+      primitive 'stroke-width ' + sprintf('%g', pixels)
     end
 
     # Draw text at position x,y. Add quotes to text that is not already quoted.
@@ -619,7 +672,7 @@ module Magick
         # escape existing braces, surround with braces
         text = '{' + text.gsub(/[}]/) { |b| '\\' + b } + '}'
       end
-      primitive 'text ' + format('%g,%g %s', x, y, text)
+      primitive 'text ' + sprintf('%g,%g %s', x, y, text)
     end
 
     # Specify text alignment relative to a given point
@@ -648,7 +701,7 @@ module Magick
     # Specify center of coordinate space to use for subsequent drawing
     # commands.
     def translate(x, y)
-      primitive 'translate ' + format('%g,%g', x, y)
+      primitive 'translate ' + sprintf('%g,%g', x, y)
     end
   end # class Magick::Draw
 
@@ -856,7 +909,7 @@ module Magick
       else
         get_exif_by_number # ensure properties is populated with exif data
         tag.each do |num|
-          rval = self[format('#%04X', num.to_i)]
+          rval = self[sprintf('#%04X', num.to_i)]
           hash[num] = rval == 'unknown' ? nil : rval
         end
       end
@@ -1064,7 +1117,7 @@ module Magick
 
         # Define a getter and a setter for each channel.
         %i[red green blue opacity].each do |c|
-          module_eval <<-END_EVAL
+          module_eval <<-END_EVAL, __FILE__, __LINE__ + 1
             def #{c}
                 return collect { |p| p.#{c} }
             end
@@ -1120,7 +1173,6 @@ module Magick
           each { |x| @view[x] = rv.dup }
           changed
           notify_observers(self)
-          nil
         end
 
         # A pixel has been modified. Tell the view.
@@ -1243,16 +1295,14 @@ module Magick
 
     protected
 
-    def is_an_image(obj)
+    def assert_image(obj)
       Kernel.raise ArgumentError, "Magick::Image required (#{obj.class} given)" unless obj.is_a? Magick::Image
-      true
     end
 
     # Ensure array is always an array of Magick::Image objects
-    def is_an_image_array(ary)
+    def assert_image_array(ary)
       Kernel.raise ArgumentError, "Magick::ImageList or array of Magick::Images required (#{ary.class} given)" unless ary.respond_to? :each
-      ary.each { |obj| is_an_image obj }
-      true
+      ary.each { |obj| assert_image obj }
     end
 
     # Find old current image, update scene number
@@ -1284,7 +1334,7 @@ module Magick
       if n.nil?
         Kernel.raise IndexError, 'scene number out of bounds' unless @images.length.zero?
         @scene = nil
-        return @scene
+        return
       elsif @images.length.zero?
         Kernel.raise IndexError, 'scene number out of bounds'
       end
@@ -1292,13 +1342,12 @@ module Magick
       n = Integer(n)
       Kernel.raise IndexError, 'scene number out of bounds' if n < 0 || n > length - 1
       @scene = n
-      @scene
     end
 
     # All the binary operators work the same way.
     # 'other' should be either an ImageList or an Array
     %w[& + - |].each do |op|
-      module_eval <<-END_BINOPS
+      module_eval <<-END_BINOPS, __FILE__, __LINE__ + 1
         def #{op}(other)
           ilist = self.class.new
           begin
@@ -1308,7 +1357,7 @@ module Magick
           end
           current = get_current()
           a.each do |image|
-            is_an_image image
+            assert_image image
             ilist << image
           end
           ilist.set_current current
@@ -1327,7 +1376,7 @@ module Magick
     end
 
     def <<(obj)
-      is_an_image obj
+      assert_image obj
       @images << obj
       @scene = @images.length - 1
       self
@@ -1368,20 +1417,21 @@ module Magick
     def []=(*args)
       obj = @images.[]=(*args)
       if obj && obj.respond_to?(:each)
-        is_an_image_array(obj)
+        assert_image_array(obj)
         set_current obj.last.__id__
       elsif obj
-        is_an_image(obj)
+        assert_image(obj)
         set_current obj.__id__
       else
         set_current nil
       end
-      obj
     end
 
-    %i[at each each_index empty? fetch
-       first hash include? index length rindex sort!].each do |mth|
-      module_eval <<-END_SIMPLE_DELEGATES
+    %i[
+      at each each_index empty? fetch
+      first hash include? index length rindex sort!
+    ].each do |mth|
+      module_eval <<-END_SIMPLE_DELEGATES, __FILE__, __LINE__ + 1
         def #{mth}(*args, &block)
           @images.#{mth}(*args, &block)
         end
@@ -1403,7 +1453,7 @@ module Magick
     # override Enumerable#collect
     def collect(&block)
       current = get_current
-      a = @images.collect(&block)
+      a = @images.map(&block)
       ilist = self.class.new
       a.each { |image| ilist << image }
       ilist.set_current current
@@ -1411,8 +1461,8 @@ module Magick
     end
 
     def collect!(&block)
-      @images.collect!(&block)
-      is_an_image_array @images
+      @images.map!(&block)
+      assert_image_array @images
       self
     end
 
@@ -1421,7 +1471,6 @@ module Magick
       ditto = self.class.new
       @images.each { |f| ditto << f.copy }
       ditto.scene = @scene
-      ditto.taint if tainted?
       ditto
     end
 
@@ -1432,6 +1481,7 @@ module Magick
     end
 
     # ImageList#map took over the "map" name. Use alternatives.
+    alias map collect
     alias __map__ collect
     alias map! collect!
     alias __map__! collect!
@@ -1456,7 +1506,7 @@ module Magick
     end
 
     def concat(other)
-      is_an_image_array other
+      assert_image_array other
       other.each { |image| @images << image }
       @scene = length - 1
       self
@@ -1470,7 +1520,7 @@ module Magick
     end
 
     def delete(obj, &block)
-      is_an_image obj
+      assert_image obj
       current = get_current
       a = @images.delete(obj, &block)
       set_current current
@@ -1495,12 +1545,11 @@ module Magick
       ditto = self.class.new
       @images.each { |img| ditto << img }
       ditto.scene = @scene
-      ditto.taint if tainted?
       ditto
     end
 
     def eql?(other)
-      is_an_image_array other
+      assert_image_array other
       eql = other.eql?(@images)
       begin # "other" is another ImageList
         eql &&= @scene == other.scene
@@ -1511,10 +1560,10 @@ module Magick
     end
 
     def fill(*args, &block)
-      is_an_image args[0] unless block_given?
+      assert_image args[0] unless block_given?
       current = get_current
       @images.fill(*args, &block)
-      is_an_image_array self
+      assert_image_array self
       set_current current
       self
     end
@@ -1522,7 +1571,7 @@ module Magick
     # Override Enumerable's find_all
     def find_all(&block)
       current = get_current
-      a = @images.find_all(&block)
+      a = @images.select(&block)
       ilist = self.class.new
       a.each { |image| ilist << image }
       ilist.set_current current
@@ -1546,14 +1595,12 @@ module Magick
       filenames.each do |f|
         Magick::Image.read(f, &block).each { |n| @images << n }
       end
-      if length > 0
-        @scene = length - 1 # last image in array
-      end
-      self
+
+      @scene = length - 1 if length > 0 # last image in array
     end
 
     def insert(index, *args)
-      args.each { |image| is_an_image image }
+      args.each { |image| assert_image image }
       current = get_current
       @images.insert(index, *args)
       set_current current
@@ -1572,7 +1619,6 @@ module Magick
       n = Integer(n)
       Kernel.raise ArgumentError, 'iterations must be between 0 and 65535' if n < 0 || n > 65_535
       @images.each { |f| f.iterations = n }
-      self
     end
 
     def last(*args)
@@ -1653,7 +1699,7 @@ module Magick
 
     def push(*objs)
       objs.each do |image|
-        is_an_image image
+        assert_image image
         @images << image
       end
       @scene = length - 1
@@ -1689,7 +1735,7 @@ module Magick
     end
 
     def replace(other)
-      is_an_image_array other
+      assert_image_array other
       current = get_current
       @images.clear
       other.each { |image| @images << image }
@@ -1787,7 +1833,7 @@ module Magick
 
     # @scene -> new object
     def unshift(obj)
-      is_an_image obj
+      assert_image obj
       @images.unshift(obj)
       @scene = 0
       self
@@ -1804,6 +1850,11 @@ module Magick
     alias indices values_at
   end # Magick::ImageList
 
+  class Pixel
+    # include Observable for Image::View class
+    include Observable
+  end
+
   #  Collects non-specific optional method arguments
   class OptionalMethodArguments
     def initialize(img)