mini_magick 4.13.2 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44b0562f09fa6d0cc281ad1c4317b8e9915aa60dc6175072dc0cdc872f3d8367
-  data.tar.gz: 96225cd5bd66e3c0c065cb169057e196becfcdd1e0c883cb7c23f746d76bcda6
+  metadata.gz: da1546dc65a1492ca64c0747715e0e6b9b3b641541beac9edd6689a2e9544b8b
+  data.tar.gz: b03c897214f43f4d106d90b7fcea2d90ae1b9395afbefcf3810fd2af21fe5095
 SHA512:
-  metadata.gz: a39cb409419be063b9cc27fd107a361d94d3f5dbdad719ed1f472efca70650c710160494f22b18f1408df479f29836d29c2bd71262ad1988cdf22caf85a9251a
-  data.tar.gz: dbb5ba23b0b773a696812ec343f0d267aee1653b0ebfb61ea9560af9c4cac68352b7c936c57233913d8848a1de3c9fe02e31070a94e5f3f0d7f471e444615a55
+  metadata.gz: 666e1178b7a89dedcae4de7220c1a41eb812f8a5a1b14143f669a1337deb26271a94ff7cc6698258617b2584dc93129e021b763365039939d83b7b85b47aa8f5
+  data.tar.gz: 6db3e4657d4e1db3c368b435ef256ba33becf7b164bea29154faeb209bd168f7c370b2ec915920c2ef1e1f61fde0da43b1753cacc6b829a9365039364b262902

data/README.md

