ramaze 2011.12.28 → 2012.03.07

data/lib/ramaze/helper/erector.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'erector'
 

data/lib/ramaze/helper/flash.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
 

data/lib/ramaze/helper/formatting.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Helper

data/lib/ramaze/helper/identity.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'openid'
 require 'openid/store/filesystem'

data/lib/ramaze/helper/link.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'innate/helper/link'
 

data/lib/ramaze/helper/markaby.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Helper

data/lib/ramaze/helper/stack.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Helper

data/lib/ramaze/helper/tagz.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'tagz'
 

data/lib/ramaze/helper/thread.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Helper

data/lib/ramaze/helper/user.rb

@@ -1,6 +1,6 @@
 module Ramaze
   module Helper
-
+    ##
     # This helper provides a convenience wrapper for handling authentication
     # and persistence of users.
     #
@@ -99,12 +99,11 @@ module Ramaze
       # Use this method in your application, but do not use it in conditionals
       # as it will never be nil or false.
       #
+      # @api    external
+      # @author manveru
       # @return [Ramaze::Helper::User::Wrapper] wrapped return value from
       #  model or callback
       #
-      # @api external
-      # @author manveru
-      #
       def user
         env = request.env
         found = env[RAMAZE_HELPER_USER]
@@ -116,48 +115,74 @@ module Ramaze
       end
 
       ##
-      # shortcut for user._login but default argument are request.params
+      # This method is used to authenticate a user against the supplied
+      # credentials (which default to ``request.params``).
+      #
+      # This method is a proxy to  user._login which returns the value as
+      # returned by ``Ramaze::Helper::User::Wrapper#_login``.
+      #
+      # The supplied argument should be a hash with the user's credentials.  The
+      # credentials hash may use any naming for the hash keys as long as they
+      # are consistent with the model which authenticates them (through the
+      # ``authenticate()`` method) such as:
+      #
+      #     {"username" =>"name", "password" => "the_passwd"}
       #
-      # @param [Hash] creds the credentials that will be passed to callback or
-      #  model
-      # @return [nil Hash] the given creds are returned on successful login
+      # On success it returns a hash of the credentials embedded within a hash
+      # whose only key is ':credentials' such as the following:
+      #
+      #     {:credentials=>{"username"=>"myuser", "password"=>"mypassword"}}
+      #
+      # On failure to authenticate this method returns nil.
+      #
+      # @example
+      #  auth = {"username" => "my_username", "password" => "mypass"}
+      #  creds = user_login(auth)
+      #  if creds
+      #    respond 'You have been logged in as #{creds[:credentials]["username"]}', 200
+      #  else
+      #    respond 'You could not be logged in', 401
+      #  end
       #
-      # @api external
-      # @see Ramaze::Helper::User::Wrapper#_login
       # @author manveru
+      # @api    external
+      # @see    Ramaze::Helper::User::Wrapper#_login
+      # @param  [Hash] creds the credentials that will be passed to the callback or model.
+      # @return [nil Hash[Hash]]
       #
       def user_login(creds = request.params)
         user._login(creds)
       end
 
       ##
-      # shortcut for user._logout
+      # Shortcut for user._logout
       #
-      # @return [nil]
-      #
-      # @api external
-      # @see Ramaze::Helper::User::Wrapper#_logout
       # @author manveru
+      # @api    external
+      # @see    Ramaze::Helper::User::Wrapper#_logout
+      # @return [NilClass]
       #
       def user_logout
         user._logout
       end
 
       ##
-      # @return [true false] whether the user is logged in already.
+      # Checks if the user is logged in and returns true if this is the case and
+      # false otherwise.
       #
-      # @api external
-      # @see Ramaze::Helper::User::Wrapper#_logged_in?
       # @author manveru
+      # @api    external
+      # @see    Ramaze::Helper::User::Wrapper#_logged_in?
+      # @return [TrueClass|FalseClass] whether the user is logged in already.
       #
       def logged_in?
         user._logged_in?
       end
 
       ##
-      # Wrapper for the ever-present "user" in your application.
-      # It wraps around an arbitrary instance and worries about authentication
-      # and storing information about the user in the session.
+      # Wrapper for the ever-present "user" in your application. It wraps
+      # around an arbitrary instance and worries about authentication and
+      # storing information about the user in the session.
       #
       # In order to not interfere with the wrapped instance/model we start our
       # methods with an underscore.
