radius-ts 1.0.0

data/CHANGELOG

@@ -0,0 +1,37 @@
+= Change Log
+=== 1.0.0-ts
+* Create a fork that is threadsafe (per-parser).
+* Bump revision to 1.0.0 since the API is stable
+
+=== 0.6.1
+* Fixed a problem with non-tags that have no prefix or tagname (see test_parse_chirpy_bird)
+
+=== 0.6.0 (private release)
+* Split radius.rb into multiple files.
+* Port the really hairy regexes from Radius::Parser to a single Ragel machine.
+* Added and refactored tests.
+* Refactored Rakefile and other administrativia.
+
+=== 0.5.1
+* Fixed a problem with parsing quotes where a single tag preceding a double tag would consume the start
+  tag of the double tag if both contained attributes.
+
+=== 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.
+* Added Context#tag_missing which works like method_method missing on Object, but is tag specific.
+
+=== 0.0.1
+* First release.

data/Manifest.txt

@@ -0,0 +1,21 @@
+CHANGELOG
+Manifest.txt
+QUICKSTART.rdoc
+README.rdoc
+Rakefile
+lib/radius.rb
+lib/radius/context.rb
+lib/radius/delegating_open_struct.rb
+lib/radius/error.rb
+lib/radius/parse_tag.rb
+lib/radius/parser.rb
+lib/radius/parser/scan.rb
+lib/radius/parser/scan.rl
+lib/radius/tag_binding.rb
+lib/radius/tag_definitions.rb
+lib/radius/utility.rb
+lib/radius/version.rb
+tasks/scan.rake
+test/context_test.rb
+test/parser_test.rb
+test/test_helper.rb

data/QUICKSTART.rdoc

@@ -0,0 +1,322 @@
+= 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 actually quite simple:
+
+  require 'radius'
+  
+  context = Radius::Context.new
+  context.define_tag "hello" do |tag|
+    "Hello #{tag.attr['name'] || 'World'}!"
+  end
+
+Once you have defined a context you can easily create a Parser:
+
+  parser = Radius::Parser.new(context)
+  puts parser.parse('<p><radius:hello /></p>')
+  puts parser.parse('<p><radius:hello name="John" /></p>')
+
+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.
+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
+
+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
+you could define another tag to parse and create Textile output:
+
+  require 'redcloth'
+  
+  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>')
+
+This code will output:
+
+  <h1>Hello <b>World</b>!</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:
+
+  context = Radius::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|
+    tag.locals.name
+  end
+  
+  parser = Radius::Parser.new(context)
+  
+  template = <<-TEMPLATE
+  <ul>
+  <radius:stooge>
+    <li><radius:name /></li>
+  </radius:stooge>
+  </ul>
+  TEMPLATE
+  
+  puts parser.parse(template)
+  
+This code will output:
+
+  <ul>
+  
+    <li>Larry</li>
+  
+    <li>Moe</li>
+  
+    <li>Curly</li>
+  
+  </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>
+
+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
+tag_prefix attribute on a Parser. For example:
+
+  parser = Radius::Parser.new(context, :tag_prefix => 'r')
+
+Now, when parsing templates with +parser+, Radius will require that every tag begin with "r"
+instead of "radius".
+
+
+== 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 tag_missing(tag, attr, &block)
+      "<strong>ERROR: Undefined tag `#{tag}' with attributes #{attr.inspect}</strong>"
+    end
+  end
+  
+  parser = Radius::Parser.new(LazyContext.new, :tag_prefix => 'lazy')
+  puts parser.parse('<lazy:weird value="true" />')
+
+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 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:
+
+  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:jack:friend:friend:name />') #=> "Jack"
+  parser.parse('<r:jill><r:friend:name /> and <r:name /></r:jill>') #=> "Jack and Jill"
+  parser.parse('<r:name />') # raises a Radius::UndefinedTagError exception
+
+Notice how TagBinding#locals enables intelligent nesting. "<r:jill:name />" evaluates to
+"Jill", but "<r:jill:friend:name />" evaluates to "Jack". Locals lose scope as soon as
+the tag they were defined in closes. Globals on the other hand, never lose 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.
+
+In practice, you don't need to understand this topic 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.rdoc

@@ -0,0 +1,118 @@
+= Radius -- Powerful Tag-Based Templates
+
+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...).
+
+== Usage
+
+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 file to get up and running with Radius.
+
+
+= Requirements
+ 
+Radius does not have any external requirements for using the library in your
+own programs.
+ 
+Ragel is required to create the ruby parser from the Ragel specification,
+and both Ragel and Graphviz are required to draw the state graph for the
+parser.
+
+
+== Installation
+
+It is recommended that you install Radius using the RubyGems packaging system:
+
+  % gem install --remote radius
+
+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 terms of the MIT-LICENSE:
+
+Copyright (c) 2006-2009, John W. Long
+
+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:
+
+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.
+
+
+== Roadmap
+
+This is a prioritized roadmap for future releases:
+
+1. Clean up the current code base. [Done]
+
+2. Add support for multi-level contexts: tags should be able to be
+   defined to only be valid within other sets of tags. [Done]
+
+3. Create a simple DSL for defining contexts. [Done]
+
+4. Optimize for speed, modify scan.rl to emit C.
+
+
+== Development
+
+The latest version of Radius can be found on RubyForge:
+
+http://rubyforge.org/projects/radius
+
+Experimental and development versions of Radius can be found on Github:
+ 
+http://github.com/jlong/radius
+
+If you are interested in helping with the development of Radius, feel free to
+fork the project on GitHub and send me a pull request.
+
+
+John Long ::
+http://wiseheartdesign.com