radius 0.0.1 → 0.0.2

data/CHANGELOG

@@ -0,0 +1,9 @@
+= Change Log
+
+=== 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.
+* Added Context#tag_missing which works like method_method missing on Object, but is tag specific.
+
+=== 0.0.1
+* First release.

data/QUICKSTART

@@ -1,4 +1,6 @@
-=Quick Start
+= 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:
@@ -17,16 +19,19 @@ Once you have defined a context you can create a Parser and parse to your heart'
   puts parser.parse('<p><radius:hello /></p>')
   puts parser.parse('<p><radius:hello name="John" /></p>')
 
-This will output:
+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
+(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!".
+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).
+
+== Container Tags
 
 Radius also allows you to define "container" tags. That is, tags that contain content and
 that may optionally manipulate it in some way. For example, if you have RedCloth installed
@@ -45,17 +50,14 @@ With the code above your parser can easily handle Textile:
 
   parser.parse('<radius:textile>h1. Hello **World**!</radius:textile>')
 
-This will output:
+This code will output:
 
   <h1>Hello <strong>World</strong>!</h1>
 
-But wait!--it gets better. Because container tags can manipulate what they contain you can use
-them to iterate over collections:
+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 initialize
-      @prefix = 'ts'
-    end
     def stooge(attr)
       content = ''
       ["Larry", "Moe", "Curly"].each do |name|
@@ -73,15 +75,15 @@ them to iterate over collections:
   
   template = <<-TEMPLATE
   <ul>
-  <ts:stooge>
-  <li><ts:name /></li>
-  </ts:stooge>
+  <radius:stooge>
+    <li><radius:name /></li>
+  </radius:stooge>
   </ul>
   TEMPLATE
   
   puts parser.parse(template)
   
-This will output:
+This code will output:
 
   <ul>
   
@@ -93,6 +95,42 @@ This will output:
   
   </ul>
 
-The above code also illustrates how you can set the prefix instance variable to control the
-string that prefixes Radius tags. By setting the prefix to "ts" our tags must begin with "ts"
-instead of "radius" like they did in the other examples.
+
+== Altering 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:
+
+  class MyContext < Radius::Context
+    def initialize
+      @prefix = 'r'
+    end
+  end
+
+Now, when parsing templates with MyContext, Radius will require that tags begin with "r".
+
+
+== Using Context#tag_missing to Define Behavior for Missing 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)
+  puts parser.parse('<lazy:weird value="true" />')
+
+This code 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.

data/README

@@ -19,7 +19,7 @@ It is recommended that you install Radius using the RubyGems packaging system:
 
   % gem install --remote radius
 
-You can also install Radius by copying radius.rb into the Ruby load path.
+You can also install Radius by copying lib/radius.rb into the Ruby load path.
 
 == License
 
@@ -44,6 +44,8 @@ link:files/ROADMAP.html
 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. :)
 
---
+Enjoy!
 
-John Long :: http://wiseheartdesign.com
+--
+John Long ::
+http://wiseheartdesign.com

data/ROADMAP

@@ -13,6 +13,6 @@ This is a prioritized roadmap for future releases:
    http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/127640/
 
    Update: See link:files/DSL-SPEC.html for a fuller explanation of how
-   the DSL should behave.
+   the DSL might behave.
 
 4. Optimize for speed. Incorporate strscan?

data/Rakefile

@@ -9,30 +9,35 @@ Rake::TestTask.new do |t|
   t.pattern = 'test/**/*_test.rb'
 end
 
+RDOC_TITLE = "Radius -- Powerful Tag-Based Templates"
+RDOC_EXTRAS = ["README", "QUICKSTART", "ROADMAP", "DSL-SPEC", "CHANGELOG"]
+
 Rake::RDocTask.new do |rd|
   rd.title = 'Radius -- Powerful Tag-Based Templates'
