el_finder 1.0.20 → 1.0.21

data/.gitignore

@@ -1,3 +1,5 @@
 *.swp
-pkg
+pkg/
 Gemfile.lock
+doc/
+.yardoc/

data/.yardopts

@@ -0,0 +1,7 @@
+--no-private
+--title 'elFinder server side connector for Ruby'
+--charset utf-8
+--readme README.md
+-
+README.md
+TODO

data/{README.rdoc → README.md}

@@ -1,142 +1,156 @@
-== el_finder
-
-* http://elrte.org/redmine/projects/elfinder
-
-== Description:
-
-Ruby library to provide server side functionality for elFinder.  elFinder is an
-open-source file manager for web, written in JavaScript using jQuery UI.
-
-== Todo:
-
-* Document library.
-* Document how to implement custom image size/resize methods.
-
-== Requirements:
-
-The gem, by default, relies upon the 'image_size' ruby gem and ImageMagick's 'mogrify' and 'convert' commands.
-These requirements can be changed by implementing custom methods for determining image size
-and resizing of an image.
-
-NOTE: There is another ruby gem 'imagesize' that also defines the class ImageSize and requires 'image_size'
-If you have that one installed, elfinder will fail.  Make sure you only have 'image_size' installed if you use
-the defaults.
-
-== Install:
-
-* Install elFinder (http://elrte.org/redmine/projects/elfinder/wiki/Install_EN)
-* Install ImageMagick (http://www.imagemagick.org/)
-* Do whatever is necessary for your Ruby framework to tie it together.
-
-=== Rails 3
-
-* Add "gem 'el_finder'" to Gemfile
-* % bundle install
-* Switch to using jQuery instead of Prototype
-* Add the following action to a controller of your choosing.
-
-    skip_before_filter :verify_authenticity_token, :only => ['elfinder']
-    def elfinder
-      h, r = ElFinder::Connector.new(
-        :root => File.join(Rails.public_path, 'system', 'elfinder'),
-        :url => '/system/elfinder',
-         :perms => {
-           /^(Welcome|README)$/ => {:read => true, :write => false, :rm => false},
-           '.' => {:read => true, :write => false, :rm => false}, # '.' is the proper way to specify the home/root directory.
-           /^test$/ => {:read => true, :write => true, :rm => false},
-           'logo.png' => {:read => true},
-           /\.png$/ => {:read => false} # This will cause 'logo.png' to be unreadable.  
-                                        # Permissions err on the safe side. Once false, always false.
-         },
-         :extractors => { 
-           'application/zip' => ['unzip', '-qq', '-o'], # Each argument will be shellescaped (also true for archivers)
-           'application/x-gzip' => ['tar', '-xzf'],
-         },
-         :archivers => { 
-           'application/zip' => ['.zip', 'zip', '-qr9'], # Note first argument is archive extension
-           'application/x-gzip' => ['.tgz', 'tar', '-czf'],
-           },
-
-      ).run(params)
-      headers.merge!(h)
-      render (r.empty? ? {:nothing => true} : {:text => r.to_json}), :layout => false
-    end
-
-* Or, use ElFinder::Action and el_finder, which handles most of the boilerplate for an ElFinder action:
-
-    require 'el_finder/action'
-    class MyController < ApplicationController
-      include ElFinder::Action
-
-      el_finder(:action_name) do
-        {
-          :root => File.join(Rails.public_path, 'system', 'elfinder'),
-          :url => '/system/elfinder',
-           :perms => {
-             /^(Welcome|README)$/ => {:read => true, :write => false, :rm => false},
-             '.' => {:read => true, :write => false, :rm => false}, # '.' is the proper way to specify the home/root directory.
-             /^test$/ => {:read => true, :write => true, :rm => false},
-             'logo.png' => {:read => true},
-             /\.png$/ => {:read => false} # This will cause 'logo.png' to be unreadable.  
-                                          # Permissions err on the safe side. Once false, always false.
-          },
-          :extractors => { 
-            'application/zip' => ['unzip', '-qq', '-o'], # Each argument will be shellescaped (also true for archivers)
-            'application/x-gzip' => ['tar', '-xzf'],
-          },
-          :archivers => { 
-            'application/zip' => ['.zip', 'zip', '-qr9'], # Note first argument is archive extension
-            'application/x-gzip' => ['.tgz', 'tar', '-czf'],
-          },
-        }
-      end
-    end
-
-* Add the appropriate route to config/routes.rb such as:
-
-    match 'elfinder' => 'home#elfinder'
-
-* Add the following to your layout. The paths may be different depending 
-on where you installed the various js/css files.
-
-    <%= stylesheet_link_tag 'jquery-ui/base/jquery.ui.all', 'elfinder' %>
-    <%= javascript_include_tag :defaults, 'elfinder/elfinder.min' %>
-
-* Add the following to the view that will display elFinder:
-
-    <%= javascript_tag do %>
-      $().ready(function() { 
-        $('#elfinder').elfinder({ 
-          url: '/elfinder',
-          lang: 'en'
-        })
-      })
-    <% end %>
-    <div id='elfinder'></div>
-
-* That's it.  I think.  If not, check out the example rails application at http://github.com/phallstrom/el_finder-rails-example.
-
-== License:
-
-(The MIT License)
-
-Copyright (c) 2010 Philip Hallstrom
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+## el_finder
+
+* http://elrte.org/redmine/projects/elfinder
+
+## Description:
+
+Ruby library to provide server side functionality for elFinder.  elFinder is an
+open-source file manager for web, written in JavaScript using jQuery UI.
+
+## Todo:
+
+* Document library.
+* Document how to implement custom image size/resize methods.
+
+## Requirements:
+
+The gem, by default, relies upon the 'image_size' ruby gem and ImageMagick's 'mogrify' and 'convert' commands.
+These requirements can be changed by implementing custom methods for determining image size
+and resizing of an image.
+
+NOTE: There is another ruby gem 'imagesize' that also defines the class ImageSize and requires 'image_size'
+If you have that one installed, elfinder will fail.  Make sure you only have 'image_size' installed if you use
+the defaults.
+
+## Install:
+
+* Install elFinder (http://elrte.org/redmine/projects/elfinder/wiki/Install_EN)
+* Install ImageMagick (http://www.imagemagick.org/)
+* Do whatever is necessary for your Ruby framework to tie it together.
+
+### Rails 3
+
+* Add `gem 'el_finder'` to Gemfile
+* % bundle install
+* Switch to using jQuery instead of Prototype
+* Add the following action to a controller of your choosing.
+
+```ruby
+  skip_before_filter :verify_authenticity_token, :only => ['elfinder']
+
+  def elfinder
+    h, r = ElFinder::Connector.new(
+      :root => File.join(Rails.public_path, 'system', 'elfinder'),
+      :url => '/system/elfinder',
+       :perms => {
+         /^(Welcome|README)$/ => {:read => true, :write => false, :rm => false},
+         '.' => {:read => true, :write => false, :rm => false}, # '.' is the proper way to specify the home/root directory.
+         /^test$/ => {:read => true, :write => true, :rm => false},
+         'logo.png' => {:read => true},
+         /\.png$/ => {:read => false} # This will cause 'logo.png' to be unreadable.  
+                                      # Permissions err on the safe side. Once false, always false.
+       },
+       :extractors => { 
+         'application/zip' => ['unzip', '-qq', '-o'], # Each argument will be shellescaped (also true for archivers)
+         'application/x-gzip' => ['tar', '-xzf'],
+       },
+       :archivers => { 
+         'application/zip' => ['.zip', 'zip', '-qr9'], # Note first argument is archive extension
+         'application/x-gzip' => ['.tgz', 'tar', '-czf'],
+         },
+
+    ).run(params)
+
+    headers.merge!(h)
+
+    render (r.empty? ? {:nothing => true} : {:text => r.to_json}), :layout => false
+  end
+```
+
+* Or, use ElFinder::Action and el_finder, which handles most of the boilerplate for an ElFinder action:
+
+```ruby
+  require 'el_finder/action'
+
+  class MyController < ApplicationController
+    include ElFinder::Action
+
+    el_finder(:action_name) do
+      {
+        :root => File.join(Rails.public_path, 'system', 'elfinder'),
+        :url => '/system/elfinder',
+         :perms => {
+           /^(Welcome|README)$/ => {:read => true, :write => false, :rm => false},
+           '.' => {:read => true, :write => false, :rm => false}, # '.' is the proper way to specify the home/root directory.
+           /^test$/ => {:read => true, :write => true, :rm => false},
+           'logo.png' => {:read => true},
+           /\.png$/ => {:read => false} # This will cause 'logo.png' to be unreadable.  
+                                        # Permissions err on the safe side. Once false, always false.
+        },
+        :extractors => { 
+          'application/zip' => ['unzip', '-qq', '-o'], # Each argument will be shellescaped (also true for archivers)
+          'application/x-gzip' => ['tar', '-xzf'],
+        },
+        :archivers => { 
+          'application/zip' => ['.zip', 'zip', '-qr9'], # Note first argument is archive extension
+          'application/x-gzip' => ['.tgz', 'tar', '-czf'],
+        },
+      }
+    end
+  end
+```
+
+* Add the appropriate route to config/routes.rb such as:
+
+```ruby
+  match 'elfinder' => 'home#elfinder'
+```
+
+* Add the following to your layout. The paths may be different depending 
+on where you installed the various js/css files.
+
+```erb
+  <%= stylesheet_link_tag 'jquery-ui/base/jquery.ui.all', 'elfinder' %>
+  <%= javascript_include_tag :defaults, 'elfinder/elfinder.min' %>
+```
+
+* Add the following to the view that will display elFinder:
+
+```erb
+  <%= javascript_tag do %>
+    $().ready(function() { 
+      $('#elfinder').elfinder({ 
+        url: '/elfinder',
+        lang: 'en'
+      })
+    })
+  <% end %>
+  <div id='elfinder'></div>
+```
+
+* That's it.  I think.  If not, check out the example rails application at http://github.com/phallstrom/el_finder-rails-example.
+
+## License:
+
+(The MIT License)
+
+Copyright (c) 2010 Philip Hallstrom
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -9,3 +9,6 @@ Rake::TestTask.new(:test) do |test|
   test.pattern = 'test/**/test_*.rb'
   test.verbose = true
 end
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/el_finder.gemspec

@@ -20,6 +20,8 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_dependency('image_size', '>= 1.0.0')
+  s.add_development_dependency('yard', '~> 0.8.1')
+  s.add_development_dependency('redcarpet', '~> 2.1.1')
   s.requirements << 'ImageMagick'
 
 end

data/lib/el_finder/base64.rb

@@ -5,10 +5,17 @@ if RUBY_VERSION < '1.9'
   end
 
   if defined? ::Base64
+    # The Base64 module provides for the encoding (encode64, strict_encode64, urlsafe_encode64) and decoding (decode64, strict_decode64, urlsafe_decode64) of binary data using a Base64 representation.
+    # @note stdlib module.
     module ::Base64
+      # Returns the Base64-encoded version of bin. This method complies with "Base 64 Encoding with URL and Filename Safe Alphabet" in RFC 4648. The alphabet uses '-' instead of '+' and '_' instead of '/'.
+      # @note This method will be defined only on ruby 1.8 due to its absence in stdlib.
       def self.urlsafe_encode64(bin)
         [bin].pack("m0").tr("+/", "-_")
       end
+
+      # Returns the Base64-decoded version of str. This method complies with "Base 64 Encoding with URL and Filename Safe Alphabet" in RFC 4648. The alphabet uses '-' instead of '+' and '_' instead of '/'.
+      # @note This method will be defined only on ruby 1.8 due to its absence in stdlib.
       def self.urlsafe_decode64(str)
         str.tr("-_", "+/").unpack("m0").first
       end

data/lib/el_finder/connector.rb

@@ -5,14 +5,20 @@
 require 'base64'
 
 module ElFinder
+
+  # Represents ElFinder connector on Rails side.
   class Connector
-    
+
+    # Valid commands to run.
+    # @see #run
     VALID_COMMANDS = %w[archive duplicate edit extract mkdir mkfile open paste ping read rename resize rm tmb upload]
 
+    # Default options for instances.
+    # @see #initialize
     DEFAULT_OPTIONS = {
       :mime_handler => ElFinder::MimeType,
       :image_handler => ElFinder::Image,
-      :original_filename_method => lambda {|file| file.original_filename},
+      :original_filename_method => lambda { |file| file.original_filename },
       :disabled_commands => [],
       :allow_dot_files => true,
       :upload_max_size => '50M',
@@ -20,7 +26,7 @@ module ElFinder
       :archivers => {},
       :extractors => {},
       :home => 'Home',
-      :default_perms => {:read => true, :write => true, :rm => true, :hidden => false },
+      :default_perms => { :read => true, :write => true, :rm => true, :hidden => false },
       :perms => [],
       :thumbs => false,
       :thumbs_directory => '.thumbs',
@@ -28,14 +34,18 @@ module ElFinder
       :thumbs_at_once => 5,
     }
 
-    #
-    def initialize(options = {})
+    # Initializes new instance.
+    # @param [Hash] options Instance options. :url and :root options are required.
+    # @option options [String] :url Entry point of ElFinder router.
+    # @option options [String] :root Root directory of ElFinder directory structure.
+    # @see DEFAULT_OPTIONS
+    def initialize(options)
       @options = DEFAULT_OPTIONS.merge(options)
 
-      raise(RuntimeError, "Missing required :url option") unless @options.key?(:url) 
-      raise(RuntimeError, "Missing required :root option") unless @options.key?(:root) 
-      raise(RuntimeError, "Mime Handler is invalid") unless mime_handler.respond_to?(:for)
-      raise(RuntimeError, "Image Handler is invalid") unless image_handler.nil? || ([:size, :resize, :thumbnail].all?{|m| image_handler.respond_to?(m)})
+      raise(ArgumentError, "Missing required :url option") unless @options.key?(:url) 
+      raise(ArgumentError, "Missing required :root option") unless @options.key?(:root) 
+      raise(ArgumentError, "Mime Handler is invalid") unless mime_handler.respond_to?(:for)
+      raise(ArgumentError, "Image Handler is invalid") unless image_handler.nil? || ([:size, :resize, :thumbnail].all?{|m| image_handler.respond_to?(m)})
 
       @root = ElFinder::Pathname.new(options[:root])
 
@@ -43,8 +53,11 @@ module ElFinder
       @response = {}
     end # of initialize
 
-    #
-    def run(params = {})
+    # Runs request-response cycle.
+    # @param [Hash] params Request parameters. :cmd option is required.
+    # @option params [String] :cmd Command to be performed.
+    # @see VALID_COMMANDS
+    def run(params)
       @params = params.dup
       @headers = {}
       @response = {}
@@ -89,19 +102,22 @@ module ElFinder
 
       pathname = @root + Base64.urlsafe_decode64(hash)
     rescue ArgumentError => e
-      if e.message == 'invalid base64'
-        nil
-      else
+      if e.message != 'invalid base64'
         raise
       end
+      nil
     end # of from_hash
 
-    #
-    def options=(opts = {})
-      opts.each_pair do |k,v|
+    # @!attribute [w] options
+    # Options setter.
+    # @param value [Hash] Options to be merged with instance ones.
+    # @return [Hash] Updated options.
+    def options=(value = {})
+      value.each_pair do |k, v|
         @options[k.to_sym] = v
       end
-    end
+      @options
+    end # of options=
 
     ################################################################################
     protected
@@ -433,7 +449,6 @@ module ElFinder
       end
     end
 
-    #
     def mime_handler
       @options[:mime_handler]
     end

data/lib/el_finder/image.rb

@@ -4,6 +4,8 @@ require 'image_size'
 
 module ElFinder
 
+  # Represents default image handler.
+  # It uses *mogrify* to resize images and *convert* to create thumbnails.
   class Image
 
     def self.size(pathname)

data/lib/el_finder/mime_type.rb

@@ -1,7 +1,9 @@
 module ElFinder
 
+  # Represents default MIME types recognizer.
   class MimeType
 
+    # File extension to mime type mapping.
     TYPES = {
       'ai'    => 'application/postscript',
       'eps'   => 'application/postscript',
@@ -67,7 +69,10 @@ module ElFinder
       'flv'   => 'video/x-flv',
       'mkv'   => 'video/x-matroska'
     }
-		
+
+    # Gets MIME type fort specified path.
+    # @param [::Pathname, String] pathname Path to recognize its MIME type.
+    # @return [String] MIME type if known; 'unknown/unknown' otherwise.
     def self.for(pathname)
       pathname = ::Pathname.new(pathname) if pathname.is_a?(String)
       TYPES[pathname.extname.downcase[1..-1]] || 'unknown/unknown'

data/lib/el_finder/version.rb

@@ -1,3 +1,5 @@
+# Represents ElFinder namespace.
 module ElFinder
-  VERSION = '1.0.20'
+  # Gem version.
+  VERSION = '1.0.21'
 end 

data/test/test_el_finder.rb

@@ -7,25 +7,25 @@ class TestElFinder < Test::Unit::TestCase
   ################################################################################
 
   def test_should_fail_initialization_if_required_options_not_passed
-    assert_raise RuntimeError do
+    assert_raise ArgumentError do
       ElFinder::Connector.new()
     end
   end
 
   def test_should_fail_initialization_if_no_root_specified
-    assert_raise RuntimeError do
+    assert_raise ArgumentError do
       ElFinder::Connector.new({:url => '/elfinder'})
     end
   end
 
   def test_should_fail_initialization_if_no_url_specified
-    assert_raise RuntimeError do
+    assert_raise ArgumentError do
       ElFinder::Connector.new({:root => '/tmp/elfinder'})
     end
   end
 
   def test_should_fail_initialization_if_mime_handler_is_invalid
-    assert_raise RuntimeError do
+    assert_raise ArgumentError do
       ElFinder::Connector.new({:root => '/tmp/elfinder', :url => '/elfinder', :mime_handler => Object})
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: el_finder
 version: !ruby/object:Gem::Version 
-  hash: 63
+  hash: 61
   prerelease: 
   segments: 
   - 1
   - 0
-  - 20
-  version: 1.0.20
+  - 21
+  version: 1.0.21
 platform: ruby
 authors: 
 - Philip Hallstrom
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-04-02 00:00:00 Z
+date: 2012-05-26 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: image_size
@@ -33,6 +33,38 @@ dependencies:
         version: 1.0.0
   type: :runtime
   version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 61
+        segments: 
+        - 0
+        - 8
+        - 1
+        version: 0.8.1
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: redcarpet
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 2
+        - 1
+        - 1
+        version: 2.1.1
+  type: :development
+  version_requirements: *id003
 description: Ruby library to provide server side functionality for elFinder.  elFinder is an open-source file manager for web, written in JavaScript using jQuery UI.
 email: 
 - philip@pjkh.com
@@ -45,8 +77,9 @@ extra_rdoc_files: []
 files: 
 - .autotest
 - .gitignore
+- .yardopts
 - Gemfile
-- README.rdoc
+- README.md
 - Rakefile
 - TODO
 - el_finder.gemspec
@@ -132,3 +165,4 @@ test_files:
 - test/test_el_finder_permissions.rb
 - test/test_el_finder_symlink.rb
 - test/test_el_finder_thumbs.rb
+has_rdoc: