vanilla 1.14.1 → 1.15

data/Rakefile

@@ -2,7 +2,8 @@ require "rubygems"
 require "rake/gempackagetask"
 require "rake/rdoctask"
 
-load File.join(File.dirname(__FILE__), *%w[lib tasks vanilla.rake])
+require "bundler/setup"
+require "vanilla"
 
 task :default => :test
 
@@ -35,7 +36,7 @@ if Object.const_defined?(:Gem)
     s.rdoc_options      = %w(--main README)
 
     # Add any extra files to include in the gem
-    s.files             = %w(config.example.yml config.ru Rakefile README README_FOR_APP) + Dir.glob("{test,lib,bin,public}/**/*")
+    s.files             = %w(Rakefile README) + Dir.glob("{test,lib,bin,pristine_app}/**/*")
     s.executables       = ['vanilla']
     s.require_paths     = ["lib"]
 

data/bin/vanilla

@@ -1,9 +1,38 @@
 #!/usr/bin/env ruby
-require 'rubygems'
-require 'rake'
-load File.join(File.dirname(__FILE__), *%w[.. lib tasks vanilla.rake])
 
-mkdir(ARGV[0])
-cd(ARGV[0])
+def create(new_app_dir)
+  require 'fileutils'
+  pristine_app = File.expand_path("../../pristine_app", __FILE__)
+  FileUtils.cp_r(pristine_app, new_app_dir)
+  FileUtils.mkdir(File.join(new_app_dir, "tmp"))
+  require 'vanilla'
+  File.open(File.join(new_app_dir, "Gemfile"), "w") do |f|
+    f.write "source :rubygems\n\n# Vanilla itself.\ngem 'vanilla', '#{Vanilla::VERSION}'"
+  end
+  puts File.readlines(File.join(new_app_dir, "README"))[0..16].join
+end
 
-Rake::Task['vanilla:setup'].invoke
+def console
+  $LOAD_PATH << "lib"
+  require "rubygems"
+  require "bundler/setup"
+  require "irb"
+  require "vanilla/console"
+  ARGV.clear
+  puts "The Soup is simmering."
+  IRB.start 
+end
+
+def upgrade
+  # TODO
+  puts "TODO, but should be easier thanks to multi-space soup."
+end
+
+case ARGV[0]
+when "console"
+  console
+when "upgrade"
+  upgrade
+else
+  create(ARGV[0])
+end

data/lib/vanilla/app.rb

@@ -49,7 +49,12 @@ module Vanilla
     def formatted_render(snip, part=nil, format=nil)
       case format
       when 'html', nil
-        render(layout_for(snip))
+        layout = layout_for(snip)
+        if layout == snip
+          "Rendering of the current layout would result in infinite recursion."
+        else
+          render(layout)
+        end
       when 'raw', 'css', 'js'
         Renderers::Raw.new(self).render(snip, part)
       when 'text', 'atom', 'xml'

data/lib/vanilla/console.rb

@@ -1,12 +1,23 @@
 require 'vanilla'
-require 'irb'
+
+module Vanilla
+  class RackShim
+    def run(app)
+      app # return it
+    end
+    def use(*args)
+      # ignore
+    end
+    def get_binding
+      binding
+    end
+  end
+end
 
 def app(reload=false)
   if !@__vanilla_console_app || reload
-    config = YAML.parse_file(ENV['VANILLA_CONFIG']) rescue {}
-    @__vanilla_console_app = Vanilla::App.new(config)
+    shim_binding = Vanilla::RackShim.new.get_binding
+    @__vanilla_console_app = eval File.read("config.ru"), shim_binding
   end
   @__vanilla_console_app
-end
-
-puts "The Soup is simmering."
+end

data/lib/vanilla.rb

@@ -1,5 +1,5 @@
 module Vanilla
-  VERSION = "1.14.1"
+  VERSION = "1.15"
 
   autoload :Renderers, "vanilla/renderers"
   autoload :App, "vanilla/app"

data/pristine_app/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gem 'vanilla', :path => File.expand_path("../..", __FILE__)

data/pristine_app/Gemfile.lock