-  rd.main = "README"
-  rd.rdoc_files.include("README", "QUICKSTART", "ROADMAP", "DSL-SPEC", "lib/**/*.rb")
+  rd.main = "Radius"
+  rd.rdoc_files.include("lib/**/*.rb")
+  rd.rdoc_files.include(RDOC_EXTRAS)
   rd.rdoc_dir = 'doc'
 end
 
 spec = Gem::Specification.new do |s|
-  s.platform = Gem::Platform::RUBY
-  s.summary = "Powerful tag-based template system."
   s.name = 'radius'
-  s.version = '0.0.1'
+  s.rubyforge_project = 'radius'
+  s.version = '0.0.2'
+  s.summary = 'Powerful tag-based template system.'
+  s.description = "Radius is a small, but powerful tag-based template language for Ruby\nsimilar to the ones used in MovableType and TextPattern. It has tags\nsimilar to HTML or XML, but can be used to generate any form of plain\ntext (not just HTML)."
+  s.homepage = 'http://radius.rubyforge.org'
+  s.platform = Gem::Platform::RUBY
   s.requirements << 'none'
   s.require_path = 'lib'
   s.autorequire = 'radius'
   s.has_rdoc = true
-  s.rdoc_options << '--title' << 'Radius -- Powerful Tag-Based Templates' <<
-                    '--main' << 'README' <<
-                    '--line-numbers' << 'ROADMAP' <<
-                    'QUICKSTART' << 'DSL-SPEC' << 'README'
+  s.rdoc_options << '--title' << RDOC_TITLE << '--line-numbers' << '--main' << 'README'
+  s.extra_rdoc_files = RDOC_EXTRAS
   files = FileList['**/*']
   files.exclude 'doc'
+  files.exclude '**/._*'
   s.files = files.to_a
-  s.description = "Radius is a small, but powerful tag-based template language inspired\nby the template languages used in MovableType and TextPattern."
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|

data/lib/radius.rb

@@ -1,13 +1,25 @@
 module Radius
-  class ParseError < StandardError # :nodoc:
+  # Abstract base class for all parsing errors.
+  class ParseError < StandardError
   end
   
-  class MissingEndTagError < ParseError # :nodoc:
+  # Occurs when Parser cannot find an end tag for a given tag in a template or when
+  # tags are miss-matched in a template.
+  class MissingEndTagError < ParseError
+    # Create a new MissingEndTagError object for +tag_name+. 
     def initialize(tag_name)
       super("end tag not found for start tag `#{tag_name}'")
     end
   end
   
+  # Occurs when Context#render_tag cannot find the specified tag on a Context.
+  class UndefinedTagError < ParseError
+    # Create a new MissingEndTagError object for +tag_name+. 
+    def initialize(tag_name)
+      super("undefined tag `#{tag_name}'")
+    end
+  end
+  
   #
   # An abstract class for creating a Context. A context defines the tags that
   # are available for use in a template.
@@ -15,22 +27,41 @@ module Radius
   class Context
     # The prefix attribute controls the string of text that is helps the parser
     # identify template tags. By default this attribute is set to "radius", but
-    # you may want to override this for your own contexts.
+    # you may want to override this when creating your own contexts.
     attr_accessor :prefix
     
     # Creates a new Context object.
     def initialize
       @prefix = 'radius'
     end
+    
+    # Returns the value of a rendered tag. Used internally by Parser#parse.
+    def render_tag(tag, attributes = {}, &block)
+      symbol = tag.to_s.intern
+      if respond_to?(symbol) and method(symbol).arity == 1
+        send(symbol, attributes, &block)
+      else
+        tag_missing(tag, attributes, &block)
+      end
+    end
+    
+    # Like method_missing for objects, but fired when a tag is undefined.
+    # Override in your own Context to change what happens when a tag is
+    # undefined. By default this method raises an UndefinedTagError.
+    def tag_missing(tag, attributes, &block)
+      raise UndefinedTagError.new(tag)
+    end
   end
   
   class Tag # :nodoc:
     def initialize(&b)
       @block = b
     end
