dragonfly 0.9.15 → 1.0

data/.yardopts

@@ -1,29 +0,0 @@
---main extra_docs/Index.md
--e ./yard/setup.rb
---markup-provider=redcarpet
---markup=markdown
--
-README.md
-extra_docs/GeneralUsage.md
-extra_docs/Rails2.md
-extra_docs/Rails3.md
-extra_docs/ImageMagick.md
-extra_docs/Rack.md
-extra_docs/Sinatra.md
-extra_docs/Heroku.md
-extra_docs/Mongo.md
-extra_docs/Couch.md
-extra_docs/Models.md
-extra_docs/DataStorage.md
-extra_docs/Analysers.md
-extra_docs/Processing.md
-extra_docs/Encoding.md
-extra_docs/Generators.md
-extra_docs/Configuration.md
-extra_docs/URLs.md
-extra_docs/MimeTypes.md
-extra_docs/Caching.md
-extra_docs/ServingRemotely.md
-extra_docs/ExampleUseCases.md
-LICENSE
-History.md

data/Rakefile

@@ -1,36 +0,0 @@
-require 'rubygems'
-require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-
-require 'rspec/core'
-require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = FileList['spec/**/*_spec.rb']
-end
-
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
-
-require 'cucumber/rake/task'
-Cucumber::Rake::Task.new(:features)
-
-task :default => [:spec, :features]
-
-require 'yard'
-YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb']
-  t.options = []
-end
-YARD::Rake::YardocTask.new 'yard:changed' do |t|
-  t.files   = `git status | grep '.rb' | grep modified | grep -v yard | cut -d' ' -f4`.split
-  t.options = []
-end

data/config.ru

@@ -1,14 +0,0 @@
-require "rubygems"
-require "bundler/setup"
-$:.unshift(File.expand_path('../lib', __FILE__))
-require 'dragonfly'
-require 'rack/cache'
-
-APP = Dragonfly[:images].configure_with(:imagemagick)
-
-use Rack::Cache,
-  :verbose     => true,
-  :metastore   => 'file:/var/cache/rack/meta',
-  :entitystore => 'file:/var/cache/rack/body'
-
-run APP

data/docs.watchr

@@ -1 +0,0 @@
-watch('lib/.*\.rb|yard/.*|extra_docs/.*')  {|md| system("rake yard:changed") }

data/extra_docs/Analysers.md

@@ -1,68 +0,0 @@
-Analysers
-=========
-Analysers are registered with Dragonfly apps for adding methods to {file:GeneralUsage Job} objects and {file:Models model attachments} such as `width`, `height`, etc.
-
-ImageMagick Analyser
---------------------
-See {file:ImageMagick}.
-
-FileCommandAnalyser
--------------------
-The {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} is registered by default by the
-{Dragonfly::Config::Rails Rails configuration} used by 'dragonfly/rails/images'.
-
-As the name suggests, it uses the UNIX 'file' command.
-
-If not already registered:
-
-    app.analyser.register(Dragonfly::Analysis::FileCommandAnalyser)
-
-gives us:
-
-    image.mime_type    # => 'image/png'
-
-You shouldn't need to configure it but if you need to:
-
-    app.analyser.register(Dragonfly::Analysis::FileCommandAnalyser) do |a|
-      a.use_filesystem = false                 # defaults to true
-      a.file_command = '/opt/local/bin/file'   # defaults to 'file'
-      a.num_bytes_to_check = 1024              # defaults to 255 - only applies if not using the filesystem
-    end
-
-Custom Analysers
-----------------
-
-To register a single custom analyser:
-
-    app.analyser.add :wobbliness do |temp_object|
-      # can use temp_object.data, temp_object.path, temp_object.file, etc.
-      SomeLibrary.assess_wobbliness(temp_object.data)
-    end
-
-    image.wobbliness    # => 71
-
-You can create a class like the ImageMagick one above, in which case all public methods will be counted as analysis methods.
-Each method takes the temp_object as its argument.
-
-    class MyAnalyser
-
-      def coolness(temp_object)
-        temp_object.size / 30
-      end
-
-      def uglyness(temp_object)
-        `ugly -i #{temp_object.path}`
-      end
-
-      private
-
-      def my_helper_method
-        # do stuff
-      end
-
-    end
-
-    app.analyser.register(MyAnalyser)
-
-    image.coolness    # => -4.1
-    image.uglyness    # => "VERY"