@@ -0,0 +1,32 @@
+PATH
+  remote: /Users/james/Code/lazyatom/vanilla-rb
+  specs:
+    vanilla (1.15)
+      BlueCloth (>= 1.0.0)
+      RedCloth (>= 4.1.1)
+      haml
+      rack (>= 0.9.1)
+      ratom (>= 0.3.5)
+      soup (>= 1.0.6)
+      treetop (>= 1.4.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    BlueCloth (1.0.1)
+    RedCloth (4.2.7)
+    haml (3.0.25)
+    libxml-ruby (2.0.2)
+    polyglot (0.3.1)
+    rack (1.2.2)
+    ratom (0.6.7)
+      libxml-ruby (>= 1.1.2)
+    soup (1.0.6)
+    treetop (1.4.9)
+      polyglot (>= 0.3.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  vanilla!

data/pristine_app/README

@@ -0,0 +1,36 @@
+                      WELCOME IN VANILLA
+                                 Vanilla
+                                 vanilla
+                                 .........vanillaaaaaAAAAAAAAAAA
+
+What you've got:
+
+  Gemfile    - specifying your dependencies
+  config.ru  - this is the rack configuration, which is used to start
+               the application by your webserver
+  soup/      - the default soup directory, where your snips are stored
+
+
+For an overview of vanilla, start your site and look at the tutorial:
+
+  $ rackup   # then open http://localhost:9292/tutorial
+
+
+You can edit any file in the soup directory using your favourite editor,
+and the changes will be reflected automatically. The snip files are
+slightly modified YAML files. Here's an example, which you might save
+in a file called 'soup.snip':
+
+
+    Soup is a data store supporting the {link_to snip}-space that 
+    {link_to vanilla-rb} expects.
+
+    It's hosted on github [here](http://github.com/lazyatom/soup).
+
+    :created_at: 2011-05-23 14:14:16 +01:00
+    :updated_at: 2009-05-23 15:23:22 +01:00
+    :render_as: Markdown
+
+
+The 'content' of the snip is at the top of the file, followed by the
+rest of the snip attributes on lines starting with ':'.

data/pristine_app/config.ru

@@ -0,0 +1,26 @@
+require 'rubygems'
+require 'bundler/setup'
+$:.unshift File.join(File.dirname(__FILE__), *%w[lib])
+
+require 'vanilla'
+
+# You can partition your snips into subdirectories to keep things tidy. This
+# doesn't affect their URL structure on the site (everything is flat).
+soups = [
+  "soups/base",
+  "soups/dynasnips"
+]
+
+# If you don't want the tutorial on your site, remove this and delete the directory
+soups << "soups/tutorial"
+
+# This is a dumping ground of ideas at the moment
+# soups << "soups/extras"
+
+app = Vanilla::App.new(:soups => soups)
+
+# If you running your site under a proper webserver, you probably don't need this.
+require 'vanilla/static'
+use Vanilla::Static, File.join(File.dirname(__FILE__), 'public')
+
+run app

data/pristine_app/public/vanilla.css

@@ -0,0 +1,15 @@
+#controls {
+  padding-left: 0;
+}
+
+#controls li {
+  background: #eee;
+  display: inline;
+  padding: 0.2em 0.5em;
+}
+
+pre {
+  margin-left: 1em;
+  background-color: #ddd;
+  padding: 1em;
+}

data/pristine_app/soups/base/layout.snip

@@ -0,0 +1,18 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en">
+<head>
+  <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+  <title>{page_title}</title>
+  <link rel="stylesheet" href="/vanilla.css" type="text/css" media="screen" title="no title" charset="utf-8">
+</head>
+<body>
+  <ul id="controls">
+    <li><a href="/">home</a></li>
+    <li>{link_to index}</li>
+    <li>you are viewing: {link_to_current_snip}</li>
+  </ul>
+  <div id="content">
+    {current_snip}
+  </div>
+</body>
+</html>

data/pristine_app/soups/base/start.snip

