ramaze 0.3.9.1 → 2023.01.06

data/lib/ramaze/gestalt.rb

@@ -1,101 +1,115 @@
-#          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
-
-=begin rdoc
-Example:
-
-  require 'ramaze'
-  require 'ramaze/gestalt'
-
-  def random_color
-    ('#' << '%02x' * 3) % (1..3).map{ rand(255) }
-  end
-
-  puts Ramaze::Gestalt.build{
-    html do
-      head do
-        title{"Hello World"}
-      end
-      body do
-        h1{"Hello, World!"}
-        div(:style => 'width:100%') do
-          10.times do
-            div(:style => "width:#{rand(100)}%;height:#{rand(100)}%;background:#{random_color}"){ '&nbsp;' }
-          end
-        end
-      end
-    end
-  }
-=end
+#          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
-
+  ##
   # Gestalt is the custom HTML/XML builder for Ramaze, based on a very simple
   # DSL it will build your markup.
-
+  #
+  # @example
+  #   html =
+  #     Gestalt.build do
+  #       html do
+  #         head do
+  #           title "Hello, World!"
+  #         end
+  #         body do
+  #           h1 "Hello, World!"
+  #         end
+  #       end
+  #     end
+  #
   class Gestalt
     attr_accessor :out
 
+    ##
     # The default way to start building your markup.
     # Takes a block and returns the markup.
     #
-    # Example:
-    #   html =
-    #     Gestalt.build do
-    #       html do
-    #         head do
-    #           title "Hello, World!"
-    #         end
-    #         body do
-    #           h1 "Hello, World!"
-    #         end
-    #       end
-    #     end
+    # @param [Proc] block
     #
-
-    def self.build &block
+    def self.build(&block)
       self.new(&block).to_s
     end
 
+    ##
     # Gestalt.new is like ::build but will return itself.
     # you can either access #out or .to_s it, which will
     # return the actual markup.
     #
     # Useful for distributed building of one page.
-
-    def initialize &block
-      @out = ''
+    #
+    # @param [Proc] block
+    #
+    def initialize(&block)
+      @out = []
       instance_eval(&block) if block_given?
     end
 
-    # catching all the tags. passing it to _gestalt_build_tag
-
-    def method_missing meth, *args, &block
+    ##
+    # Catching all the tags. passing it to _gestalt_build_tag
+    #
+    # @param [String] meth The method that was called.
+    # @param [Hash] args Additional arguments passed to the called method.
+    # @param [Proc] block
+    #
+    def method_missing(meth, *args, &block)
       _gestalt_call_tag meth, args, &block
     end
 
-    # workaround for Kernel#p to make <p /> tags possible.
-
-    def p *args, &block
+    ##
+    # Workaround for Kernel#p to make <p /> tags possible.
+    #
+    # @param [Hash] args Extra arguments that should be processed before
+    #  creating the paragraph tag.
+    # @param [Proc] block
+    #
+    def p(*args, &block)
       _gestalt_call_tag :p, args, &block
     end
 
-    def _gestalt_call_tag name, args, &block
+    ##
+    # Workaround for Kernel#select to make <select></select> work.
+    #
+    # @param [Array] args Extra arguments that should be processed before
+    #  creating the select tag.
+    # @param [Proc] block
+    #
+    def select(*args, &block)
+      _gestalt_call_tag(:select, args, &block)
+    end
+
+    ##
+    # Calls a particular tag based on the specified parameters.
+    #
+    # @param [String] name
+    # @param [Hash] args
+    # @param [Proc] block
+    #
+    def _gestalt_call_tag(name, args, &block)
       if args.size == 1 and args[0].kind_of? Hash
         # args are just attributes, children in block...
         _gestalt_build_tag name, args[0], &block
+      elsif args[1].kind_of? Hash
+        # args are text and attributes ie. a('mylink', :href => '/mylink')
+        _gestalt_build_tag(name, args[1], args[0], &block)
       else
         # no attributes, but text
         _gestalt_build_tag name, {}, args, &block
       end
     end
 
-    # build a tag for `name`, using `args` and an optional block that
-    # will be yielded
-
-    def _gestalt_build_tag name, attr={}, text=[]
+    ##
+    # Build a tag for `name`, using `args` and an optional block that
+    # will be yielded.
+    #
+    # @param [String] name
+    # @param [Hash] attr
+    # @param [Hash] text
+    #
+    def _gestalt_build_tag(name, attr = {}, text = [])
       @out << "<#{name}"