@@ -174,12 +199,13 @@ module Ramaze
         end
 
         ##
-        # @param [Hash] creds this hash will be stored in the session on
+        # @author manveru
+        # @see    Ramaze::Helper::User#user_login
+        # @param  [Hash] creds this hash will be stored in the session on
         #  successful login
         # @return [Ramaze::Helper::User::Wrapper] wrapped return value from
         #  model or callback
-        # @see Ramaze::Helper::User#user_login
-        # @author manveru
+        #
         def _login(creds = nil)
           if creds
             if @_user = _would_login?(creds)
@@ -191,11 +217,13 @@ module Ramaze
           end
         end
 
+        ##
         # The callback should return an instance of the user, otherwise it
         # should answer with nil.
         #
         # This will not actually login, just check whether the credentials
         # would result in a user.
+        #
         def _would_login?(creds)
           return unless creds
 
@@ -204,23 +232,31 @@ module Ramaze
           elsif _model.respond_to?(:authenticate)
             _model.authenticate(creds)
           else
-            Log.warn("Helper::User has no callback and there is no %p::authenticate" % _model)
+            Log.warn(
+              "Helper::User has no callback and there is no %p::authenticate" \
+                % _model
+            )
+
             nil
           end
         end
 
-        # @api internal
-        # @see Ramaze::Helper::User#user_logout
+        ##
         # @author manveru
+        # @api    internal
+        # @see    Ramaze::Helper::User#user_logout
+        #
         def _logout
           (_persistence || {}).clear
           Current.request.env['ramaze.helper.user'] = nil
         end
 
-        # @return [true false] whether the current user is logged in.
-        # @api internal
-        # @see Ramaze::Helper::User#logged_in?
+        ##
         # @author manveru
+        # @api    internal
+        # @see    Ramaze::Helper::User#logged_in?
+        # @return [true false] whether the current user is logged in.
+        #
         def _logged_in?
           !!_user
         end
@@ -233,8 +269,10 @@ module Ramaze
           Current.session[:USER]
         end
 
+        ##
         # Refer everything not known
         # THINK: This might be quite confusing... should we raise instead?
+        #
         def method_missing(meth, *args, &block)
           return unless _user
           _user.send(meth, *args, &block)

data/lib/ramaze/log.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 require 'ramaze/log/logging'
 require 'ramaze/log/informer'
 

data/lib/ramaze/log/analogger.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'swiftcore/Analogger/Client'
 

data/lib/ramaze/log/growl.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'ruby-growl'
 

data/lib/ramaze/log/hub.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Logger

data/lib/ramaze/log/informer.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Logger

data/lib/ramaze/log/knotify.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Logger

data/lib/ramaze/log/logger.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'logger'
 

data/lib/ramaze/log/logging.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   ##

data/lib/ramaze/log/syslog.rb

@@ -1,6 +1,6 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
 #          Copyright (c) 2008 rob@rebeltechnologies.nl
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'syslog'
 

data/lib/ramaze/log/xosd.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 Ramaze::Log.log( :warn, "Both xosd gems are currently known to be broken" )
 require 'xosd'

data/lib/ramaze/plugin.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   def self.plugin(name, options = {})

data/lib/ramaze/reloader.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   ##

data/lib/ramaze/request.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 module Ramaze
   ##
   # The purpose of this class is to act as a simple wrapper for Rack::Request

data/lib/ramaze/response.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 module Ramaze
   ##
   # Ramaze::Response is a small wrapper around Rack::Response that makes it

data/lib/ramaze/snippets.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'ramaze/snippets/array/put_within'
 require 'ramaze/snippets/binding/locals'

data/lib/ramaze/snippets/array/put_within.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module CoreExtensions

data/lib/ramaze/snippets/kernel/pretty_inspect.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'pp'
 

data/lib/ramaze/snippets/numeric/filesize_format.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module CoreExtensions

data/lib/ramaze/snippets/object/__dir__.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module CoreExtensions

data/lib/ramaze/snippets/object/instance_variable_defined.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module CoreExtensions

data/lib/ramaze/snippets/ordered_set.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require(File.join(File.dirname(__FILE__), 'blankslate'))
 

data/lib/ramaze/snippets/ramaze/acquire.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   # Require all .rb and .so files on the given globs, utilizes Dir::[].