merb 0.4.1 → 0.4.2

data/README

@@ -1,24 +1,16 @@
 = Merb
 
-==== FrameWork Development Dependencies
+Like Ruby on Rails, Merb (Mongrel + ERB) is an MVC framework. Unlike Rails, Merb is ORM-agnostic, JavaScript library agnostic, and template language agnostic, preferring plugins that add in support for a particular feature rather than trying to produce a monolithic library with everything in the core. In fact, this is a guiding principle of the project, which has led to third-party support for the ActiveRecord, DataMapper, and Sequel ORMs.
 
-Install these gems first:
+In addition, it means that the core code in Merb is kept simple and well organised. This has multiple benefits. It means it's faster for one thing. It's also easier to understand, maintain and extend.
 
-* mongrel
-* json
-* json_pure
-* erubis
-* mime-types
-* rspec
-* hpricot
-* mocha
-* rubigen
-* haml
-* markaby
-* mailfactory
-* Ruby2Ruby
+=== Get Merb
+
+The simplest way to get Merb is to install the gem:
 
-Then you can build the merb gem from svn trunk like so:
+  $ sudo gem install merb --include-dependencies
+  
+If you want to contribute (or just use the latest code), you can build the gem from the svn trunk:
 
   $ sudo gem install mongrel json json_pure erubis mime-types rspec hpricot mocha rubigen haml markaby mailfactory Ruby2Ruby -y
   $ svn co http://svn.devjavu.com/merb/trunk merb
@@ -26,8 +18,40 @@ Then you can build the merb gem from svn trunk like so:
   $ rake install
 
 To generate a new merb app after the gem is installed:
+  
+  $ merb myapp
 
