camping 1.5.180 → 2.0.rc0

data/bin/camping

@@ -1,279 +1,97 @@
 #!/usr/bin/env ruby
 
-require 'delegate'
+trap("INT") { exit }
 require 'optparse'
 require 'ostruct'
-
 require 'stringio'
-require 'camping'
-require 'camping/reloader'
 require 'yaml'
 
+$:.unshift File.dirname(__FILE__) + "/../lib"
+require 'camping'
+require 'camping/server'
+
 conf = OpenStruct.new(:host => '0.0.0.0', :port => 3301)
 
 # Setup paths
 if home = ENV['HOME'] # POSIX
-  conf.db = File.join(home, '.camping.db')
-  conf.rc = File.join(home, '.campingrc')
+  db_path = File.join(home, '.camping.db')
+  rc_path = File.join(home, '.campingrc')
 elsif home = ENV['APPDATA'] # MSWIN
-  conf.db = File.join(home, 'Camping.db')
-  conf.rc = File.join(home, 'Campingrc')
-end
-
-# Load configuration if any
-if conf.rc and File.exists?( conf.rc )
-  YAML.load_file(conf.rc).each do |k,v|
-    conf.send("#{k}=", v)
-  end 
+  db_path = File.join(home, 'Camping.db')
+  rc_path = File.join(home, 'Campingrc')
 end
 
 # Parse options
 opts = OptionParser.new do |opts|
-    opts.banner = "Usage: camping app1.rb, app2.rb..."
-    opts.define_head "#{File.basename($0)}, the microframework ON-button for ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}]"
-    opts.separator ""
-    opts.separator "Specific options:"
-
-    opts.on("-h", "--host HOSTNAME", "Host for web server to bind to (default is all IPs)") { |conf.host| }
-    opts.on("-p", "--port NUM", "Port for web server (defaults to #{conf.port})") { |conf.port| }
-    opts.on("-d", "--database FILE", "Database file (defaults to #{conf.db})") { |conf.db| }
-    opts.on("-l", "--log FILE", "Start a database log ('-' for STDOUT)") { |conf.log| }
-    opts.on("-C", "--console", "Run in console mode with IRB") { conf.server = :console }
-    opts.on("-s", "--server NAME", "Server to force (mongrel, webrick, console)") { |s| conf.server = s.to_sym }
-
-    opts.separator ""
-    opts.separator "Common options:"
-  
-    # No argument, shows at tail.  This will print an options summary.
-    # Try it and see!
-    opts.on_tail("-?", "--help", "Show this message") do
-        puts opts
-        exit
-    end
-  
-    # Another typical switch to print the version.
-    opts.on_tail("-v", "--version", "Show version") do
-        class << Gem; attr_accessor :loaded_specs; end
-        puts Gem.loaded_specs['camping'].version
-        exit
-    end
-end
-
-opts.parse! ARGV
-if ARGV.length < 1
+  opts.banner = "Usage: camping app1.rb, app2.rb..."
+  opts.define_head "#{File.basename($0)}, the microframework ON-button for ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}]"
+  opts.separator ""
+  opts.separator "Specific options:"
+
+  opts.on("-h", "--host HOSTNAME", "Host for web server to bind to (default is all IPs)") { |val| conf.host = val }
+  opts.on("-p", "--port NUM", "Port for web server (defaults to #{conf.port})") { |val| conf.port = val }
+  opts.on("-d", "--database FILE", "SQLite3 database path (defaults to #{db_path ? db_path : '<none>'})") { |db_path| conf.database = {:adapter => 'sqlite3', :database => db_path} }
+  opts.on("-C", "--console", "Run in console mode with IRB") { conf.server = "console" }
+  server_list = ["mongrel", "webrick", "console"]
+  opts.on("-s", "--server NAME", server_list, "Server to force (#{server_list.join(', ')})") { |val| conf.server = val }
+
+  opts.separator ""
+  opts.separator "Common options:"
+
+  # No argument, shows at tail.  This will print an options summary.
+  # Try it and see!
+  opts.on_tail("-?", "--help", "Show this message") do
     puts opts
     exit
-end
+  end
 
