module ActionController
  module Macros
    module ImageMagick
      #
      # The default configuration options.
      #
      DEFAULT_OPTIONS = { :action_name=>:imagemagick,
                          :cache=>nil,
                          :prerender=>false,
                          :max_recipe_level=>:builtin,
                          :commands_param=>:commands }
      
      def self.append_features(base) #:nodoc:
        super
        
        base.extend(ClassMethods)
      end

      # This macro can be used to add ImageMagick functionality to a controller.
      # You can use it to access ImageMagick commands with a simple template tag.
      # ImageMagick is a set of image processing tools, that can do nearly everything
      # you'd ever want to do with an image. Resize, rotate, crop and much more.
      #
      # This needs the RMagick library (and ImageMagick, of course) to work.
      #
      # * http://www.imagemagick.org/
      # * http://rmagick.rubyforge.org/
      #
      #
      # == As an action, with images from a directory
      #
      # The simplest way to use this extension, is by adding the behaviour to a directory.
      # For example:
      #
      #   # Controller
      #   class Photo < ApplicationController
      #     imagemagick_for_directory '/var/lib/photos'
      #   end
      #
      #   # View
      #   <%= imagemagick_tag 'presentation.jpg', 'resize(100x50)+flop' %>
      #
      # This example generates an <tt><img></tt> tag in the view, which points to
      # the +imagemagick+ action of the Photo controller. All you need to do to
      # generate this controller, is adding the <tt>imagemagick_for_directory</tt> method to your
      # controller class. The +imagemagick+ action opens the image, sends the
      # commands to RMagick for processing and then sends the result to the browser.
      #
      # This example shows you the image presentation.jpg from the <tt>/var/lib/photos</tt>
      # directory. It is processed with the commands <tt>resize(100x50)</tt>, which means
      # that ImageMagick will shrink it to fit it in an area of 100x50 pixels, and
      # <tt>flop</tt>, which means that left and right are reversed.
      #
      #
      # == As an +after_filter+, with images provided by your action
      #
      # Or perhaps you have stored your images not in a directory, but in a database or
      # somewhere else. Even then you can use the ImageMagick extension. This works by
      # adding the ImageMagick processing as an +after_filter+ for the action that
      # retrieves and sends the original image. For example:
      #
      #   # Controller
      #   class Photo < ApplicationController
      #     imagemagick_filter_for :display_photo
      #     
      #     def display_photo
      #       # do some work to retrieve and send the photo (that's your job)
      #     end
      #   end
      #   
      #   # View
      #   <%= imagemagick_tag :action=>'display_photo', :commands=>'resize(100)', ... other parameters for display_photo ... %>
      #
      # The action +display_photo+ gets the image from the database or where you've stored
      # it and renders it normally. Then after that, the imagemagick filter is executed. It
      # reads the output from your action, processes it using the commands from <tt>@params['commands']</tt>
      # and finally sends the resulting image to the browser (or to another filter, if there is one).
      # 
      # The <tt><img></tt> tag for this rendered image is generated by +imagemagick_tag+:
      # you give it the +url_for+ options hash that your action needs to find and display the image,
      # plus the additional <tt>:commands</tt> parameter that is to be used by ImageMagick.
      #
      #
      # == The image source
      #
      # === Action: the image directory
      #
      # If you used +imagemagick_for_directory+, the extension expects to find all images in a directory,
      # the name of which is specified with the +imagemagick_for_directory+ method. In this directory,
      # you can simply place the image files. The names and extensions are not really important,
      # ImageMagick is smart enough to determine the file type from the contents of the file.
      #
      # In the image directory, you can have subdirectories. Just give the name of the
      # subdirectory to <tt>imagemagick_tag</tt>. For example, if in our directory <tt>/var/lib/photos</tt>
      # there is a subdirectory called rails, we can refer to an image in that subdirectory
      # like this:
      #
      #   # View
      #   <%= imagemagick_tag 'rails/presentation.jpg' %>
      #
      # You can use the ImageMagick extension in multiple controllers, but you might
      # want to specify a different image directory for each of them. (But even that is not
      # required.)
      #
      # === Filter: the <tt>@response.body</tt>
      #
      # The filter expects your action to put the image in <tt>@response.body</tt>. If you use
      # <tt>render(:file)</tt> or <tt>render(:text)</tt> to render the image, it should work right. You
      # can't use the streaming methods +send_file+ and +send_data+.
      #
      #
      # == Caching
      #
      # If you don't take any precautions, the rendered image will not be saved, and
      # it has to be rendered from scratch for every new request. This can make it a
      # little slow. This extension therefore provides a caching mechanism, which caches
      # the processed images. For the requests that follow after the first rendering,
      # it simply sends the cached image, instead of re-rendering it.
      #
      # To enable caching, you need a cache directory that is writable by the webserver.
      # If you have that directory, all you have to do is specify it with the +cache+ option
      # of the +imagemagick_for+ method.
      #
      #   # Controller
      #   class Photo < ApplicationController
      #     imagemagick_for_directory '/var/lib/photos', :cache=>'/var/lib/photo-cache'
      #   end
      #
      # You can use the same cache directory for multiple controllers. Caching is also
      # possible if you use +imagemagick_filter_for+.
      #
      #
      # == Pre-rendering
      #
      # By default, the commands are transferred in the URL of the image, and are executed
      # when the user requests the image. This is reasonably safe, but it does allow your
      # visitors to specify any ImageMagick command they want by simply changing the URL.
      # If you think this is a problem, you can enable the pre-rendering function.
      #
      # Pre-rendering means that the image is rendered earlier in the process: when the
      # +imagemagick_tag+ is displayed by the view. The image is rendered and cached, and the
      # name of that cached image is sent to the browser, which then uses it to request the
      # image. This means that the user does not have the possibility to influence the
      # rendering of the image, as rendering is done from the view. It also means that the
      # initial delay of the rendering of the image is on the web page, instead of on the
      # loading of the images.
      #
      # The pre-rendered images are stored by the caching system, so you'll need to
      # enable caching if you want to use pre-rendering.
      #
      #   # Controller
      #   class Photo < ApplicationController
      #     imagemagick_for_directory '/var/lib/photos', :cache=>'/var/lib/photo-cache', :prerender=>true
      #   end
      #
      # Prerendering is only possible if you're using the +imagemagick_for_directory+ action,
      # <b>prerendering does not work with <tt>imagemagick_filter_for</tt></b>.
      #
      #
      # == Recipes
      #
      # It is possible to define your own commands, or 'recipes', for use with <tt>imagemagick_tag</tt>.
      # See the documentation for <tt>ActionController::Macros::ImageMagick::RecipeSet</tt> for more
      # information.
      # 
      # If you have your own set of recipes, you can restrict the commands that can be executed
      # to the recipes in this set. See the <tt>:max_recipe_level</tt> option of <tt>imagemagick_for</tt>.
      # 
      #
      # == Routes.rb trick
      #
      # +imagemagick_for+ works without any additional routes. It uses urls like:
      #   /photo/imagemagick/presentation.jpg?command=resize(100x100)
      #
      # If you'd like to get rid of the <tt>?command=</tt>, you can add the following routes to
      # your <tt>routes.rb</tt>:
      #     map.connect ':controller/imagemagick/:id', :action=>'imagemagick', :commands=>''
      #     map.connect ':controller/imagemagick/:commands/:id', :action=>'imagemagick'
      #
      # The above url will now be rendered as:
      #   /photo/imagemagick/resize(100x100)/presentation.jpg
      #
      module ClassMethods
        #
        # Enables the ImageMagick extension for the given +image_path+. For a description
        # of the +options+, see the documentation for +imagemagick_for+.
        #
        def imagemagick_for_directory(image_path, options = {})
          # call imagemagick_for with a String
          imagemagick_for(image_path.to_s, options)
        end
        
        #
        # Enables the ImageMagick extension as an +after_filter+ for +action_name+.
        # The response of the action will be processed as an image, with the commands found
        # in <tt>@params["command"]</tt>.
        #
        # For a description of the +options+, see the documentation for +imagemagick_for+.
        #
        def imagemagick_filter_for(action_name, options = {})
          # call imagemagick_for with a Symbol
          imagemagick_for(action_name.to_sym, options)
        end
        
        #
        # Enables the ImageMagick extension for this controller. If +image_source+ is a +String+,
        # the extension will be enabled for the directory with that name. If +image_source+ is a
        # +Symbol+, the extension will be enabled as a +after_filter+ that does its work on the
        # result of the action with that name.
        #
        # <i>This method is also available as +imagemagick_for_directory+ and +imagemagick_filter_for+.</i>
        #
        # The following +options+ can be specified:
        #
        # * <tt>:cache</tt>: the directory where cached images are stored, or +nil+ (the default)
        #   if you don't want caching. The directory has to be writable by the web server.
        # * <tt>:prerender</tt>: set this to +true+ if you want pre-rendering. This only works if
        #   you have enabled caching. By default, pre-rendering is off.
        # * <tt>:action_name</tt>: the name of the imagemagick action. The default is +imagemagick+,
        #   you can change it by specifying this option.
        # * <tt>:commands_param</tt>: the name of the commands parameter in the <tt>@params</tt> hash,
        #   <tt>:commands</tt> by default.
        # * <tt>:max_recipe_level</tt>: whether or not you can use only local or global recipes
        #   (see the documentation for +RecipeSet+ for more about these levels). This can have one
        #   of those values:
        #   * <tt>:local</tt>: only local recipes can be used
        #   * <tt>:global</tt>: only local and global recipes can be used
        #   * <tt>:builtin</tt> (the default): local, global and the built-in recipes can be used
        #
        # To change the system-wide defaults, see the <tt>ActionController::Macros::ImageMagick::DEFAULT_OPTIONS</tt>
        #
        def imagemagick_for(image_source, options = {})
          require 'RMagick'
          
          configuration = Hash.new.merge!(ActionController::Macros::ImageMagick::DEFAULT_OPTIONS)
          configuration.update(options)
          
          # expand the path if it is relative
          if defined?(RAILS_ROOT)
            configuration[:cache] = File.expand_path(configuration[:cache], RAILS_ROOT) unless configuration[:cache].nil?
          end
          
          # set the maximum recipe level that is allowed
          configuration[:max_recipe_level] = configuration[:max_recipe_level].to_sym
          configuration[:max_recipe_level] = :builtin unless [:builtin, :global, :local].member?(configuration[:max_recipe_level])
          
          # initialize the list of recipes specific to this controller.
          configuration[:local_recipes] = RecipeSet.new
          
          # what is the source of the images?
          if image_source.is_a?(String)
            # images from a directory
            # strip the trailing slash
            configuration[:image_path] = image_source
            configuration[:image_path] = image_source.sub(/\/$/, '') if image_source =~ /\/$/
            configuration[:type] = :action
            
            # expand 
            if defined?(RAILS_ROOT)
              configuration[:image_path] = File.expand_path(configuration[:image_path], RAILS_ROOT)
            end
            
            # the name of the action can be specified, but it has to be a Symbol
            configuration[:action_name] = :imagemagick unless configuration.has_key?(:action_name)
            configuration[:action_name] = configuration[:action_name].to_sym
          else
            # images from the response of an action
            configuration[:type] = :filter
            configuration[:for_action] = image_source.to_sym
          end
          
          #
          # Every controller-class gets a imagemagick_macro_helper-variable,
          # which contains the configuration options.
          #
          @imagemagick_macro_helper = ImageMagickMacroHelper.new(configuration)
          
          #
          # Makes the class helper available from the controller instance.
          #
          define_method(:imagemagick_macro_helper) do
            return self.class.instance_variable_get(:@imagemagick_macro_helper)
          end
          protected :imagemagick_macro_helper
          
          #
          # Returns the +RecipeSet+ with recipes local to this controller.
          #
          define_method(:imagemagick_local_recipes) do
            return imagemagick_macro_helper.local_recipes
          end
          protected :imagemagick_local_recipes
          
          #
          # Shortcut to the +url_for_imagemagick+ method of the helper.
          # Gives the url to the +imagemagick+ action for this filename, with these commands.
          #
          define_method(:url_for_imagemagick) do |filename_or_params, p_commands|
            imagemagick_macro_helper.controller = self
            url_for(imagemagick_macro_helper.url_options_for_imagemagick(filename_or_params, p_commands))
          end
          
          #
          # Implement the extension.
          #
          if configuration[:type]==:action
            implement_as_action(configuration)
          elsif configuration[:type]==:filter
            implement_as_filter(configuration)
          end
        end
        
        #
        # Adds a custom recipe with the given +name+. +recipe+ can be a +String+,
        # a +Proc+, a +Class+ or a +Symbol+.
        #
        def imagemagick_recipe(name, recipe, version = nil)
          if @imagemagick_macro_helper.nil?
            raise(ActionControllerError, "Use imagemagick_for before you use imagemagick_recipe.")
          end
          
          @imagemagick_macro_helper.add_recipe(name, recipe, version)
        end
        
        private
          #
          # Implements the extension as an action.
          #
          def implement_as_action(configuration)
            #
            # The +imagemagick+ action of the controller.
            # Reads the filename and the commands from the request and sends an image.
            #
            define_method(configuration[:action_name]) do
              begin
                imagemagick_macro_helper.controller = self
                
                identification = @params["id"].to_s
                commands = @params["#{configuration[:commands_param]}"]
                
                if imagemagick_macro_helper.prerender? && !imagemagick_macro_helper.cached?(identification, commands)
                  # prerendering is required, but there is no cached image
                  render :text=>"Image not found.", :status=>404
                end
                
                result = imagemagick_macro_helper.render(identification, identification, commands)
                
                if result.nil?
                  render :text=>"Image not found.", :status=>404
                else
                  @response.headers["Content-type"] = result.mime_type
                  render :text=>result.to_blob
                end
              rescue Exception=>e
                render :text=>"Image could not be processed. "+e.to_s, :status=>500
              end
            end
          end

          #
          # Implements the extension using +after_filter+.
          #
          def implement_as_filter(configuration)
            #
            # The +imagemagick+ filter method of the controller.
            # Reads the response result and the commands from the request and sends an image.
            #
            define_method(:imagemagick_after_filter) do
              image = Magick::Image.from_blob(@response.body)
              
              # if the result is not an image, we don't have to process it
              if !image.empty?
                imagemagick_macro_helper.controller = self
                
                identification = MD5.md5(@response.body).to_s
                commands = @params["#{configuration[:commands_param]}"]
                
                result = imagemagick_macro_helper.render(image.first, identification, commands)
                
                begin
                  if result.nil?
                    @response.headers["Status"] = 404
                    @response.body = "Image not found."
                  else
                    @response.headers["Content-type"] = result.mime_type
                    @response.body = result.to_blob
                  end
                rescue Exception=>e
                  @response.headers["Status"] = 500
                  @response.body = "Image could not be processed. "+e.to_s
                end
              end
            end
            
            module_eval do
              after_filter :imagemagick_after_filter, :only=>"#{configuration[:for_action]}"
            end
          end
      end
      
      #
      # The class that contains all methods of the ImageMagick extension.
      # Every controller with imagemagick_for gets an instance of this, filled
      # with its own configuration options.
      #
      class ImageMagickMacroHelper #:nodoc: all
        def initialize(configuration)
          @configuration = configuration
        end
        
        def caching?
          return !@configuration[:cache].nil?
        end
        
        def prerender?
          # only if caching is available and the +:action+ method is used
          return @configuration[:type]==:action && caching? && @configuration[:prerender]
        end
        
        def controller=(controller)
          @configuration[:controller] = controller
        end
        
        def add_recipe(name, action, version = nil)
          @configuration[:local_recipes].add(name, action, version)
        end
        
        def local_recipes
          @configuration[:local_recipes]
        end
        
        # check the filename: it may contain directory names, but it cannot
        # go to a higher directory than configuration[:image_path]
        def valid_filename?(filename)
          pathname = expand_filename(filename)
          if pathname =~ /^#{@configuration[:image_path]}\//
            return File.readable?(pathname)
          else
            return false
          end
        end
        
        #
        # Expands the filename with the +image_path+.
        #
        def expand_filename(filename)
          return File.expand_path(filename, @configuration[:image_path] + "/")
        end
        
        #
        # Returns the filename the cached image will have if it is renderd
        # with the given commands.
        #
        def cache_filename(identification, commands)
          commands = MagickCommandList.from_anything(commands)
          return File.expand_path(@configuration[:controller].class.to_s.gsub(/[^A-Za-z0-9]/, '') + "." +
                                  commands.to_cache_s(@configuration) + identification.gsub(/\//, '.'), @configuration[:cache]+"/")
        end
        
        #
        # Returns true if this image with these commands is cached.
        #
        def cached?(identification, commands)
          clear_cache_if_stale(identification, commands)
          return caching? && File.exists?(cache_filename(identification, commands))
        end
        
        #
        # Removes the cached image for this file+commands if the original image
        # is newer than the file in the cache. 
        #
        def clear_cache_if_stale(filename, commands)
          if caching? && @configuration[:type]==:action
            source_path = expand_filename(filename)
            cache_path = cache_filename(filename, commands)
            if File.exists?(cache_path) && File.mtime(cache_path) < File.mtime(source_path)
              # remove the cached file, the original file is newer
              FileUtils.rm(source_path)
            end
          end
        end
        
        #
        # Returns a Hash of url_for options that render the given filename
        # with the given ImageMagick commands.
        #
        def url_options_for_imagemagick(filename_or_params, p_commands)
          if p_commands.nil? && filename_or_params.is_a?(Hash)
            p_commands = filename_or_params.delete(@configuration[:commands_param])
          elsif p_commands.nil?
            p_commands = []
          end
          commands = MagickCommandList.from_anything(p_commands)
          
          path_options = nil
          
          if @configuration[:type]==:action
            path_options = { :action=>@configuration[:action_name].to_s }
            path_options[:id] = filename_or_params
            path_options[@configuration[:commands_param]] = commands.to_s unless commands.commands.empty?
            
            render(filename_or_params, filename_or_params, commands) if prerender?
            
          elsif @configuration[:type]==:filter
            path_options = { }
            path_options.merge!(filename_or_params)
            path_options[@configuration[:commands_param]] = commands.to_s unless commands.commands.empty?
          end
          
          return path_options
        end
        
        #
        # Renders the +image+ with the given +commands+.
        # +image+ can be the name of a file, which will be read, or a Magick::Image-object.
        # +identification+ is the unique identifier string for this image, for use in the cache.
        #
        def render(image, identification, commands)
          commands = ImageMagickMacroHelper::MagickCommandList.from_anything(commands)
          
          clear_cache_if_stale(identification, commands)
          
          if cached?(identification, commands)
            # return the file
            return Magick::Image.read(cache_filename(identification, commands)).first
            
          else
            # not cached, we have to render the image
            
            # is it a string (filename) or already an image?
            if image.is_a?(String)
              if valid_filename?(image)
                image = Magick::Image.read(expand_filename(image)).first
              else
                return nil
              end
            end
            
            # process the image
            image = commands.execute_on(image, @configuration)
            image.strip!
            
            # save in the cache?
            if caching?
              image.write(cache_filename(identification, commands))
            end
            
            return image
          end
          
          return nil
        end
        
        #
        # Contains a list of ImageMagick commands (of the type MagickCommand).
        #
        class MagickCommandList
          attr_reader :commands
          
          def initialize
            @commands = Array.new
          end
          
          #
          # Returns a String of the commands for use in a url.
          # (The commands are chained with a +.)
          #    => resize(100x1)+chop
          #
          def to_s
            command_string = @commands.empty? ? "" : @commands.join("+")
          end
          
          #
          # Returns a String of the commands for use in the cache-filename.
          # (All strange characters are removed.)
          #    => resize.100x1.chop.
          #
          def to_cache_s(configuration)
            if !commands.empty?
              command_string = to_s + "."
              command_string += recipe_versions(configuration)
              command_string.gsub!(/[+,]/, '.')
              command_string.gsub!(/[^a-zA-Z0-9.]/, '')
            else
              command_string = ""
            end
            return command_string
          end
          
          def recipe_versions(configuration)
            versions = ""
            @commands.each { |cmd| versions += cmd.recipe_version(configuration).to_s }
            versions += "." unless versions.empty?
            return versions
          end
          
          #
          # Executes the commands on this list on the picture.
          # picture should be an Magick::Image-object.
          #
          def execute_on(picture, configuration)
            @commands.each { |cmd| picture = cmd.execute_on(picture, configuration) }
            return picture
          end
          
          #
          # Parses a String of commands and returns the MagickCommandList.
          # String is of the type generated by MagickCommandList::to_s
          #     resize(100x1)+chop
          #
          def self.from_s(command_string, entered_by_user = true)
            list = MagickCommandList.new
            (command_string+"+").scan(/(([^(+]+)(\([^)]+\))?)*/) do |match|
              list.commands << MagickCommand.from_s(match[0], entered_by_user) unless match[0].nil?
            end
            return list
          end
          
          #
          # Returns the MagickCommandList for p_commands.
          # p_commands can be:
          #
          # * a +MagickCommandList+: it will be returned
          # * an +Array+: a list of commands. Commands can be Strings and
          #      arrays: [command, args]:
          #         [ "resize(1x100)", "resize", ["resize", 100] ]
          # * a +String+: will be parsed by MagickCommandList.from_s
          # * anything else: an empty MagickCommandList will be returned
          #
          # +entered_by_user+ indicates whether this command list is prepared
          # by the user (+true+), or that it is prepared by a higher-level recipe (+false+).
          # If it is set to +true+, the +max_recipe_level+ option will be followed.
          #
          def self.from_anything(p_commands, entered_by_user = true)
            if p_commands.is_a?(MagickCommandList)
              commands = p_commands
            elsif p_commands.is_a?(Array)
              commands = MagickCommandList.new
              p_commands.each { |cmd| commands.commands << MagickCommand.new(cmd[0].to_s, cmd[1], entered_by_user) }
            elsif p_commands.is_a?(String)
              commands = MagickCommandList.from_s(p_commands, entered_by_user)
            else
              commands = MagickCommandList.new
            end
            
            return commands
          end
        end
        
        #
        # A command for in a MagickCommandList.
        # (A command is a command name, and possibly a data string.)
        #
        class MagickCommand
          attr_accessor :command, :data, :entered_by_user
          
          def initialize(command, data = nil, entered_by_user = true)
            @command = command.to_sym
            @data = data
            @entered_by_user = entered_by_user
          end
          
          #
          # Converts the command to a String version for use in the image url.
          #    "command"  or  "command(args)"
          #
          def to_s
            command_string = @command.to_s
            command_string += "(" + MagickCommand.encode(data) + ")" unless data.nil?
            return command_string
          end
          
          #
          # Executes this command on the picture and returns the result.
          #
          def execute_on(picture, configuration)
            if configuration[:local_recipes].has_key?(@command.to_sym)
              recipe = configuration[:local_recipes][@command.to_sym].first
            elsif (!entered_by_user || [:global,:builtin].member?(configuration[:max_recipe_level])) &&
                  GlobalRecipes.has_key?(@command.to_sym)
              recipe = GlobalRecipes[@command.to_sym].first
            elsif (!entered_by_user || configuration[:max_recipe_level]==:builtin) &&
                  BuiltinRecipes.has_key?(@command.to_sym)
              recipe = BuiltinRecipes[@command.to_sym].first
            else
              raise "Command " + @command.to_s + " not found."
            end
            
            # recipes may return Strings. continue solving those
            # Strings until the result is an image, at which point
            # the rendering is finished.
            until recipe.is_a?(Magick::Image)
              # reorganize: Symbol points to a method on the controller
              #             Class should have a method execute_recipe_on
              if recipe.is_a?(Symbol)
                recipe = configuration[:controller].method(recipe)
              elsif recipe.respond_to?(:execute_recipe_on)
                recipe = recipe.method(:execute_recipe_on)
              end
              
              begin
                if recipe.is_a?(Proc) || recipe.is_a?(Method)
                  recipe = recipe.call(picture, *@data.to_s.split(/,/))
                elsif recipe.is_a?(String)
                  # a string with other imagemagick commands
                  recipe = MagickCommandList.from_s(recipe, false).execute_on(picture, configuration)
                end
              rescue Exception=>e
                raise "Error while executing " + @command.to_s + ": " + e.to_s
              end
            end
            
            picture = recipe
            
            return picture
          end
          
          def recipe_version(configuration)
            if configuration[:local_recipes].has_key?(@command.to_sym)
              recipe = configuration[:local_recipes][@command.to_sym]
            elsif (!entered_by_user || [:global,:builtin].member?(configuration[:max_recipe_level])) &&
                  GlobalRecipes.has_key?(@command.to_sym)
              recipe = GlobalRecipes[@command.to_sym]
            elsif (!entered_by_user || configuration[:max_recipe_level]==:builtin) &&
                  BuiltinRecipes.has_key?(@command.to_sym)
              recipe = BuiltinRecipes[@command.to_sym]
            else
              raise "Command " + @command.to_s + " not found."
            end
            
            version = recipe.last.to_s
            
            if recipe.first.is_a?(String)
              # a string with other imagemagick commands.
              # append the version numbers of those too.
              version += MagickCommandList.from_s(recipe.first, false).recipe_versions(configuration)
            end
            
            return version
          end
          
          #
          # Reads a command string (of the MagickCommand::to_s format) and returns
          # a MagickCommand.
          #   resize(100x10)  becomes @command = "resize", @data = "100x10"
          #
          def self.from_s(command, entered_by_user = true)
            return MagickCommand.new(command[/^[^(]+/], command[/\((.+)\)$/, 1], entered_by_user)
          end
          
          #
          # Encodes the data string for use in the url command string.
          #
          def self.encode(data)
            # in the command string, ( and ) are used to separate
            # the argument from the command: <tt>resize(100x10)</tt>
            return data.to_s.tr("()", "[]")
          end
          
          #
          # Decodes the data string from the url command string.
          #
          def self.decode(data)
            return data.to_s.tr("[]", "()")
          end
        end
      end
      
      
      
      # == Creating recipes
      #
      # It is possible to write your own commands to use with +imagemagick_tag+. You do
      # this by creating +recipes+. Your own recipes can have arguments and you can mix
      # them with normal ImageMagick methods. Such as:
      #
      #   <%= imagemagick_tag 'picture.jpg', 'customthumbnail+resize(100)+myborder(f00)' %>
      #
      # There are multiple ways to write your own recipes: as a +String+ of normal
      # commands, as an inline method (+Proc+), as a method reference (+Symbol+) or as
      # an external +Class+.
      #
      #
      # === Recipe type: String
      #
      # The easiest way is <b>with a String</b>. If you always render your
      # profile images with <tt>'resize(100)+border(1,1,fff)'</tt>, you can shorten
      # that with this recipe:
      #
      #   # in the controller
      #   class UserController < ApplicationController
      #     imagemagick_for_directory '/var/lib/profiles'
      #     imagemagick_recipe :userprofile, 'resize(100)+border(1,1,fff)'
      #   end
      #   
      #   # in the view
      #   <%= imagemagick_tag 'john.jpg', 'userprofile' %>
      # 
      # As you see, you've now created your own 'command'. +userprofile+ will be
      # expanded to <tt>resize(100)+border(1,1,fff)</tt> when rendering.
      # 
      #
      # === Recipe type: Proc
      #
      # A more sophisticated method is by using a Proc. You can use this
      # if you want more control than you can get with the String method. And if you
      # need custom parameters for your recipes, you simply can't use a String.
      #
      # With a proc, adding a recipe works like this:
      #
      #   # in the controller
      #   class UserController < ApplicationController
      #     imagemagick_for_directory '/var/lib/profiles'
      #     imagemagick_recipe :square, Proc.new { |image, size| image.resize!(size.to_i, size.to_i) }
      #   end
      #   
      #   # in the view
      #   <%= imagemagick_tag 'john.jpg', 'square(100)' %>
      # 
      # This example renders the image as a 100x100 pixel square. (If you look closely, you'll
      # notice that we're passing the size of 100 pixel as a parameter to the recipe.)
      # Proc-recipes work by accepting an +image+ object and perhaps some parameters. In this case,
      # the only parameter is +size+. The +image+ object is the real <tt>RMagick::Image</tt>-object
      # of the image that is currently being processed. In your proc, you can execute any of the
      # RMagick methods[http://studio.imagemagick.org/RMagick/doc/] you like.
      # 
      # There are two caveats you should keep in mind when using Proc recipes:
      #
      # * Except for the +image+ object, <b>all arguments passed to the Proc are Strings</b>.
      #   The incoming parameter string is split by the commas, so 100,100 would give you
      #   two arguments. In your proc the "100" and "100" are +String+s, but most RMagick commands
      #   expect +Integer+s or +Float+s. Remember to convert them with +to_i+ or +to_f+ (as in
      #   the example above).
      # 
      # * <b>Your proc should return the +image+ object.</b> Not every RMagick method is
      #   available as an in-place method (which is destructive, with a trailing !). Thus, to make
      #   sure that the changes your recipe makes are saved, you should return the changed image.
      #   (When a destructive method is available, use that, but returning the image object is still
      #   required.)
      #
      # 
      # === Recipe type: Method or Class
      #
      # If you don't like providing the recipe as a Proc, you can also give your recipes the form
      # of methods of the controller, or as a separate class.
      #
      # If using a method, give the method name as a Symbol:
      #
      #   class UserController < ApplicationController
      #     imagemagick_for_directory '/var/lib/profiles'
      #     imagemagick_recipe :ownresize, :my_own_resize_method
      #     
      #     private
      #       def my_own_resize_method(image, width, height)
      #         image.resize!(width.to_i, height.to_i)
      #       end
      #   end
      #
      # If using a class, it should have a class method called +execute_recipe_on+.
      # Provide the class to imagemagick_recipe:
      #
      #   class MyResizeRecipe
      #     def self.execute_recipe_on(image, width, height)
      #       image.resize!(width.to_i, height.to_i)
      #     end
      #   end
      #
      #   class UserController < ApplicationController
      #     imagemagick_for_directory '/var/lib/profiles'
      #     imagemagick_recipe :ownresize, MyResizeRecipe
      #   end
      #
      # As for the arguments and the expected return, the method and class approaches are
      # exactly the same as with a proc.
      #
      #
      # == Recipe levels
      #
      # The ImageMagick extension uses three different levels of recipes. Each level has it
      # own +RecipeSet+, which is a Hash-like object that contains the recipes of that level.
      #
      # At the deepest level, there are the +BuiltinRecipes+. Those recipes implement the
      # standard commands that come with ImageMagick. These recipes are available in every
      # controller. (You normally shouldn't have to change the recipes at this level.)
      #
      # At a little higher level, you have the +GlobalRecipes+. This is a list of recipes that
      # are specific to the application, i.e. written by you. If you want your recipes to be
      # available in every controller, you can add them to the +GlobalRecipes+ RecipeSet.
      #
      # At the highest level are the local recipes of a controller. These recipes are only
      # available in one controller. Recipes defined with +imagemagick_recipe+ are local recipes.
      #
      #
      # === Defining the +GlobalRecipes+
      #
      # Creating global recipes works a lot like creating routes. You should do it somewhere
      # in your +environment.rb+, or in a file that is included by +environment.rb+. Example:
      #
      #   ActionController::Macros::ImageMagick::GlobalRecipes.add do |recipes|
      #     recipes.add :customthumbnail, 'resize(100x100)'
      #     recipes.add :myborder, Proc.new { |image| image.border(1, 1, '#f00") }
      #   end
      #
      # You can define your global recipes as a +String+, as a +Proc+ or as a +Class+ (see above).
      # Defining them as a +Method+ of the controller is not possible.
      #
      #
      # === Defining local recipes
      #
      # You can define local recipes in your controller with the +imagemagick_recipe+ method.
      # Example:
      #
      #   class  < ApplicationController
      #     imagemagick_for '/var/lib/profiles'
      #     imagemagick_recipe :customthumbnail, 'resize(100x100)'
      #   end
      #
      # You can define your local recipes as a +String+, as a +Proc+, as a +Method+ or as
      # a +Class+ (see above).
      # 
      # It's also possible to add local recipes on the fly. For example, if you have stored your
      # recipes a database, you write a method to retrieve and add them. To do this, you can
      # add the recipe-adding method as a filter for the +imagemagick+ action. For example:
      #
      #   class  < ApplicationController
      #     imagemagick_for '/var/lib/profiles'
      #     
      #     # add a filter that is executed before the imagemagick action
      #     before_filter :add_local_recipes, :only_action=>:imagemagick
      #     
      #     private
      #       def add_local_recipes
      #         imagemagick_local_recipes.add { |recipes|
      #           recipes.add :customthumbnail, 'resize(100x100)'
      #           recipes.add :myborder, Proc.new { |image| image.border(1, 1, '#f00") }
      #         end
      #       end
      #   end
      #
      #
      # == Restricting recipes
      #
      # It is possible to limit the commands that one can execute on an image. You can restrict
      # it to only accept the recipes from the local recipe set, or only from the local and
      # global recipe sets. Set this <tt>:max_recipe_level</tt> as an option for <tt>imagemagick_for</tt>:
      #
      #   class  < ApplicationController
      #     # if you want only local recipes
      #     imagemagick_for '/var/lib/profiles', :max_recipe_level=>:local
      #
      #     # if you want only local and global recipes
      #     imagemagick_for '/var/lib/profiles', :max_recipe_level=>:global
      #   end
      #
      # If you don't specify a <tt>:max_recipe_level</tt>, recipes from all three levels (<tt>:local</tt>, 
      # <tt>:global</tt> and <tt>:builtin</tt>) may be used.
      #
      #
      # == Recipe versions
      #
      # (This only applies if you're using the cache.) Combining custom recipes with the image
      # cache can lead to problems. In the cache, the images are stored with the names of the
      # recipes they were generated with. Now, if you change a recipe but do not change the name,
      # the cached images will not be updated. The extension will still serve images that were
      # rendered with the old recipe.
      # 
      # The solution to this can be very simple: remember to empty the cache directory whenever
      # you change your recipes. This is a perfect way to solve the problem. But there is another
      # option, which is a little more sophisticated: add version numbers to your recipes, and
      # update the number when you change the recipe.
      # 
      # Recipes can be numbers or strings. The order is not important (version 3 can be older than
      # version 1). As long as you're using new version numbers that you haven't used before for the
      # same recipe, you'll be fine.
      # 
      # You can add the version number when you define the recipe. For example:
      #
      #   class  < ApplicationController
      #     imagemagick_for '/var/lib/profiles', :cache=>'/my/cache'
      #     imagemagick_recipe :myborder, Proc.new({ |image| image.border(1, 1, '#f00") }), 'version1'
      #   end
      #
      # The rendered images are now cached with the version number, 'version1'. Now if you want
      # to change the recipe, just be sure to bump the version number:
      #
      #   class  < ApplicationController
      #     imagemagick_for '/var/lib/profiles', :cache=>'/my/cache'
      #     imagemagick_recipe :myborder, Proc.new({ |image| image.border(2, 2, '#f00") }), 'version2'
      #   end
      #
      # That's about all there is to recipe versions. Just two last notes:
      #
      # * If you don't define a version number, the default is +nil+. This means that you can
      #   start setting version numbers starting with the second version of your recipe. (The first
      #   version has number +nil+, the second gets something like +'version2'+ etc.)
      # * If your recipe is a +String+, you don't have to bother adding version numbers. By default,
      #   the version number is set to the value of the +String+, which means that if you change the
      #   recipe +String+ the version will be automatically updated too.
      #
      class RecipeSet < Hash
        #
        # Adds a custom recipe with the given +name+ and +version+. +recipe+ can be a +String+,
        # a +Proc+, a +Class+ or a +Symbol+. If +recipe+ is a +String+ and the +version+ is nil,
        # +version+ will be set to the +String+.
        #
        # If a block is given, the block will be executed with this +self+
        # as the only argument. (This can be used as a way to add many recipes in a row.)
        #
        def add(name = nil, recipe = nil, version = nil, &block)
          if block_given?
            yield(self)
          else
            if recipe.is_a?(String) && version.nil?
              version = recipe
            end
            self[name.to_sym] = [recipe, version]
          end
          return self
        end
        
        #
        # Adds the command +alias_name+ as an alias for the command +original_name+.
        #
        def add_alias(alias_name, original_name, version = nil)
          self[alias_name.to_sym] = [self[original_name.to_sym].first, version]
        end
      end
      
      #
      # Global recipes, available in every controller.
      #
      GlobalRecipes = RecipeSet.new
      
      #
      # Recipes for the standard RMagick commands.
      #
      BuiltinRecipes = RecipeSet.new.add do |recipes|
        # standard RMagick commands
        recipes.add :blur_image, Proc.new { |image, radius, sigma| image.blur_image(radius.to_f, sigma.to_f) }
        recipes.add :border, (Proc.new do |image, width, height, color|
          color = "#" + color unless color[0,1]=="#"
          image.border!(width.to_i, height.to_i, color)
        end )
        recipes.add :colorize, (Proc.new do |image, red_pct, green_pct, blue_pct, fill|
          fill = "#" + fill unless fill[0,1]=="#"
          image.colorize(red_pct.to_f, green_pct.to_f, blue_pct.to_f, fill)
        end )
        recipes.add :crop, Proc.new { |image, x, y, width, height| image.crop!(x.to_i, y.to_i, width.to_i, height.to_i) }
        recipes.add :equalize, Proc.new { |image| image.equalize }
        recipes.add :flip, Proc.new { |image| image.flip! }
        recipes.add :flop, Proc.new { |image| image.flop! }
        recipes.add :geometry, Proc.new { |image, data| image.change_geometry!(data) { |cols, rows, img| img.resize!(cols, rows) } }
        recipes.add :implode, Proc.new { |image, amount| image.implode(amount.to_f) }
        recipes.add :level, Proc.new { |image, black_point, mid_point| image.level(black_point.to_f, mid_point.to_f) }
        recipes.add :normalize, Proc.new { |image| image.normalize }
        recipes.add :oilpaint, Proc.new { |image, amount| image.oil_paint(amount.to_f) }
        recipes.add :opaque, (Proc.new do |image, target, fill|
          target = "#" + target unless target[0,1]=="#"
          fill = "#" + fill unless fill[0,1]=="#"
          image.opaque(target, fill)
        end )
        recipes.add :posterize, Proc.new { |image, levels| image.posterize(levels.to_f) }
        recipes.add :rotate, Proc.new { |image, amount| image.rotate!(amount.to_i) }
        recipes.add :sharpen, Proc.new { |image, radius, sigma| image.sharpen(radius.to_f, sigma.to_f) }
        recipes.add :trim, Proc.new { |image| image.trim! }
        
        # aliases
        recipes.add_alias :resize, :geometry
        recipes.add_alias :s, :geometry
        recipes.add_alias :blur, :blur_image
        
        
        
        # This method is not available from imagemagick, but
        # it is useful: it will always give you an image of
        # exactly the required size. part(100x100) gives you
        # a 100x100 pixel crop from the center of the image.
        #
        # For example: the image is   ********
        #                             ********
        #                             ********
        # 
        # And you want this:          **
        #                             **
        # It will then first resize the image: ****
        #                                      ****
        # And then crops it:         *[**]*
        #                            *[**]*
        #
        # If the source image was this:
        #        **                    --
        #        **  it would crop:    **
        #        **                    **
        #        **                    --
        #
        # The command also scales up, if the image is too small
        # to cover the whole part.
        recipes.add :part, (Proc.new do |image, size|
          target_w = size.split(/x/)[0].to_i
          target_h = size.split(/x/)[1].to_i
          orig_w = image.columns
          orig_h = image.rows
          
          if (orig_w.to_f/orig_h) > (target_w.to_f/target_h)
            # scale to correct height
            image.change_geometry!("x"+target_h.to_s) { |cols, rows, img| img.resize!(cols, rows) }
            
            # remove left and right
            image.crop!((image.columns - target_w) / 2, 0, target_w, target_h)
            
          else
            # scale to correct width
            image.change_geometry!(target_w.to_s+"x") { |cols, rows, img| img.resize!(cols, rows) }
            
            # remove top and bottom
            image.crop!(0, (image.height - target_h) / 2, target_w, target_h)
          end
          
          image
        end )
      end
    end
  end
end