-  $ merb  myapp
+==== Dependencies
+
+Currently, Merb itself depends on the following gems:
+
+* mongrel
+* json_pure
+* erubis
+* mime-types
+* rspec
+* rubigen 
+* ruby2ruby 
+* rake 
+ 
+** If you are on windows see this blog post oj how to get up and running:
+http://www.ghostonthird.com/2007/11/17/merb-on-windows-it-works/
+ 
+You must also have either the json or json_pure gem installed. Note that the json gem 
+provides a faster library but will not work with jRuby. 
+ 
+Optionally, merb can take advantage of the following gems: 
+ 
+* mailfactory (if you wish to use merb's mailers) 
+* haml (if you wish to use HAML templates, i.e. .haml files) 
+* markaby (if you wish to use Markaby template, i.e. .mab files) 
+* builder (if you wish to use Builder templates, i.e. .rxml, .rerb or .builder files) 
+* memcache-client (for use with Danga Interactive's memcached) 
+* swiftiply 
+* eventmachine 
+* rcov
+
+You will also probably need to install your ORM of choice as well as any gem plugins you want to use (see below).
 
 === The +merb+ server
 
@@ -53,46 +77,49 @@ use the -i flag
 	$ merb -i
 	
 To see all the available command line flags use:
- 
-  $ merb -h	
+
+	$ merb -h
+		
+	
+== Using Merb
+
+Merb uses the Model-View-Controller (MVC) pattern.  Incoming requests are matched in the Router and
+directed to an appropriate controller action.
+
+=== Model
+
+Merb does not come with its own model layer.  While you are free to use whatever data system you like,
+the merb core team does maintain plugins for the following Object Relational Mappers (ORM's):
+
+ActiveRecord:: The same ORM that Rails uses. (<tt>sudo gem install merb_activerecord</tt>)
+DataMapper:: Fairly new ORM. (<tt>sudo gem install merb_datamapper</tt>)
+Sequel:: Fairly new ORM. (<tt>sudo gem install merb_sequel</tt>)
+
+To use your choice ORM, install the appropriate gem and uncomment the appropriate +use_orm+ line in
+MERB_ROOT/config/dependencies.rb
 
 === Controllers
 
-Classes with built in render method and template handling
-with instance vars available in the views automatically. Merb also supports 
-layouts. It will look for a layout named after your controller class first and
-then fall back to application.html.erb if no layout exists named after your
-controller. You can use render <tt>:layout => :none</tt>.
-
-Merb does not automatically render for you in your controller actions, you have
-to call render yourself. I consider this a big advantage over the way rails does 
-it for a few reasons. The main reason is that in rails you can only render once 
-per action, so it knows if you haven’t rendered it shoudl auto render. Merb on 
-the other hand, returns to the browser whatever the return value of your 
-controller’s action method is. This opens up more possibilities imho because
-now you can return any string from your action and that will be sent down 
-the pipe. So Merb’s render method just returns a string and needs to be the 
-last thing you call in your action. You can render multiple times and capture 
-the results into @ivars and then render a master template with many embeded 
-templates. Also if you return a handle on a File or IO object from your action 
-then merb will hand that over to mongrel to be streamed out to the client. And 
-if you return a Proc object from your action, it will be called and the 
-return value sent to the client.
+(MERB_ROOT/app/controllers/*)
 
-That last point has some cool connotations if you think about it. Merb does 
-have a mutex lock around the call to your controller’s action anywhere that
-you can call AR objects. Merb’s lock is way smaller then rails giant lock 
-though and allows for many more concurrent requests to be handled by one 
-process. By returning a Proc object from your action, you allow merb to 
-release the lock and the proc is called in multi threaded way. This allows 
-for all kinds of cool streaming and ‘futures’ where you return the proc and 
-release the mutex. It’s basically like handing over the proc to mongrel and 
-mongrel handles calling it in a thread safe manner.
+Merb controllers inherit from Merb::Controller and contain built in view/template rendering.
+Incoming requests are usually mapped to a specific method in a controller.  For example, using
+the default routes, a request to http://www.yourapp.com/posts/show/1 would call the the #show
+method of your PostsController (and params[:id] would = 1.)
 
+The return value of your action function gets sent back to the client as the view.  In most cases,
+you are going to want to end your functions with a call to +render+.  By default, +render+ will
+render the view template associated with your action (in default merb that would be 
+MERB_ROOT/app/views/<controller>/<action>.html.erb - see the View section for more info.)
 
-==== Before and after filters
+Controllers can be generated by calling MERB_ROOT/script/generate controller ControllerName.
+By default, generated controllers inherit from the Application class (MERB_ROOT/app/controllers/application.rb)
+which itself inherits from Merb:Controller.  Application is a good place to put code pertinent to all controllers.
+An example would be setting a filter to check if a user is logged in or to preload user data for each controller.
 
-Use the before method in your controllers. before accepts either a symbol, string or a Proc/lambda object. If you give it a symbol it will call a method with the same name as the symbol. If you give it a proc that takes one argument it will call the proc with the current controller as that argument. You can use :only and :exclude as options to your filters to exclude or include actionsfrom certain filters. :only and :exclude take :symbols or [:sym, :sam] array of symbols.
+==== +before+ and +after+ filters
+
+Use the +before+ method in your controllers. +before+ accepts either a symbol, string or a Proc/lambda object. If you give it a symbol it will call a method with the same name as the symbol. If you give it a proc that takes one argument it will call the proc with the current controller as that argument. You can use :only and :exclude as options to your filters to exclude or include actions from certain filters. :only and :exclude take :symbols or [:sym, :sam] array of symbols.
 
 	class Foo < Merb::Controller
  
@@ -141,8 +168,62 @@ After filters accept a symbol, string or Proc and call that proc with the contro
 
 	after Proc.new {|c| Tidy.new(c.body) }, :only => :index
 
+
+=== Views
+
+(MERB_ROOT/app/views/*)
+
+A view can be loosely defined as any data sent back to the client (a "view" of your data.)
+By default, Merb controllers send the return value of your controller action as the view.
+The Controller#render method simply renders the specified view and returns it as a string.
+By default, a call to +render+ without any options renders the view template associated
+with that controller action.  Using the default ERB templating system, this means that a
+call to +render+ in Posts#index would render the file MERB_ROOT/app/views/posts/index.html.erb
+
+==== Layouts
+
+(MERB_ROOT/app/views/layout/*)
+
+Layouts are generic templates in which your specific view templates are rendered.  A sample
+layout could look like:
+
+  <html>
+    <head><title>My Application Layout</title></head>
+    <body>
+      <img src="header" />
+      <div id="content">
+        <%= catch_content :layout %>
+      </div>
+    </body>
+  </html>
+
+By default, +render+ will look for a corresponding layout for your controller in the form
+of MERB_ROOT/app/views/layout/<controller>.html.erb .  If no specific layout is present,
++render+ will attempt to use MERB_ROOT/app/view/layout/application.html.erb
+
+<i>See #render for more details/options, as well as how to use different templating systems
+in your app.</i>
+
+You can return several different types of values from your controller actions:
+
+* String: Any string will get sent to the browser as standard text/html
+* File/IO: Any file descriptor will get handed over to mongrel to be streamed to the client.
+* Proc Object: The object will be called and the return value sent to the client.
+
+That last point has some cool connotations if you think about it. Merb does 
+have a mutex lock around the call to your controller’s action anywhere that
+you can call AR objects. Merb’s lock is way smaller then rails giant lock 
+though and allows for many more concurrent requests to be handled by one 
+process. By returning a Proc object from your action, you allow merb to 
+release the lock and the proc is called in multi threaded way. This allows 
+for all kinds of cool streaming and ‘futures’ where you return the proc and 
+release the mutex. It’s basically like handing over the proc to mongrel and 
+mongrel handles calling it in a thread safe manner.
+
 === Helpers
 
+(MERB_ROOT/app/helpers/*)
+
 app/helpers/global_helper.rb will be available to all of your views.
  Helpers named after your controller plus _helper.rb will be included in the views
  for that controller only.
@@ -172,17 +253,18 @@ A file upload will have a hash of params like this:
 
 	  app
 	    controllers
+	    helpers
+	    mailers	    
 	    models
-	    views
 	    parts
-	    mailers
+	    views
 	  config
+	  gems
 	  lib
+	  log
 	  public
-	  schema
 	  Rakefile
-	  scripts
+	  script
+	  spec
 	  test
-	    spec
 	    unit
-	  plugins

data/Rakefile

@@ -14,10 +14,15 @@ require __DIR__+'/tools/annotation_extract'
 include FileUtils
 
 NAME = "merb"
-VERS = "0.4.1"
+require 'lib/merb/version'
 CLEAN.include ['**/.*.sw?', '*.gem', '.config']
 
-setup_clean [ "pkg", "lib/*.bundle", "*.gem", "doc/rdoc", ".config", 'coverage', "cache"]
+
+windows = (PLATFORM =~ /win32|cygwin/)
+
+SUDO = windows ? "" : "sudo"
+
+setup_clean [ "pkg", "lib/*.bundle", "*.gem", "doc/rdoc", ".config", 'coverage', "cache", "log"]
 
 
 desc "Packages up Merb."
@@ -33,14 +38,14 @@ Rake::RDocTask.new do |rdoc|
       rdoc.rdoc_files.add(files)
       rdoc.main = 'README'
       rdoc.title = 'Merb Docs'
-      rdoc.template = `allison --path`.chomp+'.rb'
+      rdoc.template = __DIR__ + '/tools/allison-2.0/lib/allison.rb'
       rdoc.rdoc_dir = 'doc/rdoc'
       rdoc.options << '--line-numbers' << '--inline-source'
 end
 
 spec = Gem::Specification.new do |s|
   s.name = NAME
-  s.version = VERS
+  s.version = Merb::VERSION
   s.platform = Gem::Platform::RUBY
   s.has_rdoc = true
   s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
@@ -57,6 +62,10 @@ spec = Gem::Specification.new do |s|
   s.add_dependency('erubis')
   s.add_dependency('mime-types')
   s.add_dependency('rubigen')
+  s.add_dependency('rake') 
+  s.add_dependency('ruby2ruby') 
+  s.add_dependency('json_pure') 
+  s.requirements << 'install the json gem to get faster json parsing'
   s.required_ruby_version = '>= 1.8.4'
 
   s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{bin,spec,lib,examples,app_generators,merb_generators,merb_default_generators,rspec_generators,test_unit_generators,script}/**/*") 
@@ -72,11 +81,11 @@ end
 
 task :install do
   sh %{rake package}
-  sh %{sudo gem install pkg/#{NAME}-#{VERS} --no-rdoc --no-ri}
+  sh %{#{SUDO} gem install pkg/#{NAME}-#{Merb::VERSION} --no-rdoc --no-ri}
 end
 
 task :uninstall => [:clean] do
-  sh %{sudo gem uninstall #{NAME}}
+  sh %{#{SUDO} gem uninstall #{NAME}}
 end
 
 desc "run webgen"
@@ -87,7 +96,7 @@ end
 desc "rdoc to rubyforge"
 task :doc_rforge do
   sh %{rake doc}
-  sh %{sudo chmod -R 755 doc}
+  sh %{#{SUDO} chmod -R 755 doc} unless windows
   sh %{/usr/bin/scp -r -p doc/rdoc/* ezmobius@rubyforge.org:/var/www/gforge-projects/merb}
 end
 
@@ -138,7 +147,11 @@ task :stats do
 end
 
 task :release => :package do
-  sh %{rubyforge add_release merb merb #{VERS} pkg/#{NAME}-#{VERS}.gem}
+  if ENV['RELEASE']
+    sh %{rubyforge add_release merb merb "#{ENV['RELEASE']}" pkg/#{NAME}-#{Merb::VERSION}.gem}
+  else
+    puts 'Usage: rake release RELEASE="Clever tag line goes here"'
+  end
 end
 
 ##############################################################################
@@ -171,3 +184,5 @@ rule "" do |t|
     sh "#{spec_cmd} #{run_file_name} --format specdoc --colour #{example}" 
   end
 end
+
+

data/app_generators/merb/templates/Rakefile

@@ -6,6 +6,7 @@ require 'fileutils'
 require 'rubygems'
 
 MERB_ENV = ENV['MERB_ENV'] if ENV['MERB_ENV']
+$RAKE_ENV = true
 
 require File.dirname(__FILE__)+'/config/boot.rb'
 require MERB_FRAMEWORK_ROOT+'/tasks'
@@ -56,6 +57,18 @@ Spec::Rake::SpecTask.new('specs') do |t|
   t.spec_files = Dir['spec/**/*_spec.rb'].sort
 end
 
+desc "Run all model specs"
+Spec::Rake::SpecTask.new('model_specs') do |t|
+  t.spec_opts = ["--format", "specdoc", "--colour"]
+  t.spec_files = Dir['spec/models/**/*_spec.rb'].sort
+end
+
+desc "Run all controller specs"
+Spec::Rake::SpecTask.new('controller_specs') do |t|
+  t.spec_opts = ["--format", "specdoc", "--colour"]
+  t.spec_files = Dir['spec/controllers/**/*_spec.rb'].sort
+end
+
 desc "Run a specific spec with TASK=xxxx"
 Spec::Rake::SpecTask.new('spec') do |t|
   t.spec_opts = ["--format", "specdoc", "--colour"]

data/app_generators/merb/templates/app/helpers/global_helper.rb

@@ -1,5 +1,5 @@
 module Merb
   module GlobalHelper
-    # helpers deinfed here available to all views.  
+    # helpers defined here available to all views.  
   end
 end    

data/app_generators/merb/templates/app/views/exceptions/internal_server_error.html.erb

@@ -105,6 +105,10 @@
 					font-weight:bold;
 					color:#00BF10;
 				}
+				table.trace tr td.code a {
+				  width: 20px;
+				  float: left;
+				}
 				table.trace tr td.code .more {
 					color:#666;
 				}
@@ -164,17 +168,22 @@
 						<td class="expand">
 						</td>
 						<td class="path">
-							<%= (line.match(/^([^:]+)/)[1] rescue 'unknown').sub(/\/((opt|usr)\/local\/lib\/(ruby\/)?(gems\/)?(1.8\/)?(gems\/)?|.+\/app\/)/, '') %> in "<strong><%= line.match(/:in `(.+)'$/)[1] rescue '?' %></strong>"
+							<%= (line.match(/^([^:]+)/)[1] rescue 'unknown').sub(/\/((opt|usr)\/local\/lib\/(ruby\/)?(gems\/)?(1.8\/)?(gems\/)?|.+\/app\/)/, '') %>
+							<% unless line.match(/\.erb:/) %>
+                in "<strong><%= line.match(/:in `(.+)'$/)[1] rescue '?' %></strong>"
+              <% else %>
+                (<strong>ERB Template</strong>)
+              <% end %>
 						</td>
 						<td class="line">
-							<a href="txmt://open?url=file://<%=file = (line.match(/^([^:]+)/)[1] rescue 'unknown')%>&amp;line=<%= lineno = line.match(/:([0-9]+):/)[1] rescue '?' %>"><%=lineno%></a>
+							<a href="txmt://open?url=file://<%=file = (line.match(/^([^:]+)/)[1] rescue 'unknown')%>&amp;line=<%= lineno = line.match(/:([0-9]+):/)[1] rescue '?' %>"><%=lineno%></a>&nbsp;
 						</td> 
 					</tr>
 					<tr class="source">
 						<td class="collapse">
 						</td>
 						<td class="code" colspan="2"><% (__caller_lines__(file, lineno, 5) rescue []).each do |llineno, lcode, lcurrent| %>
-<a href="txmt://open?url=file://<%=file%>&amp;line=<%=llineno%>"><%= llineno %></a><%='<em>' if llineno==lineno.to_i %><%= lcode.size > 90 ? lcode[0..90]+'<span class="more">......</span>' : lcode %><%='</em>' if llineno==lineno.to_i %>
+<a href="txmt://open?url=file://<%=file%>&amp;line=<%=llineno%>"><%= llineno %></a><%='<em>' if llineno==lineno.to_i %><%= lcode.size > 90 ? CGI.escapeHTML(lcode[0..90])+'<span class="more">......</span>' : CGI.escapeHTML(lcode) %><%='</em>' if llineno==lineno.to_i %>
 <% end %>
 
 </td>

data/app_generators/merb/templates/config/merb.yml

@@ -32,6 +32,11 @@
 # automatically in production mode.
 #:cache_templates: true
 
+# this is true if you want mongrel to emulate the X-Sendfile header internally,
+# false if you want it to fall thru to apache or whatever front end server you use.
+# true by default
+#:mongrel_x_sendfile: false
+
 # Uncomment and set this if you want to run a drb server for upload progress
 # or other drb services.
 #:drb_server_port: 32323
@@ -61,4 +66,12 @@
 # It is often useful to use a differant layout from 'application' for errors
 # set this to the layout template (or :none) that you want to use by default
 #:exception_layout: :none
-  
+
+# You can override settings for specific environments by creating a yaml
+# file for that environment in config/environments.  For example, to
+# change the configuration only for development create
+# config/environments/development.yml
+
+# If you don't intend to parse JSON, use ActiveSupport, or want to roll your own
+# set this to true, to disable the loading of the JSON gem
+# :disable_json_gem: true

data/app_generators/merb/templates/spec/spec_helper.rb

@@ -6,4 +6,10 @@ require File.join(MERB_ROOT, 'config', 'merb_init')
 require 'merb/test/helper'
 require 'merb/test/rspec'
 
+Spec::Runner.configure do |config|
+    config.include(Merb::Test::Helper)
+    config.include(Merb::Test::RspecMatchers)
+end
+
+
 ### METHODS BELOW THIS LINE SHOULD BE EXTRACTED TO MERB ITSELF

data/app_generators/merb/templates/test/test_helper.rb

@@ -9,5 +9,6 @@ require File.join(MERB_ROOT, 'config', 'merb_init')
 require 'merb/test/helper'
 
 class Test::Unit::TestCase
+  include Merb::Test::Helper
   # Add more helper methods to be used by all tests here...
 end

data/lib/merb.rb

@@ -15,25 +15,28 @@ elsif ENV['EVENT']
     require 'mongrel'
 	puts "EVENT variable set but swiftiply not installed - falling back to normal Mongrel"
   end
+elsif ENV['PACKET']
+  begin
+    require 'packet_mongrel' 
+    puts "Using Packet Mongrel"
+  rescue LoadError
+    require 'mongrel'
+	puts "PACKET variable set but packet not installed - falling back to normal Mongrel"
+  end
 else
  require 'mongrel'
 end
 require 'fileutils'
 require 'merb/erubis_ext'
 require 'merb/logger'
-begin
-  require 'json/ext'
-rescue LoadError
-  puts "Using pure ruby JSON lib"
-  require 'json/pure'
-end
 
 require 'set'
 autoload :MerbUploadHandler, 'merb/upload_handler'
 autoload :MerbHandler, 'merb/mongrel_handler'
 
+require 'merb/version'
+
 module Merb
-  VERSION='0.4.1' unless defined?(::Merb::VERSION)
   autoload :Authentication, 'merb/mixins/basic_authentication'
   autoload :ControllerMixin, 'merb/mixins/controller'
   autoload :ErubisCaptureMixin, 'merb/mixins/erubis_capture'
@@ -42,6 +45,7 @@ module Merb
   autoload :ResponderMixin, 'merb/mixins/responder'
   autoload :ViewContextMixin, 'merb/mixins/view_context'
   autoload :WebControllerMixin, 'merb/mixins/web_controller'
+  autoload :GeneralControllerMixin, 'merb/mixins/general_controller'
   autoload :Caching, 'merb/caching'
   autoload :AbstractController, 'merb/abstract_controller'
   autoload :Const, 'merb/constants'
@@ -109,3 +113,19 @@ if $TESTING
   test_files = File.join(lib, 'test', '*.rb')
   Dir[test_files].each { |file| require file }
 end
+
+# If we're in the TEST environment or if running from Rake make sure to load 
+# config/merb.yml - which is normally done by Merb::Server.run
+Merb::Server.load_config if $TESTING || $RAKE_ENV
+
+# If you don't use the JSON gem, disable auto-parsing of json params too
+if Merb::Server.config[:disable_json_gem]
+  Merb::Request::parse_json_params = false
+else
+  begin
+    require 'json/ext'
+  rescue LoadError
+    puts "Using pure ruby JSON lib"
+    require 'json/pure'
+  end
+end