-# Default database
-unless conf.database
-  unless conf.db
-    puts "!! No home directory found.  Please specify a database file, see --help."; exit
+  # Another typical switch to print the version.
+  opts.on_tail("-v", "--version", "Show version") do
+    puts Gem.loaded_specs['camping'].version
+    exit
   end
-  conf.database = {:adapter => 'sqlite3', :database => conf.db}
 end
 
-# Load apps
-PATHS = ARGV.dup
-apps = PATHS.inject([]) do |apps, script|
-    if File.directory? script
-        apps.push(*Dir[File.join(script, '*.rb')])
-    else
-        apps << script
-    end
+begin
+  opts.parse! ARGV
+rescue OptionParser::ParseError => ex
+  STDERR.puts "!! #{ex.message}"
+  puts "** use `#{File.basename($0)} --help` for more details..."
+  exit 1
 end
 
-Camping::Reloader.database = conf.database
-Camping::Reloader.log = conf.log
-apps.map! { |script| Camping::Reloader.new(script) }
-abort("** No apps successfully loaded") unless apps.detect { |app| app.klass }
-
-def apps.find_new_scripts
-    each { |app| app.reload_app }
-    PATHS.each do |path|
-        Dir[File.join(path, '*.rb')].each do |script|
-            smount = File.basename(script, '.rb')
-            next if detect { |x| x.mount == smount }
-
-            puts "** Discovered new #{script}"
-            app = Camping::Reloader.new(script)
-            next unless app
-
-            yield app
-            self << app
-        end
-    end
-    self.sort! { |x, y| x.mount <=> y.mount }
+if ARGV.length < 1
+  puts opts
+  exit 1
 end
 
