radius 0.0.2 → 0.5.0

data/CHANGELOG

@@ -1,5 +1,17 @@
 = Change Log
 
+=== 0.5.0
+* Created a DSL for tag definitions (introducing a DSL makes this version of Radiant incompatible with
+  the last). The DSL has the following features:
+  - full support for nested tags
+  - global and local tag variables
+  - Contexts can now be defined dynamically (instead of being subclassed)
+  - see the QUICKSTART for more info
+* Many refactorings of the library and unit tests.
+* Changed the license to the MIT-LICENSE.
+* Updated documentation to reflect the changes.
+* Updated the version number to reflect the maturity of the code base.
+
 === 0.0.2
 * Refactored Parser to use Context#render_tag instead of #send when rendering tags defined on a Context.
 * UndefinedTagError is now thrown when Parser tries to render a tag which doesn't exist on a Context.

data/QUICKSTART

@@ -1,21 +1,21 @@
 = Radius Quick Start
 
+
 == Defining Tags
 
 Before you can parse a template with Radius you need to create a Context object which defines
-the tags that will be used in the template. This is pretty simple:
+the tags that will be used in the template. This is actually quite simple:
 
   require 'radius'
   
-  class MyContext < Radius::Context
-    def hello(attr)
-      "Hello #{attr['name'] || 'World'}!"
-    end
+  context = Context.new
+  context.define_tag "hello" do |tag|
+    "Hello #{tag.attr['name'] || 'World'}!"
   end
 
-Once you have defined a context you can create a Parser and parse to your heart's content:
+Once you have defined a context you can easily create a Parser:
 
-  parser = Radius::Parser.new(MyContext.new)
+  parser = Radius::Parser.new(context)
   puts parser.parse('<p><radius:hello /></p>')
   puts parser.parse('<p><radius:hello name="John" /></p>')
 
@@ -24,12 +24,12 @@ This code will output:
   <p>Hello World!</p>
   <p>Hello John!</p>
 
-Note how you can pass attributes from the template to the context using the attributes hash
-(which is passed in as the first parameter). Above, the first tag that was parsed didn't have
-a name attribute so the code in the +hello+ method uses "World" instead. The second time the
-tag is parsed the name attribute is set to "John" which is used to create the string "Hello
-John!". <b>All tag definitions must accept only one parameter--the attributes hash.</b> Tags
-that do not follow this rule will be treated as if they were undefined (like normal methods).
+Note how you can pass attributes from the template to the context using the attributes hash.
+Above, the first tag that was parsed didn't have a name attribute so the code in the +hello+
+tag definition uses "World" instead. The second time the tag is parsed the name attribute is
+set to "John" which is used to create the string "Hello John!". Tags that do not follow this
+rule will be treated as if they were undefined (like normal methods).
+
 
 == Container Tags
 
@@ -39,13 +39,14 @@ you could define another tag to parse and create Textile output:
 
   require 'redcloth'
   
-  class MyContext < Radius::Context
-    def textile(attr)
-      contents = yield
-      RedCloth.new(contents).to_html
-    end
+  context.define_tag "textile" do |tag|
+    contents = tag.expand
+    RedCloth.new(contents).to_html
   end
 
+(The code <tt>tag.expand</tt> above returns the contents of the template between the start and end
+tags.)
+
 With the code above your parser can easily handle Textile:
 
   parser.parse('<radius:textile>h1. Hello **World**!</radius:textile>')
@@ -54,24 +55,28 @@ This code will output:
 
   <h1>Hello <strong>World</strong>!</h1>
 
+
+== Nested Tags
+
 But wait!--it gets better. Because container tags can manipulate the content they contain
 you can use them to iterate over collections:
 
-  class ThreeStoogesContext < Radius::Context
-    def stooge(attr)
-      content = ''
-      ["Larry", "Moe", "Curly"].each do |name|
-        @name = name
-        content << yield
-      end
-      content
-    end
-    def name(attr)
-      @name
+  context = Context.new
+  
+  context.define_tag "stooge" do |tag|
+    content = ''
+    ["Larry", "Moe", "Curly"].each do |name|
+      tag.locals.name = name
+      content << tag.expand
     end