+      
     def on_parse(&b)
       @block = b
     end
+    
     def to_s
       @block.call(self)
     end
@@ -53,7 +84,7 @@ module Radius
     # The Context object used to expand template tags.
     attr_accessor :context
     
-    # Creates a new parser object initialized with a context.
+    # Creates a new parser object initialized with a Context.
     def initialize(context = Context.new)
       @context = context
     end
@@ -93,7 +124,7 @@ module Radius
     def parse_end_tag(end_tag, remaining) # :nodoc:
       popped = @stack.pop
       if popped.name == end_tag
-        popped.on_parse { |t| @context.send(popped.name, popped.attributes) { t.contents.to_s } }
+        popped.on_parse { |t| @context.render_tag(popped.name, popped.attributes) { t.contents.to_s } }
         tag = @stack.last
         tag.contents << popped
         pre_parse(remaining)
@@ -106,7 +137,7 @@ module Radius
       re = /<#{@context.prefix}:(\w+?)\s+?(.*?)\s*?\/>/
       if md = re.match(text)
         attr = parse_attributes($2)
-        replace = @context.send($1, attr)
+        replace = @context.render_tag($1, attr)
         md.pre_match + replace + parse_individual(md.post_match)
       else
         text || ''

data/test/radius_test.rb

@@ -1,68 +1,115 @@
 require 'test/unit'
 require 'radius'
 
-class ContextTest < Test::Unit::TestCase
-  def test_initialize
-    c = Radius::Context.new
-    assert_equal 'radius', c.prefix
+class TestContext < Radius::Context
+  def initialize
+    @prefix = "test"
+    @items = ["Larry", "Moe", "Curly"]
+  end
+  
+  def echo(attr)
+    attr["text"]
+  end
+  
+  def add(attr)
+    (attr["param1"].to_i + attr["param2"].to_i).to_s
+  end
+  
+  def reverse(attr)
+    yield.reverse
+  end
+  
+  def capitalize(attr)
+    yield.upcase
+  end
+  
+  def count(attr)
+    case
+    when attr["set"]
+      @count = attr["set"].to_i
+      ""
+    when attr["inc"] == "true"
+      @count = (@count || 0) + 1
+      ""
+    else
+      @count.to_s       
+    end
+  end
+  
+  def repeat(attr)
+    string = ''
+    (attr['count'] || '1').to_i.times { string << yield }
+    string
+  end
+  
+  def each_item(attr)
+    result = []
+    @items.each { |@item| result << yield }
+    @item = nil
+    result.join(attr["between"] || "")
+  end
+  
+  def item(attr)
+    @item
+  end
+  
+  def hello(attr)
+    "Hello #{attr['name'] || 'World'}!"
   end
 end
 
-class RadiusTest < Test::Unit::TestCase
-  class TestContext < Radius::Context
-    def initialize
-      @prefix = "test"
-      @items = ["Larry", "Moe", "Curly"]
-    end
-    
-    def echo(attr)
-      attr["text"]
-    end
-    
-    def add(attr)
-      (attr["param1"].to_i + attr["param2"].to_i).to_s
-    end
-    
-    def reverse(attr)
-      yield.reverse
-    end
-    
-    def capitalize(attr)
-      yield.upcase
-    end
-    
-    def count(attr)
-      case
-      when attr["set"]
-        @count = attr["set"].to_i
-        ""
-      when attr["inc"] == "true"
-        @count = (@count || 0) + 1
-        ""
-      else
-        @count.to_s       
+class RadiusContextTest < Test::Unit::TestCase
+  def setup
+    @context = TestContext.new
+  end
+  
+  def test_initialize
+    @context = Radius::Context.new
+    assert_equal 'radius', @context.prefix
+  end
+  
+  def test_render_tag__individual
+    text = @context.render_tag('hello')
+    assert_equal('Hello World!', text)
+
+    text = @context.render_tag('hello', 'name' => 'John')
+    assert_equal('Hello John!', text)
+  end
+  
+  def test_render_tag__container
+    text = @context.render_tag('repeat', 'count' => '5') { 'o' }
+    assert_equal('ooooo', text)
+  end
+  
+  def test_render_tag__undefined_tag
+    e = assert_raises(Radius::UndefinedTagError) { @context.render_tag('undefined_tag') }
+    assert_equal "undefined tag `undefined_tag'", e.message
+  end
+  
+  def test_render_tag__undefined_tag_with_wrong_signature
+    class << @context
+      def helper_method
       end
     end
