merb-core 0.9.2 → 0.9.3

data/Rakefile

@@ -40,7 +40,7 @@ spec = Gem::Specification.new do |s|
   s.platform     = Gem::Platform::RUBY
   s.author       = "Ezra Zygmuntowicz"
   s.email        = "ez@engineyard.com"
-  s.homepage     = "http://merb.devjavu.com"
+  s.homepage     = "http://merbivore.com"
   s.summary      = "Merb. Pocket rocket web framework."
   s.bindir       = "bin"
   s.description  = s.summary
@@ -85,6 +85,40 @@ task :uninstall => :clean do
   sh %{#{SUDO} gem uninstall #{NAME}}
 end
 
+namespace :github do
+  desc "Update Github Gemspec"
+  task :update_gemspec do
+    skip_fields = %w(new_platform original_platform)
+    integer_fields = %w(specification_version)
+    
+    result = "Gem::Specification.new do |s|\n"
+    spec.instance_variables.each do |ivar| 
+      value = spec.instance_variable_get(ivar)
+      name  = ivar.split("@").last
+      next if skip_fields.include?(name) || value.nil? || value == "" || (value.respond_to?(:empty?) && value.empty?)
+      if name == "dependencies"
+        value.each do |d| 
+          dep, *ver = d.to_s.split(" ")
+          result <<  "  s.add_dependency #{dep.inspect}, #{ver.join(" ").inspect.gsub(/[()]/, "")}\n"
+        end
+      else
+        case value
+        when Array
+          value =  name != "files" ? value.inspect : value.inspect.split(",").join(",\n")
+        when String
+          value = value.to_i if integer_fields.include?(name)
+          value = value.inspect
+        else
+          value = value.to_s.inspect
+        end
+        result << "  s.#{name} = #{value}\n"
+      end
+    end
+    result << "end"
+    File.open(File.join(File.dirname(__FILE__), "#{spec.name}.gemspec"), "w"){|f| f << result}
+  end
+end
+
 ##############################################################################
 # Documentation
 ##############################################################################
@@ -127,20 +161,36 @@ task :aok => [:specs, :rcov]
 #   t.spec_files = Dir["spec/**/*_spec.rb"].sort
 # end
 
-def setup_specs(name, spec_cmd='spec')
+def setup_specs(name, spec_cmd='spec', run_opts = "-c -f s")
   desc "Run all specs (#{name})"
   task "specs:#{name}" do
-    run_specs("spec/**/*_spec.rb", spec_cmd)
+    run_specs("spec/**/*_spec.rb", spec_cmd, ENV['RSPEC_OPTS'] || run_opts)
   end
 
   desc "Run private specs (#{name})"
   task "specs:#{name}:private" do
-    run_specs("spec/private/**/*_spec.rb", spec_cmd)
+    run_specs("spec/private/**/*_spec.rb", spec_cmd, ENV['RSPEC_OPTS'] || run_opts)
   end
 
   desc "Run public specs (#{name})"
   task "specs:#{name}:public" do
-    run_specs("spec/public/**/*_spec.rb", spec_cmd)
+    run_specs("spec/public/**/*_spec.rb", spec_cmd, ENV['RSPEC_OPTS'] || run_opts)
+  end
+
+  # With profiling formatter
+  desc "Run all specs (#{name}) with profiling formatter"
+  task "specs:#{name}_profiled" do
+    run_specs("spec/**/*_spec.rb", spec_cmd, "-c -f o")
+  end
+
+  desc "Run private specs (#{name}) with profiling formatter"
+  task "specs:#{name}_profiled:private" do
+    run_specs("spec/private/**/*_spec.rb", spec_cmd, "-c -f o")
+  end
+
+  desc "Run public specs (#{name}) with profiling formatter"
+  task "specs:#{name}_profiled:public" do
+    run_specs("spec/public/**/*_spec.rb", spec_cmd, "-c -f o")
   end
 end
 
@@ -244,7 +294,7 @@ namespace :repo do
       system "svn update"
     end
   end
-  
+
   desc "commit modified changes to the repository"
   task :commit do
     if File.directory?(".git")
@@ -253,24 +303,24 @@ namespace :repo do
       system "svn commit"
     end
   end
-  
+
 end
 
 # Run specific tests or test files. Searches nested spec directories as well.
-# 
+#
 # Based on a technique popularized by Geoffrey Grosenbach
 rule "" do |t|
   spec_cmd = (RUBY_PLATFORM =~ /java/) ? "jruby -S spec" : "spec"
   # spec:spec_file:spec_name
   if /spec:(.*)$/.match(t.name)
     arguments = t.name.split(':')
-    
+
     file_name = arguments[1]
     spec_name = arguments[2..-1]
 
     spec_filename = "#{file_name}_spec.rb"
     specs = Dir["spec/**/#{spec_filename}"]
-    
+
     if path = specs.detect { |f| spec_filename == File.basename(f) }
       run_file_name = path
     else
@@ -279,7 +329,7 @@ rule "" do |t|
     end
 
     example = " -e '#{spec_name}'" unless spec_name.empty?
-    
+
     sh "#{spec_cmd} #{run_file_name} --format specdoc --colour #{example}"
   end
 end

data/bin/merb

@@ -1,8 +1,12 @@
 #!/usr/bin/env ruby
 require "merb-core"
 
+if ARGV[0] && ARGV[0] =~ /^[^-]/
+  ARGV.push "-H"
+end 
+
 unless %w[-a --adapter -i --irb-console -r --script-runner].any? { |o| ARGV.index(o) }
   ARGV.push *%w[-a mongrel]
 end
-  
+
 Merb.start

data/lib/merb-core.rb

@@ -14,6 +14,7 @@ module Merb
   class << self
 
     # Startup Merb by setting up the Config and starting the server.
+    # This is where Merb application environment and root path are set.
     #
     # ==== Parameters
     # argv<String, Hash>::
@@ -26,9 +27,16 @@ module Merb
       end
       Merb.environment = Merb::Config[:environment]
       Merb.root = Merb::Config[:merb_root]
-      Merb::Server.start(Merb::Config[:port], Merb::Config[:cluster])
+      case Merb::Config[:action]
+      when :kill
+        Merb::Server.kill(Merb::Config[:port], 1)
+      when :kill_9
+        Merb::Server.kill(Merb::Config[:port], 9)
+      else
+        Merb::Server.start(Merb::Config[:port], Merb::Config[:cluster])
+      end
     end
-    
+
     # Start the Merb environment, but only if it hasn't been loaded yet.
     #
     # ==== Parameters
@@ -40,7 +48,7 @@ module Merb
         @started = true
       end
     end
-    
+
     # Restart the Merb environment explicitly.
     #
     # ==== Parameters
@@ -52,14 +60,53 @@ module Merb
     end
 
     attr_accessor :environment, :load_paths, :adapter
-    
+
     alias :env :environment
-    
+
     Merb.load_paths = Hash.new { [Merb.root] } unless Merb.load_paths.is_a?(Hash)
 
-    # This is the core mechanism for setting up your application layout
-    # merb-core won't set a default application layout, but merb-more will
-    # use the app/:type layout that is in use in Merb 0.5.
+    # This is the core mechanism for setting up your application layout.
+    # There are three application layouts in Merb:
+    #
+    # Regular app/:type layout of Ruby on Rails fame:
+    #
+    # app/models      for models
+    # app/mailers     for mailers (special type of controllers)
+    # app/parts       for parts, Merb components
+    # app/views       for templates
+    # app/controllers for controller
+    # lib             for libraries
+    #
+    # Flat application layout:
+    #
+    # application.rb       for models, controllers, mailers, etc
+    # config/init.rb       for initialization and router configuration
+    # config/framework.rb  for framework and dependencies configuration
+    # views                for views
+    #
+    # and Camping-style "very flat" application layout, where the whole Merb
+    # application and configs fit into a single file.
+    #
+    # ==== Notes
+    # Autoloading for lib uses empty glob by default. If you
+    # want to have your libraries under lib use autoload, add
+    # the following to Merb init file:
+    #
+    # Merb.push_path(:lib, Merb.root / "lib", "**/*.rb") # glob set explicity.
+    #
+    # Then lib/magicwand/lib/magicwand.rb with MagicWand module will
+    # be autoloaded when you first access that constant.
+    #
+    # ==== Examples
+    # This method gives you a way to build up your own application
+    # structure, for instance, to reflect the structure Rails
+    # uses to simplify transition of legacy application, you can
+    # set it up like this:
+    #
+    # Merb.push_path(:models,      Merb.root / "app" / "models",      "**/*.rb")
+    # Merb.push_path(:mailers,     Merb.root / "app" / "models",      "**/*.rb")
+    # Merb.push_path(:controllers, Merb.root / "app" / "controllers", "**/*.rb")
+    # Merb.push_path(:views,       Merb.root / "app" / "views",       "**/*.rb")
     #
     # ==== Parameters
     # type<Symbol>:: The type of path being registered (i.e. :view)
@@ -72,6 +119,23 @@ module Merb
       load_paths[type] = [path, file_glob]
     end
 
+    # Removes given types of application components
+    # from load path Merb uses for autoloading.
+    #
+    # ==== Parameters
+    # *args<Array(Symbol)>::
+    #   components names, for instance, :views, :models
+    #
+    # ==== Examples
+    # Using this combined with Merb::GlobalHelpers.push_path
+    # you can make your Merb application use legacy Rails
+    # application components.
+    #
+    # Merb.root = "path/to/legacy/app/root"
+    # Merb.remove_paths(:mailers)
+    # Merb.push_path(:mailers,     Merb.root / "app" / "models",      "**/*.rb")
+    #
+    # Will make Merb use app/models for mailers just like Ruby on Rails does.
     def remove_paths(*args)
       args.each {|arg| load_paths.delete(arg)}
     end
@@ -134,7 +198,7 @@ module Merb
     end
 
     # ==== Returns
-    # String:: The directory that contains the log file.
+    # String:: Path to directory that contains the log file.
     def log_path
       case Merb::Config[:log_file]
       when String then File.dirname(Merb::Config[:log_file])
@@ -143,9 +207,27 @@ module Merb
     end
 
     # ==== Returns
-    # String:: The root directory of the Merb framework.
+    # String:: The path of root directory of the Merb framework.
     def framework_root()  @framework_root ||= File.dirname(__FILE__)  end
 
+    # ==== Returns
+    # RegExp::
+    #   Regular expression against which deferred actions
+    #   are matched by Rack application handler.
+    #
+    # ==== Notes
+    # Concatenates :deferred_actions configuration option
+    # values.
+    def deferred_actions
+      @deferred ||= begin
+        if Merb::Config[:deferred_actions].empty?
+          /^\0$/
+        else
+          /#{Merb::Config[:deferred_actions].join("|")}/
+        end
+      end
+    end
+
     # Allows flat apps by setting no default framework directories and yielding
     # a Merb::Router instance. This is optional since the router will
     # automatically configure the app with default routes.
@@ -173,6 +255,10 @@ module Merb
     # name<~to_s>:: Name of the session type to register.
     # file<String>:: The file that defines this session type.
     # description<String>:: An optional description of the session type.
+    #
+    # ==== Notes
+    # Merb currently supports memory, cookie and memcache session
+    # types.
     def register_session_type(name, file, description = nil)
       @registered_session_types ||= Dictionary.new
       @registered_session_types[name] = {
@@ -185,24 +271,86 @@ module Merb
 
     # ==== Returns
     # Boolean:: True if Merb is running via script/frozen-merb or other freezer.
+    #
+    # ==== Notes
+    # Freezing means bundling framework libraries with your application
+    # making it independent from environment it runs in. This is a good
+    # practice to freeze application framework and gems it uses and
+    # very useful when application is run in some sort of sandbox,
+    # for instance, shared hosting with preconfigured gems.
     def frozen?
       @frozen
     end
 
     # Used by script/frozen-merb and other freezers to mark Merb as frozen.
+    # See Merb::GlobalHelpers.frozen? for more details on framework freezing.
     def frozen!
       @frozen = true
     end
-    
+
     # Load configuration and assign logger.
     #
     # ==== Parameters
     # options<Hash>:: Options to pass on to the Merb config.
+    #
+    # ==== Options
+    # :host<String>::             host to bind to,
+    #                             default is 0.0.0.0.
+    #
+    # :port<Fixnum>::             port to run Merb application on,
+    #                             default is 4000.
+    #
+    # :adapter<String>::          name of Rack adapter to use,
+    #                             default is "runner"
+    #
+    # :rackup<String>::           name of Rack init file to use,
+    #                             default is "rack.rb"
+    #
+    # :reload_classes<Boolean>::  whether Merb should reload
+    #                             classes on each request,
+    #                             default is true
+    #
+    # :environment<String>::      name of environment to use,
+    #                             default is development
+    #
+    # :merb_root<String>::        Merb application root,
+    #                             default is Dir.pwd
+    #
+    # :use_mutex<Boolean>::       turns action dispatch synchronization
+    #                             on or off, default is on (true)
+    #
+    # :session_id_key<String>::   session identifier,
+    #                             default is _session_id
+    #
+    # :log_delimiter<String>::    what Merb logger uses as delimiter
+    #                             between message sections, default is " ~ "
+    #
+    # :log_auto_flush<Boolean>::  whether the log should automatically
+    #                             flush after new messages are
+    #                             added, defaults to true.
+    #
+    # :log_file<IO>::             IO for logger. Default is STDOUT.
+    #
+    # :log_level<Symbol>::        logger level, default is :warn
+    #
+    # :disabled_components<Array[Symbol]>::
+    #   array of disabled component names,
+    #   for instance, to disable json gem,
+    #   specify :json. Default is empty array.
+    #
+    # :deferred_actions<Array(Symbol, String)]>::
+    #   names of actions that should be deferred
+    #   no matter what controller they belong to.
+    #   Default is empty array.
+    #
+    # Some of these options come from command line on Merb
+    # application start, some of them are set in Merb init file
+    # or environment-specific.
     def load_config(options = {})
       Merb::Config.setup({ :log_file => STDOUT, :log_level => :warn, :log_auto_flush => true }.merge(options))
       Merb::BootLoader::Logger.run
     end
-    
+
     # Load all basic dependencies (selected BootLoaders only).
     #
     # ==== Parameters
@@ -213,18 +361,32 @@ module Merb
       Merb::BootLoader::Dependencies.run
       Merb::BootLoader::BeforeAppRuns.run
     end
-    
-    # Reload the framework.
+
+    # Reload application and framework classes.
+    # See Merb::BootLoader::ReloadClasses for details.
     def reload
       Merb::BootLoader::ReloadClasses.reload
     end
-    
+
     # ==== Returns
-    # Boolean:: True if Merb is running via spec_helper.rb or other TEST scenario.
+    # Boolean:: True if Merb environment is testing for instance,
+    # Merb is running with RSpec, Test::Unit of other testing facility.
     def testing?
       $TESTING || Merb::Config[:testing]
     end
 
+    # Ask the question about which environment you're in.
+    # ==== Parameters
+    # env<Symbol, String>:: Name of the environment to query
+    #
+    # ==== Examples
+    # Merb.env #=> production
+    # Merb.env?(:production) #=> true
+    # Merb.env?(:development) #=> false
+    def env?(env)
+      Merb.env == env.to_s
+    end
+
     # If block was given configures using the block.
     #
     # ==== Parameters
@@ -233,6 +395,10 @@ module Merb
     # ==== Returns
     # Hash:: The current configuration.
     #
+    # ==== Notes
+    # See Merb::GlobalHelpers.load_config for configuration
+    # options list.
+    #
     # ==== Examples
     #   Merb.config do
     #     beer               "good"
@@ -244,13 +410,13 @@ module Merb
     #     session_secret_key "0d05a226affa226623eb18700"
     #     exception_details  true
     #     reload_classes     true
-    #     reload_time        0.5 
+    #     reload_time        0.5
     #   end
     def config(&block)
       Merb::Config.configure(&block) if block_given?
       Config
     end
-    
+
     # Disables the given core components, like a Gem for example.
     #
     # ==== Parameters
@@ -258,37 +424,48 @@ module Merb
     def disable(*components)
       disabled_components.push *components
     end
-    
+
     # ==== Parameters
     # Array:: All components that should be disabled.
     def disabled_components=(components)
       disabled_components.replace components
     end
-    
+
     # ==== Returns
     # Array:: All components that have been disabled.
     def disabled_components
       Merb::Config[:disabled_components] ||= []
     end
-    
+
     # ==== Returns
     # Boolean:: True if all components (or just one) are disabled.
     def disabled?(*components)
       components.all? { |c| disabled_components.include?(c) }
     end
-    
+
     # ==== Returns
-    # Array:: All Rakefiles for plugins.
+    # Array(String):: Paths Rakefiles are loaded from.
+    #
+    # ==== Notes
+    # Recommended way to find out what paths Rakefiles
+    # are loaded from.
     def rakefiles
       @rakefiles ||= ['merb-core/test/tasks/spectasks']
     end
 
     # ==== Parameters
-    # *rakefiles:: Rakefiles to add to the list of plugin Rakefiles.
+    # *rakefiles:: Rakefile pathss to add to the list of Rakefiles.
+    #
+    # ==== Notes
+    # Recommended way to add Rakefiles load path for plugins authors.
     def add_rakefiles(*rakefiles)
       @rakefiles ||= ['merb-core/test/tasks/spectasks']
       @rakefiles += rakefiles
     end
+
+
+
+
   end
 end
 
@@ -301,4 +478,4 @@ require 'merb-core/controller/mime'
 require 'merb-core/vendor/facets'
 
 # Set the environment if it hasn't already been set.
-Merb.environment ||= ENV['MERB_ENV'] || Merb::Config[:environment] || (Merb.testing? ? 'test' : 'development')
+Merb.environment ||= ENV['MERB_ENV'] || Merb::Config[:environment] || (Merb.testing? ? 'test' : 'development')