@@ -4,8 +4,7 @@
 [![CI](https://github.com/minimagick/minimagick/actions/workflows/ci.yml/badge.svg)](https://github.com/minimagick/minimagick/actions/workflows/ci.yml)
 [![Code Climate](https://codeclimate.com/github/minimagick/minimagick/badges/gpa.svg)](https://codeclimate.com/github/minimagick/minimagick)
 
-A ruby wrapper for [ImageMagick](http://imagemagick.org/) or
-[GraphicsMagick](http://www.graphicsmagick.org/) command line.
+A ruby wrapper for [ImageMagick](http://imagemagick.org/) command line.
 
 ## Why?
 
@@ -26,8 +25,8 @@ MiniMagick gives you access to all the command line options ImageMagick has
 
 ## Requirements
 
-ImageMagick or GraphicsMagick command-line tool has to be installed. You can
-check if you have it installed by running
+ImageMagick command-line tool has to be installed. You can check if you have it
+installed by running
 
 ```sh
 $ magick -version
@@ -43,13 +42,13 @@ Compiler: gcc (4.2)
 
 Add the gem to your Gemfile:
 
-```rb
-gem "mini_magick"
+```sh
+$ bundle add mini_magick
 ```
 
 ## Information
 
-* [API documentation](http://rubydoc.info/github/minimagick/minimagick)
+* [API documentation](https://rubydoc.info/gems/mini_magick)
 
 ## Usage
 
@@ -73,7 +72,7 @@ the copy is just temporary, it gets garbage collected when we lose reference
 to the image.
 
 `MiniMagick::Image.open` also accepts URLs, and options passed in will be
-forwarded to open-uri.
+forwarded to [open-uri](https://github.com/ruby/open-uri).
 
 ```rb
 image = MiniMagick::Image.open("http://example.com/image.jpg")
@@ -117,8 +116,8 @@ image = MiniMagick::Image.new("input.jpg") do |b|
 end # the command gets executed
 ```
 
-The yielded builder is an instance of `MiniMagick::Tool::Mogrify`. To learn more
-about its interface, see [Metal](#metal) below.
+The yielded builder is an instance of `MiniMagick::Tool`. To learn more
+about its interface, see [Tools](#tools) below.
 
 ### Attributes
 
@@ -126,7 +125,6 @@ A `MiniMagick::Image` has various handy attributes.
 
 ```rb
 image.type        #=> "JPEG"
-image.mime_type   #=> "image/jpeg"
 image.width       #=> 250
 image.height      #=> 300
 image.dimensions  #=> [250, 300]
@@ -145,7 +143,7 @@ image["%[gamma]"] # "0.9"
 ```
 
 To get the all information about the image, MiniMagick gives you a handy method
-which returns the output from `identify -verbose` in hash format:
+which returns the output from `magick input.jpg json:`:
 
 ```rb
 image.data #=>
@@ -193,10 +191,6 @@ image.data #=>
 # }
 ```
 
-Note that `MiniMagick::Image#data` is supported only on ImageMagick 6.8.8-3 or
-above, for GraphicsMagick or older versions of ImageMagick use
-`MiniMagick::Image#details`.
-
 ### Pixels
 
 With MiniMagick you can retrieve a matrix of image pixels, where each member of
@@ -221,6 +215,7 @@ pixels = image.get_pixels
 ### Pixels To Image
 
 Sometimes when you have pixels and want to create image from pixels, you can do this to form an image:
+
 ```rb
 image = MiniMagick::Image.open('/Users/rabin/input.jpg')
 pixels = image.get_pixels
@@ -229,22 +224,29 @@ dimension = [image.width, image.height]
 map = 'rgb'
 image = MiniMagick::Image.get_image_from_pixels(pixels, dimension, map, depth ,'jpg')
 image.write('/Users/rabin/output.jpg')
-
 ```
 
 In this example, the returned pixels should now have equal R, G, and B values.
 
 ### Configuration
 
+Here are the available configuration options with their default values:
+
 ```rb
 MiniMagick.configure do |config|
-  config.cli = :graphicsmagick
-  config.timeout = 5
+  config.timeout = nil # number of seconds IM commands may take
+  config.errors = true # raise errors non nonzero exit status
+  config.warnings = true # forward warnings to standard error
+  config.tmdir = Dir.tmpdir # alternative directory for tempfiles
+  config.logger = Logger.new($stdout) # where to log IM commands
+  config.cli_prefix = nil # add prefix to all IM commands
+  config.cli_env = {} # environment variables to set for IM commands
+  config.restricted_env = false # when true, block IM commands from accessing system environment variables other than those in cli_env
 end
 ```
 
-For a complete list of configuration options, see
-[Configuration](http://rubydoc.info/github/minimagick/minimagick/MiniMagick/Configuration).
+For a more information, see
+[Configuration](https://rubydoc.info/gems/mini_magick/MiniMagick/Configuration) API documentation.
 
 ### Composite
 
@@ -277,19 +279,7 @@ end
 
 ### Image validation
 
-By default, MiniMagick validates images each time it's opening them. It
-validates them by running `identify` on them, and see if ImageMagick finds
-them valid. This adds slight overhead to the whole processing. Sometimes it's
-safe to assume that all input and output images are valid by default and turn
-off validation:
-
-```rb
-MiniMagick.configure do |config|
-  config.validate_on_create = false
-end
-```
-
-You can test whether an image is valid:
+You can test whether an image is valid by running it through `identify`:
 
 ```rb
 image.valid?
@@ -309,67 +299,36 @@ D, [2016-03-19T07:31:36.755338 #87191] DEBUG -- : [0.01s] identify /var/folders/
 
 In Rails you'll probably want to set `MiniMagick.logger = Rails.logger`.
 
-### Switching CLIs (ImageMagick \<=\> GraphicsMagick)
-
-Default CLI is ImageMagick, but if you want to use GraphicsMagick, you can
-specify it in configuration:
+## Tools
 
-```rb
-MiniMagick.configure do |config|
-  config.cli = :graphicsmagick # or :imagemagick or :imagemagick7
-end
-```
-
-You can also use `.with_cli` to temporary switch the CLI:
+If you prefer not to use the `MiniMagick::Image` abstraction, you can use ImageMagick's command-line tools directly:
 
 ```rb
-MiniMagick.with_cli(:graphicsmagick) do
-  # Some processing that GraphicsMagick is better at
-end
-```
-
-**WARNING**: If you're building a multithreaded web application, you should
-change the CLI only on application startup. This is because the configuration is
-global, so if you change it in a controller action, other threads in the same
-process will also have their CLI changed, which could lead to race conditions.
-
-### Metal
-
-If you want to be close to the metal, you can use ImageMagick's command-line
-tools directly.
-
-```rb
-MiniMagick::Tool::Magick.new do |magick|
-  magick << "input.jpg"
-  magick.resize("100x100")
-  magick.negate
-  magick << "output.jpg"
+MiniMagick.convert do |convert|
+  convert << "input.jpg"
+  convert.resize("100x100")
+  convert.negate
+  convert << "output.jpg"
 end #=> `magick input.jpg -resize 100x100 -negate output.jpg`
 
 # OR
 
-convert = MiniMagick::Tool::Convert.new
+convert = MiniMagick.convert
 convert << "input.jpg"
 convert.resize("100x100")
 convert.negate
 convert << "output.jpg"
-convert.call #=> `convert input.jpg -resize 100x100 -negate output.jpg`
+convert.call #=> `magick input.jpg -resize 100x100 -negate output.jpg`
 ```
 
-If you're on ImageMagick 7, you should probably use `MiniMagick::Tool::Magick`,
-though the legacy `MiniMagick::Tool::Convert` and friends will work too. On
-ImageMagick 6 `MiniMagick::Tool::Magick` won't be available, so you should
-instead use `MiniMagick::Tool::Convert` and friends.
+This way of using MiniMagick is highly recommended if you want to maximize performance of your image processing. There are class methods for each CLI tool: `animate`, `compare`, `composite`, `conjure`, `convert`, `display`, `identify`, `import`, `mogrify` and `stream`. The `MiniMagick.convert` method will use `magick` on ImageMagick 7 and `convert` on ImageMagick 6.
 
-This way of using MiniMagick is highly recommended if you want to maximize
-performance of your image processing. We will now show the features available.
-
-#### Appending
+### Appending
 
 The most basic way of building a command is appending strings:
 
 ```rb
-MiniMagick::Tool::Magick.new do |convert|
+MiniMagick.convert do |convert|
   convert << "input.jpg"
   convert.merge! ["-resize", "500x500", "-negate"]
   convert << "output.jpg"
@@ -396,10 +355,10 @@ convert << "Perspective"
 convert << "0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35"
 ```
 ```
-convert -distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35'
+magick -distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35'
 ```
 
-#### Methods
+### Methods
 
 Instead of passing in options directly, you can use Ruby methods:
 
@@ -409,15 +368,12 @@ convert.rotate(90)
 convert.distort("Perspective", "0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35")
 ```
 
-MiniMagick knows which options each tool has, so you will get an explicit
-`NoMethodError` if you happen to have misspelled an option.
-
-#### Chaining
+### Chaining
 
 Every method call returns `self`, so you can chain them to create logical groups.
 
 ```rb
-MiniMagick::Tool::Magick.new do |convert|
+MiniMagick.convert do |convert|
   convert << "input.jpg"
   convert.clone(0).background('gray').shadow('80x5+5+5')
   convert.negate
@@ -425,23 +381,23 @@ MiniMagick::Tool::Magick.new do |convert|
 end
 ```
 
-#### "Plus" options
+### "Plus" options
 
 ```rb
-MiniMagick::Tool::Magick.new do |convert|
+MiniMagick.convert do |convert|
   convert << "input.jpg"
   convert.repage.+
   convert.distort.+("Perspective", "more args")
 end
 ```
 ```
-convert input.jpg +repage +distort Perspective 'more args'
+magick input.jpg +repage +distort Perspective 'more args'
 ```
 
-#### Stacks
+### Stacks
 
 ```rb
-MiniMagick::Tool::Magick.new do |convert|
+MiniMagick.convert do |convert|
   convert << "wand.gif"
 
   convert.stack do |stack|
@@ -456,16 +412,16 @@ MiniMagick::Tool::Magick.new do |convert|
 end
 ```
 ```
-convert wand.gif \( wand.gif -rotate 90 -foo bar baz \) images.gif
+magick wand.gif \( wand.gif -rotate 90 -foo bar baz \) images.gif
 ```
 
-#### STDIN and STDOUT
+### STDIN and STDOUT
 
 If you want to pass something to standard input, you can pass the `:stdin`
 option to `#call`:
 
 ```rb
-identify = MiniMagick::Tool::Identify.new
+identify = MiniMagick.identify
 identify.stdin # alias for "-"
 identify.call(stdin: image_content)
 ```
@@ -474,14 +430,14 @@ MiniMagick also has `#stdout` alias for "-" for outputting file contents to
 standard output:
 
 ```rb
-content = MiniMagick::Tool::Magick.new do |convert|
+content = MiniMagick.convert do |convert|
   convert << "input.jpg"
   convert.auto_orient
   convert.stdout # alias for "-"
 end
 ```
 
-#### Capturing STDERR
+### Capturing STDERR
 
 Some MiniMagick tools such as `compare` output the result of the command on
 standard error, even if the command succeeded. The result of
@@ -489,27 +445,57 @@ standard error, even if the command succeeded. The result of
 block, it will yield the stdout, stderr and exit status of the command:
 
 ```rb
-compare = MiniMagick::Tool::Compare.new
+compare = MiniMagick.compare
 # build the command
 compare.call do |stdout, stderr, status|
   # ...
 end
 ```
 
-## Limiting resources
+## Configuring
+
+### GraphicsMagick
+
+As of MiniMagick 5+, [GraphicsMagick](http://www.graphicsmagick.org/) isn't
+officially supported. This means its installation won't be auto-detected, and no
+attempts will be made to handle differences in GraphicsMagick API or output.
+
+However, you can still configure MiniMagick to use it:
+
+```rb
+MiniMagick.configure do |config|
+  config.graphicsmagick = true
+end
+```
+
+Some MiniMagick features won't be supported, such as global timeout,
+`MiniMagick::Image#data` and `MiniMagick::Image#exif`.
 
-ImageMagick supports a number of environment variables for controlling its
+### Limiting resources
+
+ImageMagick supports a number of [environment variables] for controlling its
 resource limits. For example, you can enforce memory or execution time limits by
-setting the following variables in your application's process environment:
+setting the following:
+
+```rb
+MiniMagick.configure do |config|
+  config.cli_env = {
+    "MAGICK_MEMORY_LIMIT" => "128MiB",
+    "MAGICK_MAP_LIMIT" => "64MiB",
+    "MAGICK_TIME_LIMIT" => "30"
+  }
+end
+```
 
-* `MAGICK_MEMORY_LIMIT=128MiB`
-* `MAGICK_MAP_LIMIT=64MiB`
-* `MAGICK_TIME_LIMIT=30`
+For time limit you can also use the `timeout` configuration:
 
-For a full list of variables and description, see [ImageMagick's resources
-documentation](http://www.imagemagick.org/script/resources.php#environment).
+```rb
+MiniMagick.configure do |config|
+  config.timeout = 30 # 30 seconds
+end
+```
 
-## Changing temporary directory
+### Changing temporary directory
 
 ImageMagick allows you to change the temporary directory to process the image file:
 
@@ -523,7 +509,7 @@ The example directory `/my/new/tmp_dir` must exist and must be writable.
 
 If not configured, it will default to `Dir.tmpdir`.
 
-## Ignoring STDERR
+### Ignoring STDERR
 
 If you're receiving warnings from ImageMagick that you don't care about, you
 can avoid them being forwarded to standard error:
@@ -534,9 +520,7 @@ MiniMagick.configure do |config|
 end
 ```
 
-## Troubleshooting
-
-### Errors being raised when they shouldn't
+### Avoiding raising errors
 
 This gem raises an error when ImageMagick returns a nonzero exit code.
 Sometimes, however, ImageMagick returns nonzero exit codes when the command
@@ -545,15 +529,14 @@ following configuration:
 
 ```rb
 MiniMagick.configure do |config|
-  config.whiny = false
+  config.errors = false
 end
 ```
 
-If you're using the tool directly, you can pass `whiny: false` value to the
-constructor:
+You can also pass `errors: false` to individual commands:
 
 ```rb
-MiniMagick::Tool::Identify.new(whiny: false) do |b|
+MiniMagick.identify(errors: false) do |b|
   b.help
 end
 ```
@@ -571,3 +554,5 @@ Unlike RMagick, MiniMagick is a much thinner wrapper around ImageMagick.
 * To open files with MiniMagick you use `MiniMagick::Image.open` as you would
   `Magick::Image.read`. To open a file and directly edit it, use
   `MiniMagick::Image.new`.
+
+[environment variables]: https://imagemagick.org/script/resources.php#environment

data/lib/mini_magick/configuration.rb

@@ -5,12 +5,11 @@ module MiniMagick
   module Configuration
 
     ##
-    # If you don't have the CLI tools in your PATH, you can set the path to the
-    # executables.
+    # Uses [GraphicsMagick](http://www.graphicsmagick.org/) instead of
+    # ImageMagick, by prefixing commands with `gm` instead of `magick`.
     #
-    attr_writer :cli_path
-    # @private (for backwards compatibility)
-    attr_accessor :processor_path
+    # @return [Boolean]
+    attr_accessor :graphicsmagick
 
     ##
     # Adds a prefix to the CLI command.
@@ -24,23 +23,35 @@ module MiniMagick
     attr_accessor :cli_prefix
 
     ##
-    # If you don't want commands to take too long, you can set a timeout (in
-    # seconds).
+    # Adds environment variables to every CLI command call.
+    # For example, you could use it to set `LD_PRELOAD="/path/to/libsomething.so"`.
+    # Must be a hash of strings keyed to valid environment variable name strings.
+    # e.g. {'MY_ENV' => 'my value'}
     #
-    # @return [Integer]
+    # @return [Hash]
     #
-    attr_accessor :timeout
+    attr_accessor :cli_env
+
     ##
-    # When get to `true`, it outputs each command to STDOUT in their shell
-    # version.
+    # If set to true, Open3 will restrict system calls to access only
+    # environment variables defined in :cli_env, plus HOME, PATH, and LANG
+    # since those are required for such system calls. It will not pass on any
+    # other environment variables from the system.
     #
     # @return [Boolean]
     #
-    attr_reader :debug
+    attr_accessor :restricted_env
+
     ##
-    # Logger for {#debug}, default is `MiniMagick::Logger.new(STDOUT)`, but
-    # you can override it, for example if you want the logs to be written to
-    # a file.
+    # If you don't want commands to take too long, you can set a timeout (in
+    # seconds).
+    #
+    # @return [Integer]
+    #
+    attr_accessor :timeout
+    ##
+    # Logger for commands, default is `Logger.new($stdout)`, but you can
+    # override it, for example if you want the logs to be written to a file.
     #
     # @return [Logger]
     #
@@ -53,31 +64,13 @@ module MiniMagick
     #
     attr_accessor :tmpdir
 
-    ##
-    # If set to `true`, it will `identify` every newly created image, and raise
-    # `MiniMagick::Invalid` if the image is not valid. Useful for validating
-    # user input, although it adds a bit of overhead. Defaults to `true`.
-    #
-    # @return [Boolean]
-    #
-    attr_accessor :validate_on_create
-    ##
-    # If set to `true`, it will `identify` every image that gets written (with
-    # {MiniMagick::Image#write}), and raise `MiniMagick::Invalid` if the image
-    # is not valid. Useful for validating that processing was successful,
-    # although it adds a bit of overhead. Defaults to `true`.
-    #
-    # @return [Boolean]
-    #
-    attr_accessor :validate_on_write
-
     ##
     # If set to `false`, it will not raise errors when ImageMagick returns
     # status code different than 0. Defaults to `true`.
     #
     # @return [Boolean]
     #
-    attr_accessor :whiny
+    attr_accessor :errors
 
     ##
     # If set to `false`, it will not forward warnings from ImageMagick to
@@ -86,118 +79,23 @@ module MiniMagick
 
     def self.extended(base)
       base.tmpdir = Dir.tmpdir
-      base.validate_on_create = true
-      base.validate_on_write = true
-      base.whiny = true
+      base.errors = true
       base.logger = Logger.new($stdout).tap { |l| l.level = Logger::INFO }
       base.warnings = true
+      base.cli_env = {}.freeze
+      base.restricted_env = false
+      base.graphicsmagick = false
     end
 
     ##
     # @yield [self]
     # @example
     #   MiniMagick.configure do |config|
-    #     config.cli = :graphicsmagick
     #     config.timeout = 5
     #   end
     #
     def configure
       yield self
     end
-
-    CLI_DETECTION = {
-      imagemagick7:   "magick",
-      imagemagick:    "mogrify",
-      graphicsmagick: "gm",
-    }
-
-    # @private (for backwards compatibility)
-    def processor
-      @processor ||= CLI_DETECTION.values.detect do |processor|
-        MiniMagick::Utilities.which(processor)
-      end
-    end
-
-    # @private (for backwards compatibility)
-    def processor=(processor)
-      @processor = processor.to_s
-
-      unless CLI_DETECTION.value?(@processor)
-        raise ArgumentError,
-          "processor has to be set to either \"magick\", \"mogrify\" or \"gm\"" \
-          ", was set to #{@processor.inspect}"
-      end
-    end
-
-    ##
-    # Get [ImageMagick](http://www.imagemagick.org) or
-    # [GraphicsMagick](http://www.graphicsmagick.org).
-    #
-    # @return [Symbol] `:imagemagick` or `:graphicsmagick`
-    #
-    def cli
-      if instance_variable_defined?("@cli")
-        instance_variable_get("@cli")
-      else
-        cli = CLI_DETECTION.key(processor) or
-          fail MiniMagick::Error, "You must have ImageMagick or GraphicsMagick installed"
-
-        instance_variable_set("@cli", cli)
-      end
-    end
-
-    ##
-    # Set whether you want to use [ImageMagick](http://www.imagemagick.org) or
-    # [GraphicsMagick](http://www.graphicsmagick.org).
-    #
-    def cli=(value)
-      @cli = value
-
-      if not CLI_DETECTION.key?(@cli)
-        raise ArgumentError,
-          "CLI has to be set to either :imagemagick, :imagemagick7 or :graphicsmagick" \
-          ", was set to #{@cli.inspect}"
-      end
-    end
-
-    ##
-    # If you set the path of CLI tools, you can get the path of the
-    # executables.
-    #
-    # @return [String]
-    #
-    def cli_path
-      if instance_variable_defined?("@cli_path")
-        instance_variable_get("@cli_path")
-      else
-        processor_path = instance_variable_get("@processor_path") if instance_variable_defined?("@processor_path")
-
-        instance_variable_set("@cli_path", processor_path)
-      end
-    end
-
-    ##
-    # When set to `true`, it outputs each command to STDOUT in their shell
-    # version.
-    #
-    def debug=(value)
-      warn "MiniMagick.debug is deprecated and will be removed in MiniMagick 5. Use `MiniMagick.logger.level = Logger::DEBUG` instead."
-      logger.level = value ? Logger::DEBUG : Logger::INFO
-    end
-
-    def shell_api=(value)
-      warn "MiniMagick.shell_api is deprecated and will be removed in MiniMagick 5. The posix-spawn gem doesn't improve performance recent Ruby versions anymore, so support for it will be removed."
-      @shell_api = value
-    end
-
-    def shell_api
-      @shell_api || "open3"
-    end
-
-    # Backwards compatibility
-    def reload_tools
-      warn "MiniMagick.reload_tools is deprecated because it is no longer necessary"
-    end
-
   end
 end