-    
-    def loop(attr)
-      t = attr["times"].to_i
-      result = ""
-      t.times { result += yield }
-      result
+    assert_raises(Radius::UndefinedTagError) { @context.render_tag('helper_method') }
+  end
+  
+  def test_tag_missing
+    class << @context
+      def tag_missing(tag, attr, &block)
+        "undefined tag `#{tag}' with attributes #{attr.inspect}"
+      end
     end
     
-    def each_item(attr)
-      result = []
-      @items.each { |@item| result << yield }
-      @item = nil
-      result.join(attr["between"] || "")
-    end
+    text = ''
+    assert_nothing_raised { text = @context.render_tag('undefined_tag', 'cool' => 'beans') }
     
-    def item(attr)
-      @item
-    end
+    expected = %{undefined tag `undefined_tag' with attributes {"cool"=>"beans"}}
+    assert_equal expected, text
   end
-  
+end
+
+class RadiusParserTest < Test::Unit::TestCase
   def setup
     @t = Radius::Parser.new(TestContext.new )
   end
@@ -105,8 +152,8 @@ class RadiusTest < Test::Unit::TestCase
     r = @t.parse("<test:reverse>12<test:capitalize>at</test:capitalize>34</test:reverse>")
     assert_equal("43TA21", r)
   end
-  def test_parse__loop
-    r = @t.parse(%{<test:count set="0" /><test:loop times="5"><test:count inc="true" /><test:count /></test:loop>})
+  def test_parse__looping
+    r = @t.parse(%{<test:count set="0" /><test:repeat count="5"><test:count inc="true" /><test:count /></test:repeat>})
     assert_equal("12345", r)
 
     r = @t.parse(%{Three Stooges: <test:each_item between=", ">"<test:item />"</test:each_item>})

metadata

@@ -3,16 +3,17 @@ rubygems_version: 0.8.10
 specification_version: 1
 name: radius
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
-date: 2006-01-21
+  version: 0.0.2
+date: 2006-02-14
 summary: Powerful tag-based template system.
 require_paths: 
   - lib
 email: 
-homepage: 
-rubyforge_project: 
-description: "Radius is a small, but powerful tag-based template language inspired by the
-  template languages used in MovableType and TextPattern."
+homepage: http://radius.rubyforge.org
+rubyforge_project: radius
+description: "Radius is a small, but powerful tag-based template language for Ruby similar to
+  the ones used in MovableType and TextPattern. It has tags similar to HTML or
+  XML, but can be used to generate any form of plain text (not just HTML)."
 autorequire: radius
 default_executable: 
 bindir: bin
@@ -27,6 +28,7 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 authors: []
 files: 
+  - CHANGELOG
   - DSL-SPEC
   - lib
   - QUICKSTART
@@ -40,14 +42,15 @@ test_files: []
 rdoc_options: 
   - "--title"
   - "Radius -- Powerful Tag-Based Templates"
+  - "--line-numbers"
   - "--main"
   - README
-  - "--line-numbers"
-  - ROADMAP
+extra_rdoc_files: 
+  - README
   - QUICKSTART
+  - ROADMAP
   - DSL-SPEC
-  - README
-extra_rdoc_files: []
+  - CHANGELOG
 executables: []
 extensions: []
 requirements: