ramaze 2010.06.18 → 2011.01

data/lib/proto/start.rb

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 # Use this file directly like `ruby start.rb` if you don't want to use the
 # `ramaze start` command.
 # All application related things should go into `app.rb`, this file is simply

data/lib/proto/view/index.xhtml

@@ -9,7 +9,7 @@
       <code>view/index.xhtml</code>, this page.
     </li>
     <li>
-      <code>view/page.xhtml</code>, the layout for this page.
+      <code>layout/default.xhtml</code>, the layout for this page.
     </li>
     <li>
       <code>controller/main.rb</code>, where you can change the header of this
@@ -27,8 +27,8 @@
 </p>
 
 <p>
-You can also read the
-<a href="http://ramaze.rubyforge.org/rdoc/files/doc/README.html">rdocs</a>
+You can also read the 
+<a href="http://doc.rubyists.com/ramaze%2binnate/">rdocs</a>
 or browse around the
 <a href="http://source.ramaze.net">Ramaze source code</a>.
 </p>

data/lib/ramaze.rb

@@ -23,7 +23,6 @@ module Ramaze
   class << self; attr_accessor :options; end
 
   # vendored, will go into rack-contrib
-  require 'vendor/etag'
   require 'vendor/route_exceptions'
 
   # Ramaze itself
@@ -67,7 +66,7 @@ module Ramaze
     m.use Rack::ShowStatus
     m.use Rack::RouteExceptions
     m.use Rack::ConditionalGet
-    m.use Rack::ETag
+    m.use Rack::ETag, 'public'
     m.use Rack::Head
     m.use Ramaze::Reloader
     m.run Ramaze::AppMap

data/lib/ramaze/cache.rb

@@ -6,6 +6,7 @@ require 'innate/cache'
 module Ramaze
   Cache = Innate::Cache
 
+  # TODO: Describe what this class does and how it can be used.
   class Cache
     autoload :LRU,           'ramaze/cache/lru'
     autoload :LocalMemCache, 'ramaze/cache/localmemcache'

data/lib/ramaze/cache/sequel.rb

@@ -1,79 +1,173 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
 # All files in this distribution are subject to the terms of the Ruby license.
-
 require 'sequel'
 
 module Ramaze
   class Cache
-
-    # Cache based on a Sequel model using relational databases.
+    ##
+    # Cache system that uses Sequel to store data in a database table named
+    # "ramaze_cache". Values stored in the database will be automatically serialized/
+    # unserialized using Marshal. Originally this cache system didn't work with Sequel 3
+    # but this has been fixed by Yorick Peterse.
+    #
+    # @example
+    #  # Define that we want to use the Sequel cache for sessions
+    #  Ramaze.options.cache.session  = Ramaze::Cache::Sequel
+    #
+    #  # Store some data in the session
+    #  session["framework"] = "Ramaze"
+    #
+    #  # Do something with the data
+    #  session["framework"] += ", simply (r)amazing"
+    #
+    # @author Unknown, Yorick Peterse
     #
-    # Please note that this cache might not work perfectly with Sequel 3.0.0,
-    # as the #[] and #[]= methods do not respect serialization.
-    # I'll lobby for a change in that direction.
     class Sequel
+      # I can haz API?
       include Cache::API
 
+      ##
+      # Model used for managing the data in the database.
+      # All data stored in the "value" column will be serialized/unserialized by Sequel itself.
+      # The structure of the table that belongs to this model looks like the following:
+      #
+      #   _________________________________________________________________
+      #  |              |              |                |                  |
+      #  | (integer) ID | (string) key | (string) value | (date) expires   |
+      #  |______________|______________|________________|__________________|
+      #
+      #
+      # Note that "key" is a unique field so double check to see if your application might try
+      # to insert an already existing key as this will cause Sequel errors.
+      #
+      # @author Unknown, Yorick Peterse
+      #
       class Table < ::Sequel::Model(:ramaze_cache)
         plugin :schema
-        plugin :serialization
-
-        serialize_attributes :marshal, :value
+        plugin :serialization, :marshal, :value
 