-      @out << attr.inject(''){ |s,v| s << %{ #{v[0]}="#{_gestalt_escape_entities(v[1])}"} }
+      @out << attr.map{|(k,v)| %[ #{k}="#{_gestalt_escape_entities(v)}"] }.join
       if text != [] or block_given?
         @out << ">"
         @out << _gestalt_escape_entities([text].join)
@@ -109,6 +123,11 @@ module Ramaze
       end
     end
 
+    ##
+    # Replace common HTML characters such as " and < with their entities.
+    #
+    # @param [String] s The HTML string that needs to be escaped.
+    #
     def _gestalt_escape_entities(s)
       s.to_s.gsub(/&/, '&amp;').
         gsub(/"/, '&quot;').
@@ -117,13 +136,26 @@ module Ramaze
         gsub(/>/, '&gt;')
     end
 
+    ##
+    # Shortcut for building tags,
+    #
+    # @param [String] name
+    # @param [Array] args
+    # @param [Proc] block
+    #
     def tag(name, *args, &block)
       _gestalt_call_tag(name.to_s, args, &block)
     end
 
+    ##
+    # Convert the final output of Gestalt to a string.
+    # This method has the following alias: "to_str".
+    #
+    # @return [String]
+    #
     def to_s
-      @out.to_s
+      @out.join
     end
     alias to_str to_s
-  end
-end
+  end # Gestalt
+end # Ramaze

data/lib/ramaze/helper/auth.rb

@@ -1,125 +1,125 @@
-#          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
-
-require 'digest/sha1'
+#          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
+  module Helper
+    ##
+    # The Auth helper can be used for authentication without using a model.
+    # This can be useful when working with very basic applications that don't
+    # require database access.
+    #
+    # If you're looking for a way to do authentication using a model you should
+    # take a look at Helper::User instead.
+    #
+    module Auth
+      Helper::LOOKUP << self
+      include Ramaze::Traited
 
-  # A simple way to do authentication. Please have a look at the docs for the
-  # check_auth method for detailed information
-
-  module Helper::Auth
-    Helper::LOOKUP << self
-
-    # add Helper::Aspect and Helper::Stack on inclusion of Helper::Auth
-
-    def self.included(klass)
-      klass.send(:helper, :aspect, :stack)
-    end
-
-    # The default Element to use (if any)
-
-    AUTH_ELEMENT = 'Page'
-
-    # action for login, takes a password
-    # ( ?password=passwort or /login/passwort or via a form )
-    # if no password given, shows a simple form to input it.
+      trait :auth_table     => {}
+      trait :auth_hashify   => lambda { |pass| Digest::SHA1.hexdigest(pass) }
+      trait :auth_post_only => false
 
-    def login
-      username, password = request[:username, :password]
-      if check_auth(username, password)
-        session[:logged_in] = true
-        session[:username] = username
-        inside_stack? ? answer : redirect_referrer
-      else
-        if AUTH_ELEMENT and AUTH_ELEMENT.to_s.split.any?
-          open_element = "<#{AUTH_ELEMENT}>"
-          close_element = "</#{AUTH_ELEMENT}>"
-        end
-        %{
-          #{open_element}
-            <form method="POST" action="#{Rs(:login)}">
-              <ul style="list-style:none;">
-                <li>Username: <input type="text" name="username" /></li>
-                <li>Password: <input type="password" name="password" /></li>
-                <li><input type="submit" /></li>
-              </ul>
-            </form>
-          #{close_element}
-        }
+      def self.included(into)
+        into.helper(:stack)
       end
-    end
 
-    # clear the session and redirect to the index action of the mapping of the
-    # current controller.
+      ##
+      # Log a user in based on the :username and :password key in the request
+      # hash.
+      #
+      # @return [String] The login template in case the user's login data was
+      #  incorrect.
+      #
+      def login
+        if trait[:auth_post_only] and !request.post?
+          return auth_template
+        end
 
-    def logout
-      session.clear
-      redirect_referer
-    end
+        @username, password = request[:username, :password]
 
-    private
+        answer(request.referer) if auth_login(@username, password)
 
-    # call( R(self, :login) ) if not logged in
+        return auth_template
+      end
 
-    def login_required
-      call(Rs(:login)) unless logged_in?
-    end
+      ##
+      # Log the user out and redirect him back to the previous page.
+      #
+      def logout
+        auth_logout
+        redirect_referrer
+      end
 
-    # checks if the user is already logged in.
-    #   session[:logged_in] is not nil/false
+      private
 
-    def logged_in?
-      !!session[:logged_in]
-    end
+      ##
+      # Validate the user's session and redirect him/her to the login page in
+      # case the user isn't logged in.
+      #
+      def login_required
+        call(r(:login)) unless logged_in?
+      end
 
-    # check the authentication (username and password) against the auth_table.
-    #
-    # auth_table is a trait, it may be the name of a method, a Proc or a simple
-    # Hash.
-    # If it is neither of the above it has at least to respond to #[]
-    # which will pass it the username as key and it should answer with the
-    # password as a Digest::SHA1.hexdigest.
-    #
-    # The method and Proc are both called on demand.
-    #
-    # If you want to change the way the password is hashed, change
-    #   trait[:auth_hashify]
-    #
-    # The default looks like:
-    #   lambda{ |pass| Digest::SHA1.hexdigest(pass.to_s) }
-    #
-    # As with the auth_table, this has to be an object that responds to #[]
-    #
-    # If you want all your controllers to use the same mechanism set the trait
-    # on one of the ancestors, the traits are looked up by #ancestral_trait
-    #
-    # Examples:
-    #
-    #   # The method to be called.
-    #   trait :auth_table => :auth_table
-    #   trait :auth_table => 'auth_table'
-    #
-    #   # Lambda that will be called upon demand
-    #   trait :auth_table => lambda{ {'manveru' => Digest::SHA1.hexdigest 'password'} }
-    #
-    #   # Hash holding the data.
-    #   trait :auth_table => {'manveru' => Digest::SHA1.hexdigest('password')}
+      ##
+      # Validate the user's session and return a boolean that indicates if the
+      # user is logged in or not.
+      #
+      # @return [true false] Whether user is logged in right now
+      #
+      def logged_in?
+        !!session[:logged_in]
+      end
 
-    def check_auth user, pass
-      return false if (not user or user.empty?) and (not pass or pass.empty?)
-      auth_table = ancestral_trait[:auth_table] ||= {}
+      ##
+      # Try to log the user in based on the username and password.
+      # This method is called by the login() method and shouldn't be called
+      # directly.
+      #
+      # @param [String] user The users's username.
+      # @param [String] pass The user's password.
+      #
+      def auth_login(user, pass)
+        return unless user and pass
+        return if user.empty? or pass.empty?
+
+        return unless table   = ancestral_trait[:auth_table]
+        return unless hashify = ancestral_trait[:auth_hashify]
+
+        if table.respond_to?(:to_sym) or table.respond_to?(:to_str)
+          table = send(table)
+        elsif table.respond_to?(:call)
+          table = table.call
+        end
 
-      auth_table = method(auth_table) if auth_table.is_a?(Symbol)
-      auth_table = method(auth_table) if auth_table.respond_to?(:to_str)
-      auth_table = auth_table.call    if auth_table.respond_to?(:call)
+        return unless table[user] == hashify.call(pass)
 
-      default_hashify = lambda{ |pass| Digest::SHA1.hexdigest(pass.to_s) }
+        session[:logged_in] = true
+        session[:username]  = user
+      end
 
-      hashify  = (ancestral_trait[:auth_hashify] ||= default_hashify)
-      password = hashify[pass.to_s]
+      ##
+      # Remove the session items that specified that the user was logged in.
+      #
+      def auth_logout
+        session.delete(:logged_in)
+        session.delete(:username)
+      end
 
-      auth_table[user.to_s] == password
-    end
-  end
-end
+      ##
+      # Method that returns a small form that can be used for logging in.
+      #
+      # @return [String] The login form.
+      def auth_template
+        <<-TEMPLATE.strip!
+<form method="post" action="#{r(:login)}">
+  <ul style="list-style:none;">
+    <li>Username: <input type="text" name="username" value="#@username"/></li>
+    <li>Password: <input type="password" name="password" /></li>
+    <li><input type="submit" /></li>
+  </ul>
+</form>
+        TEMPLATE
+      end
+    end # Auth
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/bench.rb

@@ -0,0 +1,51 @@
+require 'benchmark'
+
+module Ramaze
+  module Helper
+    ##
+    # The Benchmark helper is a simple helper that can be used to benchmark
+    # certain blocks of code by wrapping them in a block. This can be useful if
+    # you want to see how long a certain query takes or how long it takes to
+    # create a new user.
+    #
+    module Bench
+      ##
+      # Will first run an empty loop to determine the overhead it imposes, then
+      # goes on to yield your block +iterations+ times.
+      #
+      # The last yielded return value will be returned upon completion of the
+      # benchmark and the result of the benchmark itself will be sent to
+      # Log.info
+      #
+      # Example:
+      #
+      #     class MainController < Ramaze::Controller
+      #       def index
+      #         @users = bench{ User.all }
+      #         @tags = bench{ Article.tags }
+      #       end
+      #     end
+      #
+      # This will show something like following in your log:
+      #
+      #     [..] INFO   Bench ./start.rb:3:in `index': 0.121163845062256
+      #     [..] INFO   Bench ./start.rb:4:in `index': 2.234987235098341
+      #
+      # So now we know that the Article.tags call takes the most time and
+      # should be improved.
+      #
+      # @param  [Fixnum] iterations The amount of iterations to run.
+      # @return [Mixed]
+      #
+      def bench(iterations = 1)
+        result = nil
+        from   = caller[0]
+        delta  = Benchmark.realtime{ iterations.times{ nil }}
+        taken  = Benchmark.realtime{ iterations.times{ result = yield }}
+
+        Log.info "Bench #{from}: #{taken - delta}"
+        return result
+      end
+    end # Bench
+  end # Helper
+end # Ramaze