ramaze 2009.03 → 2009.04

data/lib/ramaze/helper/formatting.rb

@@ -3,6 +3,34 @@
 
 module Ramaze
   module Helper::Formatting
+    module_function
+
+    FORMATTING_NUMBER_COUNTER = { 0 => 'no', 2 => 'two', 3 => 'three',
+      4 => 'four', 5 => 'five', 6 => 'six', 7 => 'seven', 8 => 'eight',
+      9 => 'nine', 10 => 'ten' }
+
+    # Answers with a representation of given +count+ with correct grammar.
+    # If no +items+ argument is given, and the +count+ argument is not 1, then
+    # we first check whether the +item+ argument responds to #pluralize (for
+    # example if you are using Sequel). If this doesn't work we append 's' to
+    # the +item+ argument.
+    #
+    # @example usage
+    #   numeric_counter(0, 'comment') # => 'no comments'
+    #   numeric_counter(1, 'comment') # => 'one comment'
+    #   numeric_counter(2, 'comment') # => '2 comments'
+
+    def number_counter(count, item, items = nil)
+      count, item = count.to_i, item.to_s
+
+      if count == 1
+        "one #{item}"
+      else
+        items ||= item.respond_to?(:pluralize) ? item.pluralize : "#{item}s"
+        prefix = FORMATTING_NUMBER_COUNTER[count] || count
+        "#{prefix} #{items}"
+      end
+    end
 
     # Format a floating number nicely for display.
     #
@@ -44,7 +72,7 @@ module Ramaze
     end
 
     # stolen and adapted from rails
-    def time_diff from_time, to_time = Time.now, include_seconds = false
+    def time_diff(from_time, to_time = Time.now, include_seconds = false)
       distance_in_minutes = (((to_time - from_time).abs)/60).round
       distance_in_seconds = ((to_time - from_time).abs).round if include_seconds
 
@@ -121,10 +149,9 @@ module Ramaze
     end
 
     # Maybe port to ruby < 1.8.7 ?