@@ -0,0 +1,19 @@
+<h1>Welcome to Vanilla.rb</h1>
+
+<p>Vanilla.rb is a web-experiment (a <em>websperiment</em>?) about storing and reusing data on a website. It can also function as a <a href="http://www.wikipedia.com/wiki/Bliki">bliki</a>.</p>
+
+<p>From a technical perspective, vanilla is a Ruby rack application, and should play well within the rack ecosystem. It uses a simple document store called `soup` to store data.</p>
+
+<h2>What now?</h2>
+
+<p>If this is your first time using vanilla, you should investigate the {link_to tutorial} for some orientation.</p>
+
+<h2>What next?</h2>
+
+<p>This is the {link_to start} snip, which is the default home page. You can find this content in `start.snip`.</p>
+
+<p>You should replace this content with whatever you want on your site's home page.</p>
+
+<p>Once your site is ready to run, you'll probably want to remove the tutorial; you can do this by editing the configuration in `config.ru`, and deleting the `soups/tutorial` directory.</p>
+
+<p>Good luck!</p>

data/pristine_app/soups/dynasnips/current_snip.rb

@@ -0,0 +1,29 @@
+require 'vanilla/dynasnip'
+
+class CurrentSnip < Dynasnip
+  usage %|
+    The current_snip dyna normally returns the result of rendering the snip named by the
+    'snip' value in the parameters. This way, it can be used in templates to place the currently
+    requested snip, in its rendered form, within the page.
+
+    It can also be used to determine an attribute of the current snip in a consistent way:
+
+      {current_snip name}
+
+    will output the name of the current snip.
+  |
+
+  def handle(attribute=nil)
+    if attribute
+      app.request.snip.__send__(attribute)
+    else
+      if app.request.snip
+        app.render(app.request.snip, app.request.part)
+      else
+        app.response.status = 404
+        %{Couldn't find snip "#{app.request.snip_name}"}
+      end
+    end
+  end
+  self
+end

data/{lib/vanilla → pristine_app/soups}/dynasnips/debug.rb

@@ -1,13 +1,15 @@
 require 'vanilla/dynasnip'
+require 'cgi'
 
 # If the dynasnip is a subclass of Dynasnip, it has access to the request hash
 # (or whatever - access to some object outside of the snip itself.)
 class Debug < Dynasnip
   def get(*args)
-    app.request.inspect
+    CGI.escapeHTML(app.request.inspect)
   end
-  
+
   def post(*args)
-    "You posted! " + app.request.inspect
+    "You posted! " + CGI.escapeHTML(app.request.inspect)
   end
+  self
 end

data/{lib/vanilla → pristine_app/soups}/dynasnips/index.rb

@@ -7,4 +7,6 @@ class Index < Dynasnip
     }
     "<ol>#{list}</ol>"
   end
+
+  self
 end

data/{lib/vanilla → pristine_app/soups}/dynasnips/link_to.rb

@@ -11,4 +11,6 @@ would insert a link to the blah snip.|
   def handle(snip_name, link_text=snip_name, part=nil)
     link_to(link_text, snip_name, part)
   end
+
+  self
 end

data/pristine_app/soups/dynasnips/link_to_current_snip.rb

