Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Updated documentation #9

Merged
merged 2 commits into from

2 participants

@akzhan

YARD and Markdown.

@phallstrom
Owner

Akzhan - Looks good. Couple of questions (more curious than anything else).

Why did you change def options=(opts = {}) to def options=(value = {}) ? Does YARD like 'value' over 'opts'?

And in two other methods you removed the default value of {} from the argument. Was there a reason for that?

@akzhan

@phallstrom Yard likes default values.

There is another issue: You can't call these methods without options/params simply because some of its options/params are required - as seen by code (and now by documentation).

@akzhan

Oops, You ask for something totally different :)

Yes, !@attribute declaration looks only for value parameter for setters. It's Yard restriction for now.

@akzhan

It's can be simply overriden, but there is another problem.

options= isn't setter. It should be removed due to its inadequate behaviour.

@phallstrom phallstrom merged commit 20369d5 into phallstrom:master
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on May 26, 2012
  1. @akzhan

    Change markup to GFM.

    akzhan authored
  2. @akzhan

    YARD documentation (basics)

    akzhan authored
This page is out of date. Refresh to see the latest.
View
4 .gitignore
@@ -1,3 +1,5 @@
*.swp
-pkg
+pkg/
Gemfile.lock
+doc/
+.yardoc/
View
7 .yardopts
@@ -0,0 +1,7 @@
+--no-private
+--title 'elFinder server side connector for Ruby'
+--charset utf-8
+--readme README.md
+-
+README.md
+TODO
View
298 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.
View
3  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
View
2  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
View
7 lib/el_finder/base64.rb
@@ -5,10 +5,17 @@
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
View
53 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 @@ class Connector
: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 @@ class Connector
: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 @@ def initialize(options = {})
@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 @@ def from_hash(hash)
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 @@ def remove_target(target)
end
end
- #
def mime_handler
@options[:mime_handler]
end
View
2  lib/el_finder/image.rb
@@ -4,6 +4,8 @@
module ElFinder
+ # Represents default image handler.
+ # It uses *mogrify* to resize images and *convert* to create thumbnails.
class Image
def self.size(pathname)
View
7 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 @@ class MimeType
'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'
View
2  lib/el_finder/version.rb
@@ -1,3 +1,5 @@
+# Represents ElFinder namespace.
module ElFinder
+ # Gem version.
VERSION = '1.0.20'
end
Something went wrong with that request. Please try again.