-def apps.index_page
-    welcome = "You are Camping"
-    apps = self
-    b = Markaby::Builder.new({}, {})
-    b = b.instance_eval do
-        html do
-            head do
-                title welcome
-                style <<-END, :type => 'text/css'
-                    body { 
-                        font-family: verdana, arial, sans-serif; 
-                        padding: 10px 40px; 
-                        margin: 0; 
-                    }
-                    h1, h2, h3, h4, h5, h6 {
-                        font-family: utopia, georgia, serif;
-                    }
-                END
-            end
-            body do
-                h1 welcome
-                p %{Good day.  These are the Camping apps you've mounted.}
-                ul do
-                    apps.each do |app|
-                        next unless app.klass
-                        li do
-                            h3(:style => "display: inline") { a app.klass.name, :href => "/#{app.mount}" }
-                            small { text " / " ; a "View Source", :href => "/code/#{app.mount}" }
-                        end
-                    end
-                end
-            end
-        end
-    end
-    b.to_s
+# Load configuration if any
+if rc_path and File.exists?(rc_path)
+  YAML.load_file(rc_path).each do |k,v|
+    conf.send("#{k}=", v) unless conf.send(k)
+  end 
+  puts "** conf file #{rc_path} loaded"
 end
 
-# Check that mongrel exists 
-unless conf.server 
-    begin
-        require 'mongrel'
-        require 'mongrel/camping'
-        conf.server = :mongrel
-    rescue LoadError 
-        conf.server = :webrick 
-    end
+# Default db
+if conf.database.nil? and db_path
+  conf.database = { :adapter => 'sqlite3', :database => db_path }
 end
 
-# Running the selected server
-case conf.server.to_s
-when 'mongrel'
-    require 'mongrel'
-    require 'mongrel/camping'
-
-    class IndexHandler < Mongrel::HttpHandler
-        def initialize(apps, server)
-            @apps = apps
-            @server = server
-        end
-        def process(req, res)
-            res.start(200) do |head, out|
-                @apps.find_new_scripts do |app|
-                    @server.register "/#{app.mount}", Mongrel::Camping::CampingHandler.new(app)
-                    @server.register "/code/#{app.mount}", ViewSource.new(app)
-                end
-                out << @apps.index_page
-            end
-        end
-    end
-    class ViewSource < Mongrel::HttpHandler
-        def initialize(app)
-            @app = app
-        end
-        def process(req, res)
-            res.start(200) do |head, out|
-                head['Content-Type'] = 'text/plain'
-                out << @app.view_source
-            end
-        end
-    end
-    begin
-        config = Mongrel::Configurator.new :host => conf.host do
-            listener :port => conf.port do
-                if apps.length > 1
-                    apps.each do |app|
-                        uri "/#{app.mount}", :handler => Mongrel::Camping::CampingHandler.new(app)
-                        uri "/code/#{app.mount}", :handler => ViewSource.new(app)
-                    end
-                    uri "/", :handler => IndexHandler.new(apps, @listener)
-                else
-                    uri "/", :handler => Mongrel::Camping::CampingHandler.new(apps.first)
-                end
-                uri "/favicon.ico", :handler => Mongrel::Error404Handler.new("")
-                trap("INT") { stop }
-                run
-            end
-        end 
-
-        puts "** Camping running on #{conf.host}:#{conf.port}."
-        config.join
-    rescue Errno::EADDRINUSE
-        puts "** ERROR : address #{conf.host}:#{conf.port} already in use."
-    end
-when 'webrick'
-    require 'webrick/httpserver'
-    require 'camping/webrick'
-
-    # Mount the root
-    s = WEBrick::HTTPServer.new(:BindAddress => conf.host, :Port => conf.port)
-    if apps.length > 1
-        apps.each do |app|
-            s.mount "/#{app.mount}", WEBrick::CampingHandler, app
-            s.mount_proc("/code/#{app.mount}") do |req, resp|
-                resp['Content-Type'] = 'text/plain'
-                resp.body = app.view_source
-            end
-        end
-        s.mount_proc("/") do |req, resp|
-            apps.find_new_scripts do |app|
-                s.mount "/#{app.mount}", WEBrick::CampingHandler, app
-                s.mount_proc("/code/#{app.mount}") do |req, resp|
-                    resp['Content-Type'] = 'text/plain'
-                    resp.body = app.view_source
-                end
-            end
-            resp.body = apps.index_page
-        end
-    else
-        s.mount "/", WEBrick::CampingHandler, apps.first
-    end
-
-    # Server up
-    trap(:INT) do
-        s.shutdown
-    end
-    s.start
-when 'lighttpd'
-    require 'rbconfig'
-    ruby = File.join(Config::CONFIG['bindir'], Config::CONFIG['RUBY_INSTALL_NAME'])
-    dispatcher =<<SCRIPT
-#!#{ruby}
-require 'rubygems'
-require 'camping/fastcgi'
-Camping::Models::Base.establish_connection(Marshal.load(#{Marshal.dump(conf.database).dump})) 
-Camping::FastCGI.serve("")
-SCRIPT
-    lighttpd_conf =<<CONF
-server.port                 = #{conf.port}
-server.bind                 = "#{conf.host}"
-server.modules              = ( "mod_fastcgi" )
-server.document-root        = "/dont/need/one" 
 
-#### fastcgi module
-fastcgi.server = ( "/" => ( 
-  "localhost" => ( 
-    "socket" => "/tmp/camping-blog.socket",
-    "bin-path" => "#{conf.dispatcher}",
-    "check-local" => "disable",
-    "max-procs" => 1 ) ) )
-CONF
- 
-when 'console'
-    ARGV.clear # Avoid passing args to IRB 
+# get a copy of the paths to pass to the server
+paths = ARGV.dup
 
-    require 'irb' 
-    require 'irb/completion' 
-    if File.exists? ".irbrc"
-        ENV['IRBRC'] = ".irbrc"
-    end
-    IRB.start 
+# Check that mongrel exists 
+if conf.server.nil? || conf.server == "mongrel"
+  begin
+    require 'mongrel'
+    conf.server = "mongrel"
+  rescue LoadError 
+    puts "!! Could not load mongrel. Falling back to webrick."
+    conf.server = "webrick"
+  end
 end
+
+server = Camping::Server.new(conf, paths)
+server.start

data/book/01_introduction

@@ -0,0 +1,19 @@
+= Introduction
+
+Camping is a small web framework, less than 4k, a little white blood cell in
+the vein of Rails. This little book will start with a tutorial which takes
+about fifteen minutes - by the end you should have a little Camping site up.
+The following chapters will eventually go deeper into how both Camping, HTTP
+and Rack works.
+
+("Eventually", because these chapters are not written yet. This book is
+currently a very much work in progress, and we'll be very grateful if you want
+to help out.)
+
+If you at any moment need some help or have any questions or comments, we
+highly recommend {the mailing list}[http://rubyforge.org/mailman/listinfo/camping-list]
+which got plenty of nice people willing to help. We also have an IRC-channel
+at {#camping @ irc.freenode.net}[http://java.freenode.net/?channel=camping]
+if you're into that sort of things.
+
+Enough talk. Ready? Let's {"get started"}[link:book/02_getting_started.html].

data/book/02_getting_started

@@ -0,0 +1,443 @@
+= Getting Started
+
+Start a new text file called nuts.rb. Here's what you put inside:
+ 
+  Camping.goes :Nuts
+
+Save it. Then, open a command prompt in the same directory. You'll want to
+run:
+
+  $ camping nuts.rb
+
+And you should get a message which reads:
+
+  ** Camping running on 0.0.0.0:3301.
+
+This means that right now The Camping Server is running on port 3301 on your
+machine. Open your browser and visit http://localhost:3301/.
+
+Your browser window should show:
+
+  Camping Problem!
+  
+  / Not found
+
+No problem with that. The Camping Server is running, but it doesn't know what
+to show. Let's tell him.
+
+== Hello clock
+
+So, you've got Camping installed and it's running. Keep it running. You can
+edit files and The Camping Server will reload automatically. When you need to
+stop the server, press Control-C.
+
+Let's show something. At the bottom of nuts.rb add:
+
+  module Nuts::Controllers
+    class Index < R '/'
+      def get
+        Time.now.to_s
+      end
+    end
+  end
+
+Save the file and refresh the browser window. Your browser window should show
+the time, e.g.
+
+  Sun Jul 15 12:56:15 +0200 2007
+
+== Enjoying the view
+
+The Camping microframework allows us to separate our code using the MVC
+(Model-View-Controller) design pattern. Let's add a view to our Nuts
+application. Replace the <tt>module Nuts::Controllers</tt> with:
+
+  module Nuts::Controllers
+    class Index < R '/'
+      def get
+        @time = Time.now
+        render :sundial
+      end
+    end
+  end
+
+  module Nuts::Views
+    def layout
+      html do
+        head do
+          title { "Nuts And GORP" }
+        end
+        body { self << yield }
+      end
+    end
+
+    def sundial
+      p "The current time is: #{@time}"
+    end
+  end
+  
+Save the file and refresh your browser window and it should show a message
+like:
+
+   The current time is: Sun Jul 15 13:05:41 +0200 2007
+
+And the window title reads "Nuts And GORP".
+
+Here you can see we call <tt>render :sundial</tt> from our controller. This
+does exactly what it says, and renders our <tt>sundial</tt> method. We've also
+added a special method called <tt>layout</tt> which Camping will automatically
+wrap our sundial output in. If you're familiar with HTML, you'll see that our
+view contains what looks HTML tag names. This is Markaby, which is like
+writing HTML using Ruby!
+
+Soon enough, you'll find that you can return anything from the controller, and
+it will be sent to the browser. But let's keep that for later and start
+investigating the routes.
+
+== Routes
+
+You probably noticed the weird <tt>R '/'</tt> syntax in the previous page.
+This is an uncommon feature of Ruby that is used in our favorite
+microframework, to describe the routes which the controller can be accessed
+on.
+
+These routes can be very powerful, but we're going to have look at the
+simplest ones first.
+
+  module Nuts::Controllers
+    class Words < R '/welcome/to/my/site'
+      def get
+        "You got here by: /welcome/to/my/site"
+      end
+    end
+    
+    class Digits < R '/nuts/(\d+)'
+      def get(number)
+        "You got here by: /nuts/#{number}"
+      end
+    end
+
+    class Segment < R '/gorp/([^/]+)'
+      def get(everything_else_than_a_slash)
+        "You got here by: /gorp/#{everything_else_than_a_slash}"
+      end
+    end
+    
+    class DigitsAndEverything < R '/nuts/(\d+)/([^/]+)'
+      def get(number, everything)
+        "You got here by: /nuts/#{number}/#{everything}"
+      end
+    end
+  end
+  
+Add this to nuts.rb and try if you can hit all of the controllers. 
+
+Also notice how everything inside a parenthesis gets passed into the method,
+and is ready at your disposal.
+
+=== Simpler routes
+
+This just in:
+
+  module Nuts::Controllers
+    class Index
+      def get
+        "You got here by: /"
+      end
+    end
+    
+    class WelcomeToMySite
+      def get
+        "You got here by: /welcome/to/my/site"
+      end
+    end
+    
+    class NutsN
+      def get(number)
+        "You got here by: /nuts/#{number}"
+      end
+    end
+    
+    class GorpX
+      def get(everything_else_than_a_slash)
+        "You got here by: /gorp/#{everything_else_than_a_slash}"
+      end
+    end
+    
+    class NutsNX
+      def get(number, everything)
+        "You got here by: /nuts/#{number}/#{everything}"
+      end
+    end
+  end
+  
+Drop the <tt>< R</tt>-part and it attemps to read your mind. It won't always
+succeed, but it can simplify your application once in a while.
+
+== Modeling the world
+
+You can get pretty far with what you've learned now, and hopefully you've been
+playing a bit off-book, but it's time to take the next step: Storing data.
+
+Let's start over again.
+
+  Camping.goes :Nuts
+
+  module Nuts::Models
+    class Page < Base
+    end
+  end
+  
+Obviously, this won't do anything, since we don't have any controllers, but
+let's rather have a look at we _do_ have.
+
+We have a model named Page. This means we now can store wiki pages and
+retrieve them later. In fact, we can have as many models as we want. Need one
+for your users and one for your blog posts? Well, I think you already know how
+to do it.
+
+However, our model is missing something essential: a skeleton.
+  
+  Camping.goes :Nuts
+  
+  module Nuts::Models
+    class Page < Base
+    end
+  
+    class BasicFields < V 1.0
+      def self.up
+        create_table Page.table_name do |t|
+          t.string :title
+          t.text   :content
+          # This gives us created_at and updated_at
+          t.timestamps
+        end
+      end
+  
+      def self.down
+        drop_table Page.table_name
+      end
+    end
+  end
+  
+Now we have our first version of our model. It says:
+
+  If you want to migrate up to version one,
+    create the skeleton for the Page model,
+    which should be able to store,
+      "title" which is a string,
+      "content" which is a larger text,
+      "created_at" which is the time it was created,
+      "updated_at" which is the previous time it was updated.
+    
+  If you want to migrate down from version one,
+    remove the skeleton for the Page model.
+    
+This is called a _migration_. Whenever you want to change or add new models you simply add a new migration below, where you increase the version number. All of these migrations builds upon each other like LEGO blocks.
+
+Now we just need to tell Camping to use our migration. Write this at the bottom of nuts.rb
+
+  def Nuts.create
+    Nuts::Models.create_schema
+  end
+
+When The Camping Server boots up, it will automatically call
+<tt>Nuts.create</tt>. You can put all kind of startup-code here, but right now
+we only want to create our skeleton (or upgrade if needed). Start The Camping
+Server again and observe:
+  
+  $ camping nuts.rb
+  ** Starting Mongrel on 0.0.0.0:3301
+  -- create_table("nuts_schema_infos")
+     -> 0.1035s
+  ==  Nuts::Models::BasicFields: migrating ===================================
+  -- create_table(:nuts_pages)
+     -> 0.0033s
+  ==  Nuts::Models::BasicFields: migrated (0.0038s) ==========================
+  
+Restart it, and enjoy the silence. There's no point of re-creating the
+skeleton this time.
+
+Before we go on, there's one rule you must known: Always place your models
+before your migrations.
+
+== Using our model
+
+Let's explore how our model works by going into the _console_
+
+  $ camping -C nuts.rb
+  ** Starting console
+  >>
+  
+Now it's waiting for your input, and will give you the answer when you press
+Enter. Here's what I did, leaving out the boring answers. You should add your
+own pages.
+
+  >> Page = Nuts::Models::Page
+  
+  >> hiking = Page.new(:title => "Hiking")
+  >> hiking.content = "You can also set the values like this."
+  >> hiking.save
+
+  >> page = Page.find_by_title("Hiking")
+  => #<Nuts::Models::Page id: 1, ... >
+  >> page = Page.find(1)
+  => #<Nuts::Models::Page id: 1, ... >
+  >> page.title
+  >> page.content
+  >> page.created_at
+  >> page.updated_at
+  
+  >> Page.find_by_title("Fishing")
+  => nil
+  
+  ## Page.create automatically saves the page for you.
+  >> Page.create(:title => "Fishing", :content => "Go fish!")
+  
+  >> Page.count
+  => 2
+  
+Now I have two pages: One about hiking and one about fishing.
+
+== Wrapping it up
+
+Wouldn't it be nice if we could show this wonderful our pages in a browser?
+Update nuts.rb so it also contains something like this:
+
+  module Nuts::Controllers
+    class Pages
+      def get
+        # Only fetch the titles of the pages.
+        @pages = Page.all(:select => "title")
+        render :list
+      end
+    end
+    
+    class PageX
+      def get(title)
+        @page = Page.find_by_title(title)
+        render :view
+      end
+    end
+  end
+
+  module Nuts::Views
+    def list
+      h1 "All pages"
+      ul do
+        @pages.each do |page|
+          li do
+            a page.title, :href => R(PageX, page.title)
+          end
+        end
+      end
+    end
+
+    def view
+      h1 @page.title
+      self << @page.content
+    end
+  end
+  
+Here we meet our first _helper_:
+
+  R(PageX, page.title)
+  
+This is the <em>reversed router</em> and it generates a URL based on a
+controller. Camping ships with a few, but very useful, helpers and you can
+easily add your owns. Have a look at Camping::Helpers for how you use these.
+  
+There's a lot of improvements you could do here. Let me suggest:
+
+* Show when the page was created and last updated.
+* What happens when the page doesn't exist?
+* What should the front page show?
+* Add a layout.
+* Jazz it up a bit.
+ 
+== The last touch
+
+We have one major flaw in our little application. You can't edit or add new
+pages. Let's see if we can fix that:
+
+  module Nuts::Controllers
+    class PageX
+      def get(title)
+        if @page = Page.find_by_title(title)
+          render :view
+        else
+          redirect PageXEdit, title
+        end
+      end
+      
+      def post(title)
+        # If it doesn't exist, initialize it:
+        @page = Page.find_or_initialize_by_title(title)
+        # This is the same as:
+        # @page = Page.find_by_title(title) || Page.new(:title => title)
+        
+        @page.content = @input.content
+        @page.save
+        redirect PageX, title
+      end
+    end
+    
+    class PageXEdit
+      def get(title)
+        @page = Page.find_or_initialize_by_title(title)
+        render :edit
+      end
+    end
+  end
+  
+The core of this code lies in the new <tt>post</tt> method in the PageX
+controller. When someone types an address or follows a link, they'll end up at
+the <tt>get</tt> method, but you can easily create a form which rather sends
+you to the <tt>post</tt> when submitted.
+
+There are other names you can use, but they won't always work. So for now,
+don't be fancy and just stick to <tt>get</tt> and <tt>post</tt>. We'll show
+you how this really works later.
+
+You might also notice that we use <tt>@input.content</tt>. The
+<tt>@input</tt>-hash contains any extra parameters sent, like those in the
+forms and those in the URL (<tt>/posts?page=50</tt>).
+
+Here's an <tt>edit</tt>-view, but you can probably do better. See if you can
+integrate all of this with what you already have.
+  
+  module Nuts::Views
+    def edit
+      h1 @page.title
+      form :action => R(PageX, @page.title), :method => :post do
+        textarea @page.content, :name => :content,
+          :rows => 10, :cols => 50
+
+        br
+        
+        input :type => :submit, :value => "Submit!"
+      end
+    end
+  end
+  
+
+== Phew.
+
+You've taken quite a few steps in the last minutes. You deserve a break. But
+let's recap for a moment:
+
+* Always place <tt>Camping.goes :App</tt> at the top of your file.
+* Every route ends at a controller, but ...
+* ... the controller only delegates the work.
+* <tt>@input</tt> contains the extra parameters.
+* The views are HTML disguised as Ruby.
+* They can access the instances variables (those that starts with a single
+  at-sign) from the controller.
+* The models allows you to store all kinds of data.
+* Place your models before your migrations.
+* Helpers are helpful.
+
+Unfortunately, the book stops here for now. Come back in a few months, or join
+the mailing list to stay updated, and hopefully there's another chapter
+waiting for you.
+