+    content
+  end
+  
+  context.define_tag "stooge:name" do
+    tag.locals.name
   end
   
-  parser = Radius::Parser.new(ThreeStoogesContext.new)
+  parser = Radius::Parser.new(context)
   
   template = <<-TEMPLATE
   <ul>
@@ -95,42 +100,224 @@ This code will output:
   
   </ul>
 
+Note how the definition for the +name+ tag is defined. Because "name" is prefixed
+with "stooge:" the +name+ tag cannot appear outside the +stooge+ tag. Had it been defined
+simply as "name" it would be valid anywhere, even outside the +stooge+ tag (which was
+not what we wanted). Using the colon operator you can define tags with any amount of
+nesting.
+
+
+== Exposing Objects to Templates
+
+During normal operation, you will often want to expose certain objects to your templates.
+Writing the tags to do this all by hand would be cumbersome of Radius did not provide
+several mechanisms to make this easier. The first is a way of exposing objects as tags
+on the context object. To expose an object simply call the +define_tag+
+method with the +for+ option:
+
+  context.define_tag "count", :for => 1
+
+This would expose the object <tt>1</tt> to the template as the +count+ tag. It's basically the
+equivalent of writing:
+
+  context.define_tag("count") { 1 }
+
+So far this doesn't save you a whole lot of typing, but suppose you want to expose certain
+methods that are on that object? You could do this:
+
+  context.define_tag "user", :for => user, :expose => [ :name, :age, :email ]
+  
+This will add a total of four tags to the context. One for the <tt>user</tt> variable, and
+one for each of the three methods listed in the +expose+ clause. You could now get the user's
+name inside your template like this:
+
+  <radius:user><radius:name /></radius:user>
 
-== Altering the Tag Prefix
+If "John" was the value stored in <tt>user.name</tt> the template would render as "John".
+
+
+== Tag Shorthand
+
+In the example above we made reference to <tt>user.name</tt> in our template by using the
+following code:
+
+  <radius:user><radius:name /></radius:user>
+  
+There is a much easer way to refer to the <tt>user.name</tt> variable. Use the colon operator
+to "scope" the reference to <tt>name</tt>:
+
+  <radius:user:name />
+
+Radius allows you to use this shortcut for all tags.
+  
+
+== Changing the Tag Prefix
 
 By default, all Radius tags must begin with "radius". You can change this by altering the
-prefix attribute on a Context. For example:
+tag_prefix attribute on a Parser. For example:
 
-  class MyContext < Radius::Context
-    def initialize
-      @prefix = 'r'
-    end
-  end
+  parser = Radius::Parser.new(context, :tag_prefix => 'r')
 
-Now, when parsing templates with MyContext, Radius will require that tags begin with "r".
+Now, when parsing templates with +parser+, Radius will require that every tag begin with "r"
+instead of "radius".
 
 
-== Using Context#tag_missing to Define Behavior for Missing Tags
+== Custom Behavior for Undefined Tags
 
 Context#tag_missing behaves much like Object#method_missing only it allows you to define
 specific behavior for when a tag is not defined on a Context. For example:
 
   class LazyContext < Radius::Context
-    def initialize
-      @prefix = 'lazy'
-    end
     def tag_missing(tag, attr, &block)
       "<strong>ERROR: Undefined tag `#{tag}' with attributes #{attr.inspect}</strong>"
     end
   end
   
-  parser = Radius::Parser.new(LazyContext.new)
+  parser = Radius::Parser.new(LazyContext.new, :tag_prefix => 'lazy')
   puts parser.parse('<lazy:weird value="true" />')
 