data/extra_docs/Caching.md

@@ -1,23 +0,0 @@
-Caching
-=======
-
-Processing and encoding can be an expensive operation. The first time we visit the url,
-the image is processed, and there might be a short delay and getting the response.
-
-However, dragonfly apps send `Cache-Control` and `ETag` headers in the response, so we can easily put a caching
-proxy like {http://varnish.projects.linpro.no Varnish}, {http://www.squid-cache.org Squid},
-{http://rtomayko.github.com/rack-cache/ Rack::Cache}, etc. in front of the app, so that subsequent requests are served
-super-quickly straight out of the cache.
-
-The file 'dragonfly/rails/images' puts Rack::Cache in front of Dragonfly by default, but for better performance
-you may wish to look into something like Varnish.
-
-Given a dragonfly app
-
-    app = Dragonfly[:images]
-
-You can configure the 'Cache-Control' header with
-
-    app.cache_duration = 3600*24*365*3  # time in seconds
-
-For a well-written discussion of Cache-Control and ETag headers, see {http://tomayko.com/writings/things-caches-do}.

data/extra_docs/Configuration.md

@@ -1,149 +0,0 @@
-Configuration
-=============
-
-Given a Dragonfly app
-
-    app = Dragonfly[:app_name]
-
-Configuration can either be done using a block...
-
-    app.configure do |c|
-      c.url_format = '/media/:job'
-      # ...
-    end
-
-...or directly...
-
-    app.url_format = '/media/:job'
-
-The defaults should be fairly sensible, but you can tweak a number of things if you wish.
-Here is an example of an app with all attributes configured:
-
-    app.configure do |c|
-      c.datastore = SomeCustomDataStore.new :egg => 'head'  # defaults to FileDataStore
-
-      c.cache_duration = 3600*24*365*2                      # defaults to 1 year # (1 year)
-      c.fallback_mime_type = 'something/mental'             # defaults to application/octet-stream
-      c.log = Logger.new($stdout)                           # defaults to Logger.new('/var/tmp/dragonfly.log')
-      c.trust_file_extensions = false                       # defaults to true
-
-      c.url_format = '/images/:job/:basename.:format'       # defaults to '/:job/:basename.:format'
-      c.url_host = 'http://some.domain.com:4000'            # defaults to nil
-
-      c.content_filename = proc{|job, request|              # defaults to the original name, with modified ext if encoded
-        "file.#{job.ext}"
-      }
-      c.content_disposition = :attachment                   # defaults to nil (use the browser default)
-
-      c.protect_from_dos_attacks = true                     # defaults to false - adds a SHA parameter on the end of urls
-      c.secret = 'This is my secret yeh!!'                  # should set this if concerned about DOS attacks
-
-      c.analyser.register(MyAnalyser)                       # See 'Analysers' for more details
-      c.processor.register(MyProcessor, :type => :fig)      # See 'Processing' for more details
-      c.encoder.register(MyEncoder) do |e|                  # See 'Encoding' for more details
-        e.some_value = 'geg'
-      end
-      c.generator.register(MyGenerator)                     # See 'Generators' for more details
-
-      c.register_mime_type(:egg, 'fried/egg')               # See 'MimeTypes' for more details
-
-      c.job :black_and_white do |size|                      # Job shortcut - lets you do image.black_and_white('30x30')
-        process :greyscale
-        process :thumb, size
-        encode  :gif
-      end
-      
-      c.define_url do |app, job, opts|                      # allows overriding urls - defaults to
-        if job.step_types == [:fetch]                       #   app.server.url_for(job, opts)
-          app.datastore.url_for(job.uid)
-        else
-          app.server.url_for(job, opts)
-        end
-      end
-      
-      c.server.before_serve do |job, env|                   # allows you to do something before content is served
-        # do something
-      end
-      
-      c.response_headers['X-Something'] = 'Custom header'   # You can set custom response headers
-      c.response_headers['summink'] = proc{|job, request|   # either directly or via a callback
-        job.image? ? 'image yo' : 'not an image'
-      }
-      
-      # When using ImageMagick only...
-      c.convert_command = "/opt/local/bin/convert"          # defaults to "convert"
-      c.identify_command = "/opt/local/bin/identify"        # defaults to "identify"
-      c.log_commands = true                                 # defaults to false
-    end
-
-Where is configuration done?
-----------------------------
-In Rails, it should be done in an initializer, e.g. 'config/initializers/dragonfly.rb'.
-Otherwise it should be done anywhere where general setup is done, early on.
-
-Reflecting on configuration
----------------------------
-There are a few methods you can call on the `app` to see what processors etc. are registered: `processor_methods`, `generator_methods`, `analyser_methods` and `job_methods`.
-
-Saved configurations
-====================
-Saved configurations are useful if you often configure the app the same way.
-There are a number that are provided with Dragonfly:
-
-ImageMagick
------------
-
-    app.configure_with(:imagemagick)
-
-The {Dragonfly::ImageMagick::Config ImageMagick configuration} registers the app with the {Dragonfly::ImageMagick::Analyser ImageMagick Analyser}, {Dragonfly::ImageMagick::Processor ImageMagick Processor},
-{Dragonfly::ImageMagick::Encoder ImageMagick Encoder} and {Dragonfly::ImageMagick::Generator ImageMagick Generator}, and a number of job shortcuts.
-
-The file 'dragonfly/rails/images' does this for you.
-
-The processor, analyser, encoder and generator pass data around using tempfiles.
-
-Rails
------
-
-    app.configure_with(:rails)
-
-The {Dragonfly::Config::Rails Rails configuration} points the log to the Rails logger, configures the file data store root path, sets the url path prefix to '/media', and
-registers the {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} for helping with mime_type validations.
-
-The file 'dragonfly/rails/images' does this for you.
-
-Custom Saved Configuration
---------------------------
-You can create your own saved configuration with any object that responds to 'apply_configuration':
-
-    module MyConfiguration
-
-      def self.apply_configuration(app, *args)
-        app.configure do |c|
-          c.url_path_prefix = '/hello/beans'
-          c.processor.register(MyProcessor)
-          # ...
-        end
-      end
-
-    end
-
-Then to configure:
-
-    app.configure_with(MyConfiguration, :any_other => :args)     # other args get passed through to apply_configuration
-
-You can also carry on configuring by passing a block
-
-    app.configure_with(MyConfiguration) do |c|
-      c.any_extra = :config_here
-      # ...
-    end
-
-If you wish to be able to use a symbol to represent your configuration (e.g. for a plugin, etc.) you can register it
-globally as a one-off:
-
-    Dragonfly::App.register_configuration(:myconfig){ My::Saved::Configuration }
-
-Then from then on you can configure Dragonfly apps using
-
-    app.configure_with(:myconfig, :any_other => :args)

data/extra_docs/Couch.md

@@ -1,49 +0,0 @@
-CouchDB
-=====
-Dragonfly can be used with any ActiveModel-compatible model, and so you can use it with CouchDB using [CouchRest::Model](https://github.com/couchrest/couchrest_model).
-
-Since CouchDB allows you to store files directly on documents as attachments, you can also use the supplied {Dragonfly::DataStorage::CouchDataStore CouchDataStore}.
-which allows storing files as attachments directly on documents.
-
-For more info about ActiveModel, see {file:Models}.
-
-For more info about using the Couch data store, see {file:DataStorage}.
-
-Example setup in Rails, using CouchRest::Model
--------------------------------------
-In config/initializers/dragonfly.rb:
-
-    require 'dragonfly'
-
-    app = Dragonfly[:images]
-
-    # Get database config from config/couchdb.yml
-    couch_settings = YAML.load_file(Rails.root.join('config/couchdb.yml'))[Rails.env]
-
-    # Configure to use ImageMagick, Rails defaults, and the Couch data store
-    app.configure_with(:imagemagick)
-    app.configure_with(:rails) do |c|
-      c.datastore = Dragonfly::DataStorage::CouchDataStore.new(
-        :host => couch_settings['host'],
-        :port => couch_settings['port'],
-        :username => couch_settings['username'],
-        :password => couch_settings['password'],
-        :database => couch_settings['database']
-      )
-    end
-
-    # Allow all CouchRest::Model models to use the macro 'image_accessor'
-    app.define_macro(CouchRest::Model::Base, :image_accessor)
-
-    # ... any other setup, see Rails docs
-
-Then in models:
-
-    class Album < CouchRest::Model::Base
-      property :cover_image_uid
-      image_accessor :cover_image
-
-      # ...
-    end
-
-See {file:Models} for more info.

data/extra_docs/DataStorage.md

@@ -1,226 +0,0 @@
-Data Storage
-============
-Each dragonfly app has a key-value datastore to store the content (originals only).
-
-Lets say we have an app
-
-    app = Dragonfly[:my_app_name]
-
-Then we can store data like so:
-
-    # Can pass in a String, Pathname, File or Tempfile
-    uid = app.store('SOME CONTENT')
-
-We can also save metadata at the same time, and any other options the configured datastore accepts
-
-    uid = app.store('SOME CONTENT',
-      :meta => {:time => Time.now, :name => 'content.txt'},
-      :some => 'option'
-    )
-
-We can get content with
-
-    content = app.fetch(uid)
-    content.data         # "SOME CONTENT"
-
-We can also get the extra saved attributes
-
-    content.meta         # {:time => Sat Aug 14 12:04:13 +0100 2010, :name => 'content.txt'}
-    content.name         # 'content.txt'
-
-We can destroy it with
-
-    app.destroy(uid)
-
-Serving directly from the datastore
------------------------------------
-Datastores can optionally serve data directly too, by implementing `url_for`
-
-    app.datastore.url_for(uid, :some => 'option')   # ---> "http://some.url/thing.txt"
-
-or (the same)
-
-    app.remote_url_for(uid, :some => 'option')
-
-or
-
-    my_model.attachment.remote_url(:some => 'option')
-
-You can create your own datastore, or use one of the provided ones as outlined below.
-
-File datastore
---------------
-The {Dragonfly::DataStorage::FileDataStore FileDataStore} stores data on the local filesystem.
-
-It is used by default.
-
-If for whatever reason you need to configure it again:
-
-    # shouldn't need this - it is the default
-    app.datastore = Dragonfly::DataStorage::FileDataStore.new
-
-    app.datastore.configure do |d|
-      d.root_path = '/filesystem/path/public/place'   # defaults to /var/tmp/dragonfly
-      d.server_root = '/filesystem/path/public'       # filesystem root for serving from - default to nil
-      d.store_meta = false                            # default to true - can be switched off to avoid
-                                                      #  saving an extra .meta file if meta not needed
-    end
-
-You can serve directly from the FileDataStore if the `server_root` is set.
-
-To customize the storage path (and therefore the uid), use the `:path` option on store
-
-    app.store("SOME CONTENT", :path => 'some/path.txt')
-
-To do this on a per-model basis see {file:Models#Storage_options}.
-
-**BEWARE!!!!** you must make sure the path (which will become the uid for the content) is unique and changes each time the content
-is changed, otherwise you could have caching problems, as the generated urls will be the same for the same uid.
-
-S3 datastore
-------------
-To configure with the {Dragonfly::DataStorage::S3DataStore S3DataStore}:
-
-    app.datastore = Dragonfly::DataStorage::S3DataStore.new
-
-    app.datastore.configure do |c|
-      c.bucket_name = 'my_bucket'
-      c.access_key_id = 'salfjasd34u23'
-      c.secret_access_key = '8u2u3rhkhfo23...'
-      c.region = 'eu-west-1'                        # defaults to 'us-east-1'
-      c.storage_headers = {'some' => 'thing'}       # defaults to {'x-amz-acl' => 'public-read'}
-      c.url_scheme = 'https'                        # defaults to 'http'
-      c.url_host = 'some.custom.host'               # defaults to "<bucket_name>.s3.amazonaws.com"
-    end
-
-You can also pass these options to `S3DataStore.new` as an options hash.
-
-You can serve directly from the S3DataStore using e.g.
-
-    my_model.attachment.remote_url
-
-or with an expiring url:
-
-    my_model.attachment.remote_url(:expires => 3.days.from_now)
-
-or with an https url:
-
-    my_model.attachment.remote_url(:scheme => 'https')   # also configurable for all urls with 'url_scheme'
-
-or with a custom host:
-
-    my_model.attachment.remote_url(:host => 'custom.domain')   # also configurable for all urls with 'url_host'
-
-Extra options you can use on store are `:path` and `:headers`
-
-    app.store("SOME CONTENT", :path => 'some/path.txt', :headers => {'x-amz-acl' => 'public-read-write'})
-
-To do this on a per-model basis see {file:Models#Storage_options}.
-
-**BEWARE!!!!** you must make sure the path (which will become the uid for the content) is unique and changes each time the content
-is changed, otherwise you could have caching problems, as the generated urls will be the same for the same uid.
-
-Mongo datastore
----------------
-To configure with the {Dragonfly::DataStorage::MongoDataStore MongoDataStore}:
-
-    app.datastore = Dragonfly::DataStorage::MongoDataStore.new
-
-It won't normally need configuring, but if you wish to:
-
-    app.datastore.configure do |d|
-      c.host = 'http://egg.heads:5000'                  # defaults to localhost
-      c.port = '27018'                                  # defaults to mongo default (27017)
-      c.database = 'my_database'                        # defaults to 'dragonfly'
-      c.username = 'some_user'                          # only needed if mongo is running in auth mode
-      c.password = 'some_password'                      # only needed if mongo is running in auth mode
-      c.connection_opts = {:name => 'prod'}             # arg gets passed to Mongo::Connection
-                                                        #  or Mongo::ReplSetConnection initializer - see http://api.mongodb.org/ruby/current
-      
-      c.hosts = ['localhost:30000', 'localhost:30001']  # will use Mongo::ReplSetConnection instead of Mongo::Connection
-    end
-
-If you already have a mongo database or connection available, you can skip setting these and set `db` or `connection` instead.
-
-You can also pass any options to `MongoDataStore.new` as an options hash.
-
-You can't serve directly from the mongo datastore.
-
-You can optionally pass in a `:content_type` option to `store` to tell it the content's MIME type.
-
-Couch datastore
----------------
-To configure with the {Dragonfly::DataStorage::CouchDataStore CouchDataStore}:
-
-    app.datastore = Dragonfly::DataStorage::CouchDataStore.new
-
-To configure:
-
-    app.datastore.configure do |d|
-      c.host = 'localhost'                            # defaults to localhost
-      c.port = '5984'                                 # defaults to couchdb default (5984)
-      c.database = 'dragonfly'                        # defaults to 'dragonfly'
-      c.username = ''                                 # not needed if couchdb is in 'admin party' mode
-      c.password = ''                                 # not needed if couchdb is in 'admin party' mode
-    end
-
-You can also pass these options to `CouchDataStore.new` as an options hash.
-
-You can serve directly from the couch datastore.
-
-You can optionally pass in a `:content_type` option to `store` to tell it what to use for its 'Content-Type' header.
-
-Custom datastore
-----------------
-Data stores are key-value in nature, and need to implement 3 methods: `store`, `retrieve` and `destroy`.
-
-    class MyDataStore
-
-      def store(temp_object, opts={})
-        # ... use temp_object.data, temp_object.file, temp_object.path, etc.
-        # ... also we can use temp_object.meta and store it ...
-        
-        # store and return the uid
-        'return_some_unique_uid'
-      end
-
-      def retrieve(uid)
-        # return an array containing
-        [
-          content,          # either a File, String or Tempfile
-          meta_data         # Hash - :name and :format are treated specially,
-        ]                   #  e.g. job.name is taken from job.meta[:name]
-      end
-
-      def destroy(uid)
-        # find the content and destroy
-      end
-
-    end
-
-You can now configure the app to use your datastore:
-
-    Dragonfly[:my_app_name].datastore = MyDataStore.new
-
-Notice that `store` takes a second `opts` argument.
-Any options, get passed here.
-`:meta` is treated specially and is accessible inside `MyDataStore#store` as `temp_object.meta`
-
-    uid = app.store('SOME CONTENT',
-      :meta => {:name => 'great_content.txt'},
-      :some_other => :option
-    )
-
-    # ...
-
-You can also optionally serve data directly from the datastore if it implements `url_for`:
-
-    class MyDataStore
-
-      # ...
-
-      def url_for(uid, opts={})
-        "http://some.domain/#{uid}"
-      end
-
-    end