padrino-core 0.1.3 → 0.1.4

data/README.rdoc

@@ -7,11 +7,200 @@ To install the 'full-stack' padrino framework, simply grab the latest version fr
   $ sudo gem install padrino --source http://gemcutter.org
   
 This will install the necessary padrino gems to get you started.
-Now you are ready to use this gem to enhance your sinatra projects or to create new Padrino applications.
+Now you are ready to use this gem to enhance your existing Sinatra projects or build new Padrino applications.
 
 == Usage
 
-Include padrino-core overview here
+For a comprehensive overview of the whole padrino-framework, check out the 
+{Padrino Framework README}[http://github.com/padrino/padrino-framework/blob/master/README.rdoc]
+
+Sinatra has support for classes which can be extended to create an application: <tt>Sinatra::Base</tt> and <tt>Sinatra::Application</tt>
+These classes can be extended in order to create a Sinatra web application. These classes provide support for all the basic
+functionality afforded by Sinatra.
+
+Padrino has support for an enhanced base application class <tt>Padrino::Application</tt>. <tt>Padrino::Application</tt>
+expands the capabilities of Sinatra::Application and automatically provides the resulting application access to all of
+the padrino framework's functionalities. 
+
+Similar in spirit to Sinatra itself, Padrino application layout is extremely flexible and can be as small as a single file.
+However, Padrino provides many extensions which improve upon the ability to construct more complex applications.
+
+=== Simple Application Definition
+
+Let us first take a look at the simplest possible Padrino application:
+
+  # app.rb
+  PADRINO_ROOT = File.dirname(__FILE__) unless defined? PADRINO_ROOT
+  require 'padrino'
+  Padrino.load!
+
+  class SimpleApp < Padrino::Application
+    get '/ do
+      'Hello world'
+    end
+  end
+  
+=== Gemfile Dependency Resolution
+  
+While this is a fully operational Padrino application in itself, let us take a look at Padrino's expanded capabilites. First, 
+we can create Gemfile within the application root. This will contain a list of all the dependencies for our application.
+
+  # /Gemfile
+  clear_sources
+  source 'http://gemcutter.org'
+  gem 'sinatra',     :require_as => 'sinatra/base'
+  gem 'rack-flash'
+  
+This manifest file uses the standard <tt>bundler</tt> gem syntax of which details can be found in the
+{Bundler README}[http://github.com/wycats/bundler]
+This gem allows us to place all our dependencies into a single file. Padrino will then automatically require
+all necessary files (if they exist on the system). 
+
+If the dependencies are not on the system, you can automatically vendor all necessary gems 
+using the <tt>gem bundle</tt> command within the application root. Note that this is all possible without
+any further effort than adding the Gemfile (or having this generated automatically with generators explained later).
+
+=== Auto Load Paths
+
+Padrino also intelligently supports requiring useful files within your application automatically and provides
+functionality for easily splitting up your application into separate files. Padrino automatically requires <tt>config/database.rb</tt>
+as a convention for establishing database connection. Also, any files within the <tt>lib</tt> folder will be required 
+automatically by Padrino.
+
+This is powered by the fact that Padrino will automatically load (and reload) any directory patterns within the 'load path'. 
+Additional directory patterns can be added to the load path as needed by simply appending to the <tt>load_paths</tt> 
+within your application:
+
+  # app.rb
+  class SimpleApp < Padrino::Application
+    load_paths << ["app/special/*.rb", "some_file.rb"]
+  end
+  
+This will instruct Padrino to autoload these files (and reload them when changes are detected). By default, the load path 
+contains certain paths known to contain important files such as controllers, mailers, models, urls, and helpers. 
+
+=== Initializers
+
+Padrino also has support for 'initializers' which are important setup steps or configuration within an application
+that should occur during the bootup process. To construct initializers, simply add a file to the <tt>config/initializers<tt>
+directory following this convention:
+
+  # config/initializers/example.rb
+  module ExampleInitializer
+    def self.registered(app)
+      # Manipulate 'app' here to register components or adjust configuration
+      app.set :environment, :production # just an example configuration change
+      app.use Hassle # or even enable middleware
+    end
+  end
+  
+Initializers are automatically required and 'registered' during the application startup process. Note that
+the name of the module must be the name of the file appended with 'Initializer' (i.e sample.rb => SampleInitializer)
+
+=== Controllers
+
+Suppose we wanted to add additional routes to our Padrino application, and we want to organize the routes
+within a more structured layout. Simply add a <tt>controllers</tt> or <tt>app/controllers</tt> folder and create a file as such:
+
+  # controllers/example.rb
+  SimpleApp.controllers do
+    get "/test" do
+      "Text to return"
+    end
+  end
+  
+=== Application Logging
+
+Padrino also supports robust logging capabilities. By default, logging information will
+go to the STDOUT in development (for use in a console) and in an environment-specific log file <tt>log/development.log</tt>
+in test and production environments.
+
+You can modify the logging behavior or disable logging altogether:
+
+  # app.rb
+  class SimpleApp < Padrino::Application
+    disable :logging     # Turns off logging
+    enable  :log_to_file # Forces logging to be written to a file
+  end
+  
+To use the logger within a Padrino application, simply refer to the <tt>logger</tt> method accessible
+within your app and any controller or views:
+
+  # controllers/example.rb
+  SimpleApp.controllers do
+    get("/test") { logger.info "This is a test" }
+  end
+  
+The logger automatically supports severity through the use of <tt>logger.info</tt>, <tt>logger.warn</tt>, <tt>logger.error</tt>, et al.
+For more information about the logger, check out the {Logger RDOC}[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/]
+
+=== Mounting Applications
+
+Padrino applications are all automatically mountable into other Padrino projects. This means that a given Padrino
+project directory can easily mount multiple applications. This allows for better organization of complex applications,
+re-usable applications that can be applied (i.e admin, auth, blog) and even more flexibility. 
+
+You can think of mountable applications as a 'full-featured' merb slice or rails engine. Instead of a separate construct, 
+any application can simply be packaged and mounted into another project.
+
+Padrino stores application mounting information by default within <tt>config/apps.rb</tt>. This file is intended
+to keep all information regarding what applications are mounted to which uri's. An <tt>apps.rb</tt> file has
+the following structure:
+
+  Padrino.mount("blog").to("/blog")
+  Padrino.mount("website").to("/website")
+  
+This would mount two applications onto the Padrino project, one served from the '/blog' uri namespace and the other
+served from the '/website' uri namespace. Often a Padrino project directory requires a single 'core' application
+which is served from the uri root. This can be easily configured using:
+
+  Padrino.mount_core("app_name") # mounts app with class AppName, in file <tt>app/app.rb</tt>
+  Padrino.mount_core("app_name", :app_file => Padrino.root('app.rb')) # now with file in <tt>app.rb</tt>
+  
+This will mount a 'core' application with class AppName from the file 'app.rb' to the uri root which will
+act as a primary application.
+
+=== Development Reloader
+
+Padrino applications also have the enabled ability to automatically reload all changing application files without
+the need to restart the server. Through the use of a customized Rack middleware, all files on the 'load path'
+are monitored and reloaded whenever changes are applied. 
+
+This makes rapid development much easier and provides a better alternative to 'shotgun' or 'rerun' 
+which require the application server to be restarted which makes requests take much longer to complete.
+
+An application can explicitly enable / disable reloading through the use of options:
+
+  # app.rb
+  class SimpleApp < Padrino::Application
+    disable :reload # reload is disabled in all environments
+    enable  :reload # enabled in all environments
+  end
+  
+By default, reloading is enabled in development and disabled in the test and production environments.
+
+=== Terminal Commands
+
+Padrino also comes equipped with multiple useful terminal commands which can be activated to perform
+common tasks such as starting / stopping the application, executing the unit tests or activating an irb session.
+
+The following commands are available:
+
+  # starts the app server (non-daemonized)
+  $ padrino start 
+  # starts the app server (daemonized) with given port, environment and adapter
+  $ padrino start -d -p 3000 -e development -a thin 
+  
+  # Stops a daemonized app server
+  $ padrino stop
+  
+  # Run all the unit tests
+  $ padrino test
+  
+  # Bootup the Padrino console (irb)
+  $ padrino console
+  
+Using these commands can simplify common tasks making development that much smoother.
 
 == Copyright
 

data/Rakefile

@@ -8,11 +8,13 @@ begin
     gem.summary = "The required Padrino core gem"
     gem.description = "The Padrino core gem required for use of this framework"
     gem.email = "nesquena@gmail.com"
-    gem.homepage = "http://github.com/padrino/padrino-core"
+    gem.homepage = "http://github.com/padrino/padrino-framework/tree/master/padrino-core"
     gem.authors = ["Padrino Team", "Nathan Esquenazi", "Davide D'Agostino", "Arthur Chiu"]
+    gem.executables = ["padrino"]
     gem.add_runtime_dependency     "sinatra",       ">= 0.9.2"
     gem.add_runtime_dependency     "thor",          ">= 0.11.8"
     gem.add_development_dependency "haml",          ">= 2.2.1"
+    gem.add_runtime_dependency     "bundler",       ">= 0.5.0"
     gem.add_development_dependency "shoulda",       ">= 0"
     gem.add_development_dependency "mocha",         ">= 0.9.7"
     gem.add_development_dependency "rack-test",     ">= 0.5.0"

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.4

data/bin/padrino

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
-%w[rubygems activesupport thor].each { |gem| require gem }
+%w[rubygems thor].each { |gem| require gem }
+require File.dirname(__FILE__) + "/../lib/padrino-core/support_lite"
 require File.dirname(__FILE__) + "/../lib/padrino-core/tasks"
 
 arguments = ARGV.any? ? ARGV : ['-h']

data/lib/padrino-core.rb

@@ -6,7 +6,6 @@ PADRINO_ENV = ENV["PADRINO_ENV"] ||= ENV["RACK_ENV"] ||= "development" unless de
 
 module Padrino
   class ApplicationLoadError < RuntimeError; end
-
   # Helper method for file references.
   #
   # Example:
@@ -16,10 +15,10 @@ module Padrino
   def self.root(*args)
     File.join(PADRINO_ROOT, *args)
   end
-  
+
   # Helper method that return PADRINO_ENV
   def self.env
-    PADRINO_ENV
+    PADRINO_ENV.to_s
   end
 
   # Returns the resulting rack builder mapping each 'mounted' application

data/lib/padrino-core/application.rb

@@ -11,8 +11,11 @@ module Padrino
 
     class << self
       def inherited(subclass)
+        CALLERS_TO_IGNORE.concat(PADRINO_IGNORE_CALLERS)
         subclass.default_configuration!
         super # Loading the subclass
+        subclass.register Padrino::Routing if defined?(Padrino::Routing)
+        subclass.check_single_app
       end
 
       # Hooks into when a new instance of the application is created
@@ -32,39 +35,52 @@ module Padrino
         include(*extensions)  if extensions.any?
       end
 
+      # Return true if the bootloader => Padrino.load! it's instatiated in the same
+      # palace of the app.
+      # Notice that <tt>signle_apps</tt> was not reloadable!
+      def single_app?
+        @_single_app
+      end
+
       protected
 
       # Setup the application by registering initializers, load paths and logger
       # Invoked automatically when an application is first instantiated
       def setup_application!
-        return if @configured
+        return if @_configured
         self.register_framework_extensions
         self.calculate_paths
         self.register_initializers
         self.require_load_paths
         self.setup_logger
-        @configured = true
+        @_configured = true
       end
 
       # Defines default settings for Padrino application
       def default_configuration!
         # Overwriting Sinatra defaults
+        set :app_file, caller_files.first || $0 # Assume app file is first caller
+        set :environment, PADRINO_ENV.to_sym
         set :raise_errors, true if development?
-        set :logging, true
+        set :logging, !test?
         set :sessions, true
         set :log_to_file, !development?
         set :reload, development?
         # Padrino specific
         set :app_name, self.to_s.underscore.to_sym
-        set :environment, PADRINO_ENV.to_sym
         set :default_builder, 'StandardFormBuilder'
         enable :flash
         # Plugin specific
-        enable :padrino_routing
         enable :padrino_mailer
         enable :padrino_helpers
       end
 
+      def check_single_app
+        @_single_app = File.identical?(self.app_file, Padrino.called_from.to_s)
+        single_message = "=> Instantiated #{File.basename(self.app_file)} in single app mode, reload is not available"
+        puts single_message if @_single_app && logging?
+      end
+
       # Calculates any required paths after app_file and root have been properly configured
       # Executes as part of the setup_application! method
       def calculate_paths
@@ -76,23 +92,17 @@ module Padrino
       # Requires the middleware and initializer modules to configure components
       def register_initializers
         use Rack::Session::Cookie
-        use Rack::Flash if flash?
-        use Padrino::Reloader if reload?
+        use Rack::Flash if defined?(Rack::Flash) && flash?
+        use Padrino::Reloader unless single_app?
         register DatabaseSetup if defined?(DatabaseSetup)
-        Dir[Padrino.root + '/config/initializers/*.rb'].each do |file|
-          Padrino.load_dependencies(file)
-          file_class = File.basename(file, '.rb').classify
-          register "#{file_class}Initializer".constantize
-        end
+        @initializer_path ||= Padrino.root + '/config/initializers/*.rb'
+        Dir[@initializer_path].each { |file| register_initializer(file) }
       end
 
       # Registers all desired padrino extension helpers/routing
       def register_framework_extensions
-        return if @registered
-        register Padrino::Routing  if padrino_routing?
-        register Padrino::Mailer   if padrino_mailer?
-        register Padrino::Helpers  if padrino_helpers?
-        @registered = true
+        register Padrino::Mailer   if padrino_mailer?  && defined?(Padrino::Mailer)
+        register Padrino::Helpers  if padrino_helpers? && defined?(Padrino::Helpers)
       end
 
       # Require all files within the application's load paths
@@ -102,7 +112,7 @@ module Padrino
 
       # Creates the log directory and redirects output to file if needed
       def setup_logger
-        return unless log_to_file?
+        return unless logging? && log_to_file?
         FileUtils.mkdir_p("#{Padrino.root}/log") unless File.exists?("#{Padrino.root}/log")
         log = File.new("#{Padrino.root}/log/#{PADRINO_ENV.downcase}.log", "a+")
         $stdout.reopen(log)
@@ -125,7 +135,20 @@ module Padrino
       # Resets application routes for use in reloading the application
       # This performs a basic routes reload (compatible with sinatra edge)
       def reset_routes!
-        @routes = Padrino::Application.dupe_routes; load(self.app_file)
+        return if single_app? # Don't reset routes for single app
+        @routes = Padrino::Application.dupe_routes
+        load(self.app_file)
+      end
+
+      # Registers an initializer with the application
+      # register_initializer('/path/to/initializer')
+      def register_initializer(file_path)
+        Padrino.load_dependencies(file_path)
+        file_class = File.basename(file_path, '.rb').camelize
+        register "#{file_class}Initializer".constantize
+      rescue NameError => e
+        puts "The module '#{file_class}Initializer' (#{file_path}) didn't loaded properly!" if logging?
+        puts "   Initializer error was '#{e.message}'" if logging?
       end
     end
   end

data/lib/padrino-core/caller.rb

@@ -0,0 +1,35 @@
+module Padrino
+  PADRINO_IGNORE_CALLERS = [
+    %r{/padrino-.*$},            # all padrino code
+    %r{/sinatra},                # all sinatra code
+    %r{lib/tilt.*\.rb$},         # all tilt code
+    %r{\(.*\)},                  # generated code
+    %r{shoulda/context\.rb$},    # shoulda hacks
+    %r{mocha/integration},       # mocha hacks
+    %r{test/unit},               # test unit hacks
+    %r{rake_test_loader\.rb},    # rake hacks
+    %r{custom_require\.rb$},     # rubygems require hacks
+    %r{active_support},          # active_support require hacks
+    %r{/thor},                   # thor require hacks
+  ]
+
+  # add rubinius (and hopefully other VM impls) ignore patterns ...
+  PADRINO_IGNORE_CALLERS.concat(RUBY_IGNORE_CALLERS) if defined?(RUBY_IGNORE_CALLERS)
+
+  # Returns the filename for the file that is the direct caller (first caller)
+  def self.first_caller
+    caller_files.first
+  end
+
+  # Like Kernel#caller but excluding certain magic entries and without
+  # line / method information; the resulting array contains filenames only.
+  def self.caller_files
+    caller_locations.map { |file,line| file }
+  end
+
+  def self.caller_locations
+    caller(1).
+      map    { |line| line.split(/:(?=\d|in )/)[0,2] }.
+      reject { |file,line| PADRINO_IGNORE_CALLERS.any? { |pattern| file =~ pattern } }
+  end
+end

data/lib/padrino-core/loader.rb

@@ -2,15 +2,29 @@ module Padrino
   class << self
     # Requires necessary dependencies as well as application files from root lib and models
     def load!
+      return if loaded?
+      @_called_from = first_caller
       load_required_gems # load bundler gems
       load_dependencies("#{root}/config/apps.rb", "#{root}/config/database.rb") # load configuration
       load_dependencies("#{root}/lib/**/*.rb", "#{root}/models/*.rb") # load root app dependencies
       reload! # We need to fill our Stat::CACHE but we do that only for development
+      @_loaded = true
     end
 
-    # Method for reload required classes
-    def reload!
-      Stat::reload!
+    # This adds the ablity to instantiate Padrino.load! after Padrino::Application definition.
+    def called_from
+      @_called_from || first_caller
+    end
+
+    # Return true if Padrino was loaded with Padrino.load!
+    def loaded?
+      @_loaded
+    end
+
+    # Attempts to require all dependencies with bundler; if this fails, uses system wide gems
+    def load_required_gems
+      load_bundler_manifest
+      require_vendored_gems
     end
 
     # Attempts to load/require all dependency libs that we need.
@@ -26,24 +40,34 @@ module Padrino
     end
     alias_method :load_dependency, :load_dependencies
 
-    # Attempts to require all dependencies with bundler; if fails, we try to use system wide gems
-    def load_required_gems
-      begin
-        require 'bundler'
-        gemfile_path = root("Gemfile")
-        puts "=> Loading GemFile #{gemfile_path} for #{PADRINO_ENV}"
-        # TODO possibly support padrino apps where no Gemfile is specified (skip requires, assume explicit dependencies)
-        Bundler::Environment.load(gemfile_path).require_env(PADRINO_ENV)
-      rescue Bundler::DefaultManifestNotFound => e
-        puts "=> You didn't create Bundler Gemfile manifest or you are not in a Sinatra application."
-      end
+    # Method for reload required classes
+    def reload!
+      Stat::reload!
+    end
 
-      begin
-        load_dependencies(root('/../vendor', 'gems', PADRINO_ENV))
-        puts "=> Using bundled gems"
-      rescue LoadError => e
-        puts "=> Using system wide gems (No bundled gems)"
-      end
+    protected
+
+    # Loads the bundler manifest Gemfile if it exists
+    def load_bundler_manifest
+      require 'bundler'
+      say "=> Locating Gemfile for #{PADRINO_ENV}"
+      Bundler::Environment.load(root("Gemfile")).require_env(PADRINO_ENV)
+      say " ... Loaded!"
+    rescue Bundler::ManifestFileNotFound, Bundler::DefaultManifestNotFound => e
+      say " ... Not Found"
+    end
+
+    # Loads bundled gems if they exist
+    def require_vendored_gems
+      load_dependencies(root('/../vendor', 'gems', PADRINO_ENV))
+      say " (Loading bundled gems)\n"
+    rescue LoadError => e
+      say " (Loading system gems)\n"
+    end
+
+    # Prints out a message to the stdout if not in test environment
+    def say(text)
+      print text if Padrino.env != 'test'
     end
   end
 end