+        # Define the schema for this model
         set_schema do
           primary_key :id
-          index :key, :unique => true
-
-          String :key
-          String :value
+          
+          String :key,   :null => false, :unique => true
+          String :value, :text => true
+          
           Time :expires
         end
-
-        def [](column)
-          if column == :value
-            deserialized_values[column] = deserialize_value(column, @values[column])
-          else
-            super
-          end
-        end
       end
 
-      # Setup the table, not suitable for multiple apps yet.
+      ##
+      # Create the cache table if it doesn't exist yet.
+      # This cache does not yet support multiple applications unless you
+      # give "app" an unique name.
+      #
+      # @author Unknown, Yorick Peterse
+      # @example
+      #  cache = Ramaze::Cache::Sequel.new
+      #  cache.cache_setup 'my_server', 'chuck_norris', 'blog', 'articles'
+      #
+      # @param [String] host The hostname of the machine on which the application is running.
+      # @param [String] user The user under which the application is running.
+      # @param [String] app The name of the "application". For example, when using this cache
+      # for session "app" will be set to "session".
+      # @param [String] name The name for the row. When using sessions this will be set to the
+      # user's session ID.
+      #
       def cache_setup(host, user, app, name)
         @namespace = [host, user, app, name].compact.join(':')
         Table.create_table?
         @store = Table
       end
 
-      # Wipe out _all_ data in the table, use with care.
+      ##
+      # Wipe out _all_ data in the table, use with care!
+      #
+      # @author Unknown, Yorick Peterse
+      # @example
+      #  cache = Ramaze::Cache::Sequel.new
+      #  cache.cache_clear
+      #
       def cache_clear
-        Table.delete
+        @store.delete
       end
 
-      # Delete records for given +keys+
+      ##
+      # Deletes a specific set of records based on the provided keys.
+      #
+      # @author Unknown, Yorick Peterse
+      # @example
+      #  # Delete everything where "key" is set to "chunky_bacon"
+      #  cache = Ramaze::Cache::Sequel.new
+      #  cache.cache_delete 'chunky_bacon'
+      #
+      # @param [String] *keys A set of keys that define which row has to be deleted.
+      #
       def cache_delete(*keys)
-        super do |key|
-          record = @store[:key => namespaced(key)]
-          record.delete if record
+        if keys
+          keys.each do |key|
+            record = @store[:key => namespaced(key)]
+            record.delete if record  
+          end
         end
       end
 
+      ##
+      # Retrieve the cache that belongs to the specified key.
+      #
+      # @author Unknown, Yorick Peterse
+      # @example
+      #  cache = Ramaze::Cache::Sequel.new
+      #  data  = cache.cache_fetch 'chunky_bacon'
+      #
+      # @param  [String] key The key that defines what record to retrieve.
+      # @param  [String] default The value to return in case no data could be found.
+      # @return [String] The unserialized data from the "value" column.
+      # @return [String]
+      #
       def cache_fetch(key, default = nil)
-        super{|key| @store[:key => namespaced(key)] }
+        # Retrieve the data and return it
+        record = @store[:key => namespaced(key)]
+        record.value rescue default
       end
 
+      ##
+      # Store the specified key/value variables in the cache.
+      #
+      # @author Unknown, Yorick Peterse
+      # @example
+      #  cache = Ramaze::Cache::Sequel.new
+      #  cache.cache_store 'name', 'Yorick Peterse', :ttl => 3600
+      #
+      # @param [String] key The name of the cache to store.
+      # @param [String] value The actual data to cache.
+      # @param [Hash] options Additional options such as the TTL.
+      # @return [String]
+      #
       def cache_store(key, value, options = {})
-        key = namespaced(key)
-        ttl = options[:ttl]
-        expires = Time.now + ttl if ttl
+        key     = namespaced(key)
+        ttl     = options[:ttl] rescue nil
+        expires = Time.now + ttl if !ttl.nil?
+        record  = @store[:key => key]
 