@@ -0,0 +1,14 @@
+require 'vanilla/dynasnip'
+
+class LinkToCurrentSnip < Dynasnip
+  usage %|
+    Renders a link to the current snip, or the snip currently being edited
+    (if we're currently editing)
+  |
+
+  def handle(*args)
+    link_to app.request.snip_name
+  end
+
+  self
+end

data/pristine_app/soups/dynasnips/page_title.rb

@@ -0,0 +1,9 @@
+require 'vanilla/dynasnip'
+
+class PageTitle < Dynasnip
+  def handle
+    app.request.snip.page_title || app.request.snip.name
+  end
+
+  self
+end

data/{lib/vanilla → pristine_app/soups}/dynasnips/pre.rb

@@ -5,15 +5,17 @@ class ShowContentInPreTag < Dynasnip
 
   usage %|
     Wraps the contents of the given snip in &lt;pre&gt; tags, e.g.
-    
+
       {pre my_snip}
-      
+
     You can specify a part to render in pre tags, should you wish:
-    
+
       {pre my_snip,specific_part}
   |
-  
+
   def handle(snip_name, part=:content)
     %{<pre>#{app.soup[snip_name].__send__(part || :content)}</pre>}
   end
+
+  self
 end

data/{lib/vanilla → pristine_app/soups}/dynasnips/raw.rb

@@ -1,19 +1,22 @@
 require 'vanilla/dynasnip'
+require 'cgi'
 
 class ShowRawContent < Dynasnip
   snip_name "raw"
 
   usage %|
     Displays the raw contents of a snip in &lt;pre&gt; tags, e.g.
-    
+
       {raw my_snip}
-      
+
     You can specify a part to show, should you wish:
-    
+
       {raw my_snip,specific_part}
   |
-  
+
   def handle(snip_name, part=:content)
-    %{<pre>#{Dynasnip.escape_curly_braces(app.soup[snip_name].__send__(part || :content))}</pre>}
+    %{#{Dynasnip.escape_curly_braces(CGI.escapeHTML(app.soup[snip_name].__send__(part || :content)))}}
   end
+
+  self
 end

data/{lib/vanilla/dynasnips → pristine_app/soups/extras}/comments.rb

@@ -64,7 +64,7 @@ class Comments < Dynasnip
   }
 
   attribute :comment_form, %{
-    <form class="comments" action="/#{snip_name}?snip=SNIP_NAME" method="POST">
+    <form class="comments" action="/comments?snip=SNIP_NAME" method="POST">
       <label>Name: <input type="text" name="author"></input></label>
       <label>Email: <input type="text" name="email"></input></label>
       <label>Website: <input type="text" name="website"></input></label>
@@ -73,4 +73,6 @@ class Comments < Dynasnip
       <button>Submit</button>
     </form>
   }
+
+  self
 end

data/{lib/vanilla/dynasnips → pristine_app/soups/extras}/rand.rb

@@ -24,4 +24,6 @@ class RandomNumber < Dynasnip
     max = max.to_i
     (rand(max-min) + min)
   end
+
+  self
 end

data/{lib/vanilla/snips → pristine_app/soups}/tutorial/soup.snip

@@ -1,5 +1,3 @@
 Soup is a data store supporting the {link_to snip}-space that {link_to vanilla-rb} expects.
 
-It's hosted on github <a href="http://github.com/lazyatom/soup">here</a>.
-
-:render_as: Markdown
+It's hosted on github <a href="http://github.com/lazyatom/soup">here</a>.

data/pristine_app/soups/tutorial/tutorial-dynasnips.snip.markdown

@@ -0,0 +1,56 @@
+{tutorial-links}
+
+Dynasnips
+=========
+
+As mentioned in the general {link_to tutorial}, dynamic content is built in vanilla using "dynasnips". These are snips who content depends on more than just their content.
+
+Typically they are rendered by the `Vanilla::Renderers::Ruby` renderer. Lets look again at the raw content of `link_to`:
+
+    {raw link_to}
+
+As you can see, it simply refers to the Ruby class `LinkTo`, which is contained within the vanilla-rb codebase. When the Ruby renderer is called, expects the given code to evaulate to a Ruby class. It then instantiates the class, and calls a `handle` method on the instance, passing it any other arguments from the snip inclusion.
+
+You can pass arguments to dynasnips in a number of ways. All of the following are valid:
+
+* {dynasnip apple}
+* {dynasnip apple, banana}
+* {dynasnip apple, big banana, cherry}
+* {dynasnip apple, big banana, "lovely lucious cherry"}
+* {dynasnip apple => true, banana => false}
+* {dynasnip apple: true, banana: false}
+
+Where a simple list of arguments is given, these will be passed to the `handle` method as an array. If a ruby-hash-like syntax is used, a hash of these options will be passed.
+
+Of course, it depends entirely on the implementation of the dynasnip what arguments it expects and accepts; some may require a flat list, while others may require hash-like named arguments.
+
+
+Writing your own Dynasnips
+--------------------------
+
+While dynasnip classes can be provided as part of the vanilla codebase, it's envisioned that much of these will be created by end users in their own sites, either by refering to local classes, or defining the classes directly as the content. Here's an example of that, as the raw content of `hello_world`:
+
+    {raw hello_world}
+
+It's important that the contents of the snip evaluate to a Ruby class; this is easy to achieve by placing `self` as the last statement in the class definition, or referencing the class at the end of the snip; both are shown above.
+
+If we include the dynasnip here as <tt>&#123;hello\_world&#125;</tt>, gives:
+
+> {hello_world}
+
+Note that the `handle` method can take one (optional) argument. Lets try including it with <tt>&#123;hello\_world Dave&#125;</tt>:
+
+> {hello_world Dave}
+
+
+HTTP Verbs
+----------
+
+By default, the Ruby renderer will attempt to call `handle` on a dynasnip instance, but if the instance responds to methods corresponding to the HTTP Verbs - `get`, `post`, `put`, or `delete` - then these methods will be called instead.
+
+This means you can have a single dynasnip which responds differently when receiving a `POST` request - quite useful if you want to write dynasnips that generate and respond to forms, like the `comments` dynasnip in your `extras` soup directory.
+
+There's really no limit to what you can do with dynasnips - only what you can imagine.
+
+
+{tutorial-links}

data/pristine_app/soups/tutorial/tutorial-layout.snip

@@ -0,0 +1,56 @@
+{tutorial-links}
+
+Layouts
+=======
+
+Since you almost certainly want your site to look good, one of the first things you'll want to change in your vanilla site is the layout.
+
+When the browser requests a snip, normally vanilla will present it within a _layout_ template. This would typically include a header, a footer, and any other peripheral markup that shouldn't be within the content of the snip itself. If you're familiar with the construction of web applications, this will be exactly as you expect.
+
+Layouts are just like any other snip - they can be sent through a renderer, and include other snips. The default layout snip is called, predictable, `layout.snip`, and here's the content:
+
+    {raw layout}
+
+When you request `/start`, this is the snip that's actually rendered first. If this snip was just text, that's all that would be returned; however, there are some dynasnip calls in here which help us actually return the content that the user requested.
+
+
+`current_snip`
+--------------
+
+The most significant is the call to `current_snip`. This figures out what snip was actually requested (e.g. if the url is `/start`, it's the {link_to start} snip), and renders it in place.
+
+Here's the source of `current_snip`:
+
+    {raw current_snip}
+
+The default case, as in our layout, is `app.render(app.request.snip, app.request.part)` - it delegates rendering back to the application, which then takes care of processing `start` using the right renderer and so on. This method call returns the fully rendered string, and vanilla replaces the call to the dynasnip with that output, placing our snip in the appropriate place in the layout.
+
+
+Other dynas
+-----------
+
+Of course, you can put other plain content in your layout, and other dynasnips too. In the provided layout there are calls to two other dynasnips.
+
+The first is `page_title`, which simply places a (hopefully) meaningful string in the title element of the page. Snips can set the title to be used by defining a `:page_title` attribute. As usual, the source explains it more clearly:
+
+    {raw page_title}
+
+The second dynasnip used is `link_to_current_snip`, which returns an HTML link to the snip that's currently being rendered. I'll let you figure out how to view the source yourself.
+
+
+Other layouts
+-------------
+
+Vanilla looks for a snip called `layout` by default, but this can be changed by passing in a `:default_layout` option to `Vanilla::App.new`, e.g.
+
+    Vanilla::App.new(:default_layout => "my_layout")
+
+
+You can also override the layout on a per-snip basis, simply by setting the `:layout` attribute of the snip to the name of the layout snip to use instead.
+
+Finally, if you implement a custom renderer class (see {link_to tutorial-renderers, "the renderers tutorial"}), you can also specify a layout to be used when the requested snip invokes that renderer. This can be useful if you have a particular kind of content that requires a different layout entirely.
+
+{tutorial-links}
+
+:render_as: Markdown
+:page_title: Tutorial - Layout

data/pristine_app/soups/tutorial/tutorial-links.snip

@@ -0,0 +1,4 @@
+{link_to tutorial}
+{link_to tutorial-layout}
+{link_to tutorial-renderers}
+{link_to tutorial-dynasnips}