-This code will output:
+This will output:
 
   <strong>ERROR: Undefined tag `weird' with attributes {"value"=>"true"}</strong>
 
 Normally, when the Radius Parser encounters an undefined tag for a Context it raises an
 UndefinedTagError, but since we have defined #tag_missing on LazyContext the Parser now
-outputs our custom message.
+outputs a nicely formated error message when we parse a string that does not contain a
+valid tag.
+
+
+== Tag Bindings
+
+Radius passes a TagBinding into the block of the Context#define_tag method. The tag
+binding is useful for a number of tasks. A tag binding has an #expand instance method
+which processes a tag's contents and returns the result. It also has a #attr method
+which returns a hash of the attributes that were passed into the tag. TagBinding also
+contains the TagBinding#single? and TagBinding#double? methods which return true or false
+based on wether the tag is a container tag or not. More about the methods which are
+available on tag bindings can be found on the Radius::TagBinding documentation page.
+
+
+== Tag Binding Locals, Globals, and Context Sensitive Tags
+
+A TagBinding also contains two OpenStruct-like objects which are useful when developing
+tags. TagBinding#globals is useful for storing variables which you would like to be
+accessible to all tags:
+
+  context.define_tag "inc" do |tag|
+    tag.globals.count ||= 0
+    tag.globals.count += 1
+  end
+  
+  context.define_tag "count" do |tag|
+    tag.globals.count || 0
+  end
+
+TagBinding#locals mirrors the variables that are in TagBinding#globals, but allows child
+tags to redefine variables. This is valuable when defining context sensitive tags:
+
+  require 'radius'
+
+  class Person
+    attr_accessor :name, :friend
+    def initialize(name)
+      @name = name
+    end
+  end
+
+  jack = Person.new('Jack')
+  jill = Person.new('Jill')
+  jack.friend = jill
+  jill.friend = jack
+
+  context = Radius::Context.new do |c|
+    c.define_tag "jack" do |tag|
+      tag.locals.person = jack
+      tag.expand
+    end
+    c.define_tag "jill" do |tag|
+      tag.locals.person = jill
+      tag.expand
+    end
+    c.define_tag "name" do |tag|
+      tag.locals.person.name rescue tag.missing!
+    end
+    c.define_tag "friend" do |tag|
+      tag.locals.person = tag.locals.person.friend rescue tag.missing!
+      tag.expand
+    end
+  end
+  
+  parser = Radius::Parser.new(context, :tag_prefix => 'r')
+  
+  parser.parse('<r:jack:name />') #=> "Jack"
+  parser.parse('<r:jill:name />') #=> "Jill"
+  parser.parse('<r:jill:friend:name />') #=> "Jack"
+  parser.parse('<r:jill:friend:friend:name />') #=> "Jack"
+  parser.parse('<r:jill><r:friend:name /> and <r:name /></r:jill>') #=> "Jack and Jill"
+  parser.parse('<r:name />') # raises an UndefinedTagError exception
+
+Notice how TagBinding#locals enables intelligent nesting. "<r:jill:name />" evaluates to
+"Jill", but "<r:jill:friend:name />" evaluates to "Jack". Locals loose scope as soon as
+the tag they were defined in closes. Globals on the other hand, never loose scope.
+
+The final line in the example above demonstrates that calling "<r:name />" raises a
+TagMissing error. This is because of the way the name tag was defined:
+
+  tag.locals.person.name rescue tag.missing!
+  
+If person is not defined on locals it will return nil. Calling #name on nil would normally
+raise a NoMethodError exception, but because of the 'rescue' clause the TagBinding#missing!
+method is called which fires off Context#tag_missing. By default Context#tag_missing raises
+a UndefinedTagError exception. The 'rescue tag.missing!' idiom is extremly useful for adding
+simple error checking to context sensitive tags.
+
+
+== Tag Specificity
+
+When Radius is presented with two tags that have the same name, but different nesting
+Radius uses an algorithm similar to the way winning rules are calculated in Cascading Style
+Sheets (CSS) to determine which definition should be used. Each time a tag is encountered
+in a template potential tags are assigned specificity values and the tag with the highest
+specificity wins.
+
+For example, given the following tag definitions:
+
+  nesting
+  extra:nesting
+  parent:child:nesting
+
+And template:
+
+  <r:parent:extra:child:nesting />
+
+Radius will calculate specificity values like this:
+
+  nesting => 1.0.0.0
+  extra:nesting => 1.0.1.0
+  parent:child:nesting => 1.1.0.1
+
+Meaning that parent:child:nesting will win. If a template contained:
+
+  <r:parent:child:extra:nesting />
+
+The following specificity values would be assigned to each of the tag definitions:
+
+  nesting => 1.0.0.0
+  extra:nesting => 1.1.0.0
+  parent:child:nesting => 1.0.1.1
+
+Meaning that extra:nesting would win because it is more "specific".
+
+Values are assigned by assigning points to each of the tags from right to left.
+Given a tag found in a template with nesting four levels deep, the maximum
+specificity a tag could be assigned would be:
+
+  1.1.1.1
+
+One point for each of the levels.
+
+A deep understanding of tag specificity is not necessary to be effective with
+Radius. For the most part you will find that Radius resolves tags precisely the
+way that you would expect. If you find this section confusing forget about it and
+refer back to it if you find that tags are resolving differently from the way that
+you expected.

data/README

@@ -1,10 +1,48 @@
 = Radius -- Powerful Tag-Based Templates
 
-Radius is a small, but powerful template language for Ruby inspired by the template languages
-used in MovableType <http://www.movabletype.org> and TextPattern <http://www.textpattern.com>.
-It uses tags similar to HTML, but can be used to generate any form of plain text (XML, e-mail,
+Radius is a powerful tag-based template language for Ruby inspired by the template languages
+used in MovableType[http://www.movabletype.org] and TextPattern[http://www.textpattern.com].
+It uses tags similar to XML, but can be used to generate any form of plain text (HTML, e-mail,
 etc...).
 
+== Example
+
+With Radius, it is extremely easy to create custom tags and parse them. Here's a small
+example:
+
+  require 'radius'
+
+  # Define tags on a context that will be available to a template:
+  context = Radius::Context.new do |c|
+    c.define_tag 'hello' do
+      'Hello world'
+    end
+    c.define_tag 'repeat' do |tag|
+      number = (tag.attr['times'] || '1').to_i
+      result = ''
+      number.times { result << tag.expand }
+      result
+    end
+  end
+  
+  # Create a parser to parse tags that begin with 'r:'
+  parser = Radius::Parser.new(context, :tag_prefix => 'r')
+  
+  # Parse tags and output the result
+  puts parser.parse(%{A small example:\n<r:repeat times="3">* <r:hello />!\n</r:repeat>})
+  
+Output:
+
+  A small example:
+  * Hello world!
+  * Hello world!
+  * Hello world!
+
+
+= Quick Start
+
+Read the QUICKSTART[link:files/QUICKSTART.html] to get up and running fast with Radius.
+
 
 == Download
 
@@ -21,28 +59,36 @@ It is recommended that you install Radius using the RubyGems packaging system:
 
 You can also install Radius by copying lib/radius.rb into the Ruby load path.
 
-== License
 
-Radius is free software and may be redistributed under the same terms and Ruby itself. For
-more details, see the readme file in the Ruby distribution.
+== License
 
+Radius is free software and may be redistributed under the terms of the MIT-LICENSE:
 
-== Quick Start
+Copyright (c) 2006, John W. Long
 
-To get up and running fast with Radius read:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so, subject to the following conditions:
 
-link:files/QUICKSTART.html
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
 
-== A Call to Action
 
-Radius is still very much in the development stages. Take a look at the roadmap to see where
-we want to go:
+== The Future
 
-link:files/ROADMAP.html
+Radius is nearing completion, but is still very much in the development stages. Take a look
+at the ROADMAP[link:files/ROADMAP.html] to see where we want to go.
 
-If you are a smart developer with a passion for excellence, now is the time to jump on board.
-Contact me and we'll talk. :)
+If you are interested in helping with the development of Radiant, contact me and we'll talk.
 
 Enjoy!