-    def obfuscate_email(string)
-      string = string.to_s
-      text = string.each_byte.map{|c| "&#%03d" % c}.join
-      %(<a href="mailto:#{string}">#{text}</a>)
+    def obfuscate_email(email, text = nil)
+      obfuscated = email.to_s.each_byte.map{|c| "&#%03d" % c}.join
+      %(<a href="mailto:#{obfuscated}">#{text || obfuscated}</a>)
     end
 
     # Returns Hash with tags as keys and their weight as value.

data/lib/ramaze/helper/gestalt.rb

@@ -1,4 +1,4 @@
-require 'gestalt'
+require 'ramaze/gestalt'
 
 module Ramaze
   module Helper

data/lib/ramaze/helper/gravatar.rb

@@ -1,31 +1,78 @@
 module Ramaze
   module Helper
+
+    # Helps you building Gravatar URIs from an email address.
+    #
+    # For more information about gravatars, please see: http://gravatar.com
+    #
+    # The implementation of the gravatar method changed significantly, it does
+    # less hand-holding but is more flexible so you can simply put your own
+    # helper on top.
+    #
+    # It might not know about all the secret parameters (like 'force'), if you
+    # find out more of these please consider contributing a patch.
     module Gravatar
 
-      # fetches a gravatar from http//www.gravatar.com based on 'email'
-      # and 'size'. Falls back to 'fallback_path' if no gravatar is found.
-      # default 'fallback_path' is "/images/gravatar_default.jpg".
-      # example:
+      # API to build gravatar URIs from an email address (or any other String).
       #
-      # class GravatarController < Ramaze::Controller
-      #    helper :gravatar
+      # @example Simple usage
       #
-      #    def index
-      #      @gravatar_thumbnail_src = gravatar(session[:email] || 'riku@helloit.fi')
-      #    end
-      # end
+      #   class Gravatars < Ramaze::Controller
+      #     helper :gravatar
       #
-      #  /view/gravatar/index.html:
-      #  <img src="#{@gravatar_thumbnail_src}" />
-
-      def gravatar(email, size = 32, fallback_path = "/images/gravatar_default.jpg")
-        emailhash = Digest::MD5.hexdigest(email)
+      #     def index
+      #       %q(
+      #       Input your email address and I'll show you your Gravatar
+      #       <form>
+      #         <input type="text" name="email" />
+      #         <input type="submit" />
+      #       </form>
+      #       <?r if email = request[:email] ?>
+      #         Your gravatar is:
+      #         <img src="#{gravatar(email)}" />
+      #       <?r end ?>
+      #       )
+      #     end
+      #   end
+      #
+      # @option opts [#to_s] :ext (nil)
+      #   append a filename extension for the image, like '.jpg'
+      #
+      # @option opts [#to_i] :size (80)
+      #   The size of the gravatar, square, so 80 is 80x80.
+      #   Allowed range is from 1 to 512.
+      #
+      # @option opts [#to_s] :rating ('g')
+      #   Only serve a gravatar if it has a content rating equal or below the
+      #   one specified. Ratings, in order are: 'g', 'pg', 'r', or 'x'
+      #
+      # @option opts [#to_s] :default (nil)
+      #   Fall back to default if the given +email+ doesn't have an gravatar;
+      #   may be an absolute url, 'identicon', 'monsterid', or 'wavatar'
+      #
+      # @options opts [true, false] :force (false)
+      #   Force use of the default avatar, useful if you want to use only
+      #   identicons or the like
+      #
+      # @param [#to_str] email
+      #
+      # @return [URI]
+      #
+      # @see http://en.gravatar.com/site/implement/url
+      # @author manveru
+      def gravatar(email, opts = {})
+        uri = URI("http://www.gravatar.com/")
+        ext = opts[:ext]
+        uri.path = "/avatar/#{Digest::MD5.hexdigest(email.to_str)}#{ext}"
 
-        fallback = Request.current.domain
-        fallback.path = fallback_path
-        default = Rack::Utils.escape(fallback.to_s)
+        query = {}
+        query[:size]    = opts[:size].to_i.to_s if opts.key?(:size)
+        query[:rating]  = opts[:rating].to_s if opts.key?(:rating)
+        query[:default] = opts[:default].to_s if opts.key?(:default)
+        query[:force]   = '1' if opts[:force]
 
-        return "http://www.gravatar.com/avatar.php?gravatar_id=#{emailhash}&default=#{default}&size=#{size}"
+        uri.query = Rack::Utils.build_query(query) if query.any?
+        uri
       end
     end
   end

data/lib/ramaze/helper/httpdigest.rb

@@ -1,93 +1,97 @@
-require 'uuid'
-require 'md5'
+begin
+  require 'securerandom' # Ruby >= 1.8.7
+rescue LoadError
+  require 'uuidtools'
+end
+
+require 'digest/md5'
 
 module Ramaze
   module Helper
+    # Authorization using HTTP Digest.
+    #
+    # For custom authorization failure handling add an {httpdigest_failure}
+    # method in your controller.
     module HttpDigest
 
-      UUID_GENERATOR = UUID.new
-
       SESSION_NONCE = 'httpdigest_authentication_nonce'
       SESSION_OPAQUE = 'httpdigest_authentication_opaque'
+      DIGEST_HEADER = %|Digest realm="%s", qop="auth,auth-int", nonce="%s", opaque="%s"|
 
+      # Delete the nonce and opaque from session to log out.
       def httpdigest_logout
-        session.delete( SESSION_NONCE )
-        session.delete( SESSION_OPAQUE )
+        session.delete(SESSION_NONCE)
+        session.delete(SESSION_OPAQUE)
       end
 
-      def httpdigest_headers uid, realm
-        session[ SESSION_NONCE ] = UUID_GENERATOR.generate
-        session[ SESSION_OPAQUE ][ realm ][ uid ] = UUID_GENERATOR.generate
-        response['WWW-Authenticate'] =
-          %|Digest realm="#{realm}",| +
-          %|qop="auth,auth-int",| +
-          %|nonce="#{session[SESSION_NONCE]}",| +
-          %|opaque="#{session[SESSION_OPAQUE][realm][uid]}"|
+      def httpdigest_uuid
+        ::SecureRandom.hex(32)
       end
 
-      def httpdigest(uid, realm)
-        session[ SESSION_OPAQUE ] ||= {}
-        session[ SESSION_OPAQUE ][ realm ] ||= {}
-
-        if request.env['HTTP_AUTHORIZATION']
+      # Set the WWW-Authenticate header and store relevant data in the session.
+      #
+      # @param [String] uid
+      # @param [String] realm
+      def httpdigest_headers(uid, realm)
+        nonce = session[SESSION_NONCE] = httpdigest_uuid
+        opaque = session[SESSION_OPAQUE][realm][uid] = httpdigest_uuid
+        response['WWW-Authenticate'] = DIGEST_HEADER % [realm, nonce, opaque]
+      end
 
-          authorized = false
+      def httpdigest_failure
+        respond 'Unauthorized', 401
+      end
 
-          if session[ SESSION_NONCE ] and session[ SESSION_OPAQUE ][ realm ][ uid ]
+      def httpdigest_http_authorization(uid, realm)
+        http_authorization = request.env['HTTP_AUTHORIZATION']
+        return http_authorization if http_authorization
 
-            auth_split = request.env['HTTP_AUTHORIZATION'].split
-            authentication_type = auth_split[0]
-            authorization = Rack::Auth::Digest::Params.parse( auth_split[1..-1].join(' ') )
+        httpdigest_headers(uid, realm)
+        httpdigest_failure
+      end
 
-            digest_response, username, nonce, nc, cnonce, qop, opaque =
-              authorization.values_at(*%w[response username nonce nc cnonce qop opaque])
+      def httpdigest_lookup(username, realm)
+        if block_given?
+          yield(username)
+        elsif respond_to?(:httpdigest_lookup_password)
+          httpdigest_lookup_password(username)
+        elsif respond_to?(:httpdigest_lookup_plaintext_password)
+          plain = httpdigest_lookup_plaintext_password(username)
+          Digest::MD5.hexdigest([username, realm, plain].join(':'))
+        else
+          raise "No password lookup handler found"
+        end
+      end
 
-            if authentication_type == 'Digest'
-              if nonce == session[SESSION_NONCE] and opaque == session[SESSION_OPAQUE][realm][uid]
-                h1 = nil
-                if respond_to?( :httpdigest_lookup_password )  
-                  ha1 = httpdigest_lookup_password( username )
-                else
-                  if respond_to?( :httpdigest_lookup_plaintext_password )
-                    ha1 = MD5.hexdigest( "#{username}:#{realm}:#{httpdigest_lookup_plaintext_password( username )}" )
-                  else
-                    if block_given?
-                      ha1 = yield( username )
-                    else
-                      raise "No password lookup handler found"
-                    end
-                  end
-                end
+      def httpdigest(uid, realm, &block)
+        session[SESSION_OPAQUE] ||= {}
+        session[SESSION_OPAQUE][realm] ||= {}
 
-                a2 = [request.request_method,request.fullpath]
-                a2 << MD5.hexdigest(request.body.read) if qop == "auth-int"
+        http_authorization = httpdigest_http_authorization(uid, realm)
 
-                ha2 = MD5.hexdigest( a2.join(':') )
+        httpdigest_failure unless session_nonce = session[SESSION_NONCE]
+        httpdigest_failure unless session_opaque = session[SESSION_OPAQUE][realm][uid]
 
-                md5 = MD5.hexdigest([ha1, nonce, nc, cnonce, qop, ha2].join(':'))
-                
-                authorized = digest_response == md5
-              end
-            end
+        auth_type, auth_raw = http_authorization.split(' ', 2)
+        httpdigest_failure unless auth_type == 'Digest'
 
-          end
+        authorization = Rack::Auth::Digest::Params.parse(auth_raw)
 
-          unless authorized
-            httpdigest_headers( uid, realm )
-            respond('Unauthorized', 401)
-          end
+        digest_response, username, nonce, nc, cnonce, qop, opaque =
+          authorization.values_at(*%w[response username nonce nc cnonce qop opaque])
 
-        else
+        httpdigest_failure unless nonce == session_nonce and opaque == session_opaque
 
-          httpdigest_headers( uid, realm )
-          httpdigest_failure if respond_to?( :httpdigest_failure )
-          respond('Unauthorized', 401)
+        ha1 = httpdigest_lookup(username, realm, &block)
+        a2 = [request.request_method,request.request_uri]
+        a2 << Digest::MD5.hexdigest(request.body.read) if qop == "auth-int"
+        ha2 = Digest::MD5.hexdigest( a2.join(':') )
+        md5 = Digest::MD5.hexdigest([ha1, nonce, nc, cnonce, qop, ha2].join(':'))
 
-        end
+        httpdigest_failure unless digest_response == md5
 
-        authorization["username"]
+        return username
       end
-
     end
   end
 end

data/lib/ramaze/helper/link.rb

@@ -1,122 +1,75 @@
-#          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
+#          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
 # All files in this distribution are subject to the terms of the Ruby license.
 
-module Ramaze
-  # Helper::Link is included into the Controller by default
-  #
-  # Usage is shown in spec/ramaze/helper/link.rb and the rdocs below.
-
-  module Helper::Link
-    # Builds a basic <a> tag.
-    #
-    # `text` is mandatory, the second hash of options will be transformed into
-    # arguments of the tag, :href is a special case and its segments will be
-    # escaped.
-    #
-    # If you pass no :href, the text will be run through Rs and its result is
-    # used instead. If you really want an empty href, use :href => ''
-    #
-    # Usage:
-    #   A('text')                       #> <a href="/text">text</a>
-    #   A('foo/bar')                    #> <a href="/foo/bar">foo/bar</a>
-    #   A('/foo?x=y')                   #> <a href="/foo?x=y">/foo?x=y</a>
-    #   A('text', :href => '/foo?x=y')  #> <a href="/foo?x=y">text</a>
-    #   A('Home', :href => Rs(:/))      #> <a href="/foo/bar">Home</a>
-
-    def A(*args)
-      hash = args.last.respond_to?(:to_hash) ? args.pop : {}
-
-      hash[:href] ||= Rs(*args)
-      text = hash.delete(:text) || args.last || hash[:title] || hash[:href]
-      hash[:href] = hash[:href].to_s.gsub(/[^\/?;=]+/){|m| Rack::Utils.escape(m) }
-
-      args = ['']
-      hash.each {|k,v| args << %(#{k}="#{v}") if k and v }
-
-      %(<a#{args.join(' ')}>#{text}</a>)
-    end
-
-    # Builds links out of segments.
-    #
-    # Pass it strings, symbols, controllers and it will produce a link out of
-    # it. Paths to Controllers are obtained from Global.mapping.
-    #
-    # For brevity, the mapping for the example below is following:
-    #   { MC => '/', OC => '/o', ODC => '/od' }
-    #
-    # Usage:
-    #   R(MC) #=> '/'
-    #   R(OC) #=> '/o'
-    #   R(ODC) #=> '/od'
-    #   R(MC, :foo) #=> '/foo'
-    #   R(OC, :foo) #=> '/o/foo'
-    #   R(ODC, :foo) #=> '/od/foo'
-    #   R(MC, :foo, :bar => :x) #=> '/foo?bar=x'
-
-    def R(*atoms)
-      args, atoms = atoms.flatten.partition{|a| a.is_a?(Hash) }
-      args = args.flatten.inject{|s,v| s.merge!(v) }
+require 'innate/helper/link'
 
-      map = Global.mapping.invert
-
-      atoms.map! do |atom|
-        if atom.is_a?(Ramaze::Controller)
-          map[atom.class]
-        else
-          map[atom]
-        end or atom.to_s
+module Ramaze
+  module Helper
+    # This is a modification of Innate::Helper::Link to respect the routing of
+    # Ramaze
+    # NOTE: The A/R/Rs methods have been deprecated.
+    module Link
+
+      # @return [String]
+      # @see Innate::Helper#anchor
+      def A(*args)
+        Ramaze.deprecated('Ramaze::Helper::Link#A', 'Ramaze::Helper::Link#a')
+        a(*args)
       end
 
-      front = [Global.prefix, *atoms].join('/').squeeze('/')
-
-      if args
-        rear = args.inject('?'){|s,(k,v)| s << "#{Rack::Utils.escape(k)}=#{Rack::Utils.escape(v)};"}[0..-2]
-        front + rear
-      else
-        front
+      # @return [String]
+      # @see Innate::Helper#route
+      def R(arg, *args)
+        Ramaze.deprecated('Ramaze::Helper::Link#R', 'Ramaze::Helper::Link#r')
+        (arg < Controller ? arg.r(*args) : r(arg, *args)).to_s
       end
-    end
 
-    # Uses R with Controller.current as first element.
-
-    def Rs(*atoms)
-      atoms.unshift Controller.current unless atoms.first.is_a?(Controller)
-      R(*atoms)
-    end
+      # @return [String]
+      # @see Innate::Helper#route
+      def Rs(*args)
+        Ramaze.deprecated('Ramaze::Helper::Link#Rs', 'Ramaze::Helper::Link#r')
+        r(*args).to_s
+      end
 
-    # Give it a path with character to split at and one to join the crumbs with.
-    # It will generate a list of links that act as pointers to previous pages on
-    # this path.
-    #
-    # Example:
-    #   breadcrumbs('/path/to/somewhere')
-    #
-    #   # results in this, newlines added for readability:
-    #
-    #   <a href="/path">path</a>/
-    #   <a href="/path/to">to</a>/
-    #   <a href="/path/to/somewhere">somewhere</a>
-    #
-    # Optionally a href prefix can be specified which generate link
-    # names a above, but with the prefix prepended to the href path.
-    #
-    # Example:
-    #   breadcrumbs('/path/to/somewhere', '/', '/', '/mycontroller/action')
-    #
-    #   # results in this, newlines added for readability:
-    #
-    #   <a href="/mycontroller/action/path">path</a>/
-    #   <a href="/mycontroller/action/path/to">to</a>/
-    #   <a href="/mycontroller/action/path/to/somewhere">somewhere</a>
+      def route_location(klass)
+        Ramaze.to(klass) || Ramaze.to(klass.class)
+      end
 
-    def breadcrumbs(path, split = '/', join = '/', href_prefix = '')
-      atoms = path.split(split).reject{|a| a.empty?}
-      crumbs = atoms.inject([]){|s,v| s << [s.last,v]}
-      bread = crumbs.map do |a|
-        href_path = href_prefix + a*'/'
-        A(a[-1], :href=>(href_path))
+      # Give it a path with character to split at and one to join the crumbs with.
+      # It will generate a list of links that act as pointers to previous pages on
+      # this path.
+      #
+      # Example:
+      #   breadcrumbs('/path/to/somewhere')
+      #
+      #   # results in this, newlines added for readability:
+      #
+      #   <a href="/path">path</a>/
+      #   <a href="/path/to">to</a>/
+      #   <a href="/path/to/somewhere">somewhere</a>
+      #
+      # Optionally a href prefix can be specified which generate link
+      # names a above, but with the prefix prepended to the href path.
+      #
+      # Example:
+      #   breadcrumbs('/path/to/somewhere', '/', '/', '/mycontroller/action')
+      #
+      #   # results in this, newlines added for readability:
+      #
+      #   <a href="/mycontroller/action/path">path</a>/
+      #   <a href="/mycontroller/action/path/to">to</a>/
+      #   <a href="/mycontroller/action/path/to/somewhere">somewhere</a>
+      #
+      # @return [String]
+      def breadcrumbs(path, split = '/', join = '/', href_prefix = '')
+        atoms = path.split(split).reject{|a| a.empty?}
+        crumbs = atoms.inject([]){|s,v| s << [s.last,v]}
+        bread = crumbs.map do |a|
+          href_path = href_prefix + a*'/'
+          a(a[-1], href_path)
+        end
+        bread.join(join)
       end
-      bread.join(join)
     end
   end
 end