-        record = @store[:key => key].update(:value => value, :expires => expires)
-        record.value
-      rescue
-        record = @store.create(:key => key, :value => value, :expires => expires)
-        record.value
+        # Figure out if the record is new or already exists
+        if !record
+          record = @store.create(:key => key, :value => value, :expires => expires)
+          record.value
+        else
+          record = record.update(:value => value, :expires => expires)
+          record.value
+        end
       end
 
+      ##
+      # Generate the namespace for the cache.
+      # Namespaces have the format of host:user:app:name:key.
+      #
+      # @author Unknown
+      # @param [String] key The name of the cache key.
+      # @return [String]
+      #
       def namespaced(key)
         [@namespace, key].join(':')
       end

data/lib/ramaze/controller.rb

@@ -2,6 +2,7 @@
 # All files in this distribution are subject to the terms of the Ruby license.
 
 module Ramaze
+  # TODO: Describe what this class does other than initailizing the Controller system.
   class Controller
     include Innate::Traited
     include Innate::Node

data/lib/ramaze/gestalt.rb

@@ -1,85 +1,91 @@
 #          Copyright (c) 2009 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'
-
-  page = Ramaze::Gestalt.build{
-    title = 'Hello, World!'
-
-    html do
-      head{ title(title) }
-      body do
-        h1(title)
-        p 'I count to 10'
-        ('1'..'10').each do |count|
-          div(:style => 'width: 25px; height: 25px'){ count }
-        end
-      end
-    end
-  }
-=end
-
 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 [Block] 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.
-
+    #
+    # @param [Block] block
+    #
     def initialize(&block)
       @out = []
       instance_eval(&block) if block_given?
     end
 
-    # catching all the tags. passing it to _gestalt_build_tag
-
+    ##
+    # Catching all the tags. passing it to _gestalt_build_tag
+    #
+    # @param [String] method The method that was called.
+    # @param [Hash] args Additional arguments passed to the called method.
+    # @param [Block] block
+    #
     def method_missing(meth, *args, &block)
       _gestalt_call_tag meth, args, &block
     end
 
-    # workaround for Kernel#p to make <p /> tags possible.
-
+    ##
+    # Workaround for Kernel#p to make <p /> tags possible.
+    #
+    # @param [Hash] args Extra arguments that should be processed before creating the paragraph tag.
+    # @param [Block] block
+    #
     def p(*args, &block)
       _gestalt_call_tag :p, args, &block
     end
-
-    # workaround for Kernel#select to make <select></select> work
+    
+    ##
+    # Workaround for Kernel#select to make <select></select> work.
+    #
+    # @param [Hash] args Extra arguments that should be processed before creating the select tag.
+    # @param [Block] block
+    #
     def select(*args, &block)
       _gestalt_call_tag(:select, args, &block)
     end
 
+    ##
+    # TODO: Describe this method, I'm not exactly sure what it does - Yorick
+    #
+    # @param [String] name
+    # @param [Hash] args
+    # @param [Block] 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...
@@ -93,9 +99,16 @@ module Ramaze
       end
     end
 
-    # build a tag for `name`, using `args` and an optional block that
-    # will be yielded
-
+    ##
+    # Build a tag for `name`, using `args` and an optional block that
+    # will be yielded.
+    #
+    # TODO: Describe this method since I'm not exactly sure what it does - Yorick
+    #
+    # @param [String] name
+    # @param [Hash] attr
+    # @param [Hash] text
+    #
     def _gestalt_build_tag(name, attr = {}, text = [])
       @out << "<#{name}"
       @out << attr.map{|(k,v)| %[ #{k}="#{_gestalt_escape_entities(v)}"] }.join
@@ -112,6 +125,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;').
@@ -120,10 +138,21 @@ module Ramaze
         gsub(/>/, '&gt;')
     end
 
+    ##
+    # TODO: Describe this method since I'm not exactly sure what it does - Yorick
+    #
+    # @param [String] name
+    # @param [Hash] args
+    # @param [Block] 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".
+    #
     def to_s
       @out.join
     end