radius19-radiant 1.0.0

data/CHANGELOG

@@ -0,0 +1,7 @@
+= Change Log
+
+=== 0.5.3
+* Patched to work under Ruby 1.9
+
+=== 0.5.2
+* Original import from Radius (Ruby 1.8)

data/QUICKSTART

@@ -0,0 +1,323 @@
+= 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 'radius19'
+  
+  context = 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 <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:
+
+  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(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:
+
+  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

@@ -0,0 +1,5 @@
+= Radius19 for radiantcms-couchrest_model
+
+Based on the originalwork of Adrian Madrid (aemadrid@gmail.com)
+
+on https://github.com/aemadrid/radius19/

data/ROADMAP

@@ -0,0 +1,12 @@
+= 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. Incorporate strscan?

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "radius19"
+    gem.summary = %Q{A small, but powerful tag-based template language for Ruby modeled after the ones used in MovableType and TextPattern. It has tags similar to XML, but can be used to generate any form of plain text (HTML, e-mail, etc...) adapted to work on Ruby 1.9.}
+    gem.email = "aemadrid@gmail.com"
+    gem.homepage = "http://github.com/aemadrid/radius19"
+    gem.authors = ["Adrian Madrid", "John W. Long"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "radius19 #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.5.3

data/lib/radius/context.rb

@@ -0,0 +1,139 @@
+module Radius
+  #
+  # A context contains the tag definitions which are available for use in a template.
+  # See the QUICKSTART[link:files/QUICKSTART.html] for a detailed explaination its
+  # usage.
+  #
+  class Context
+    # A hash of tag definition blocks that define tags accessible on a Context.
+    attr_accessor :definitions # :nodoc:
+    attr_accessor :globals # :nodoc:
+
+    # Creates a new Context object.
+    def initialize(&block)
+      @definitions = {}
+      @tag_binding_stack = []
+      @globals = DelegatingOpenStruct.new
+      with(&block) if block_given?
+    end
+
+    # Yeild an instance of self for tag definitions:
+    #
+    #   context.with do |c|
+    #     c.define_tag 'test' do
+    #       'test'
+    #     end
+    #   end
+    #
+    def with
+      yield self
+      self
+    end
+
+    # Creates a tag definition on a context. Several options are available to you
+    # when creating a tag:
+    #
+    # +for+::             Specifies an object that the tag is in reference to. This is
+    #                     applicable when a block is not passed to the tag, or when the
+    #                     +expose+ option is also used.
+    #
+    # +expose+::          Specifies that child tags should be set for each of the methods
+    #                     contained in this option. May be either a single symbol/string or
+    #                     an array of symbols/strings.
+    #
+    # +attributes+::      Specifies whether or not attributes should be exposed
+    #                     automatically. Useful for ActiveRecord objects. Boolean. Defaults
+    #                     to +true+.
+    #
+    def define_tag(name, options = {}, &block)
+      type = Util.impartial_hash_delete(options, :type).to_s
+      klass = Util.constantize('Radius::TagDefinitions::' + Util.camelize(type) + 'TagFactory') rescue raise(ArgumentError.new("Undefined type `#{type}' in options hash"))
+      klass.new(self).define_tag(name, options, &block)
+    end
+
+    # Returns the value of a rendered tag. Used internally by Parser#parse.
+    def render_tag(name, attributes = {}, &block)
+      if name =~ /^(.+?):(.+)$/
+        render_tag($1) { render_tag($2, attributes, &block) }
+      else
+        tag_definition_block = @definitions[qualified_tag_name(name.to_s)]
+        if tag_definition_block
+          stack(name, attributes, block) do |tag|
+            tag_definition_block.call(tag).to_s
+          end
+        else
+          tag_missing(name, attributes, &block)
+        end
+      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(name, attributes, &block)
+      raise UndefinedTagError.new(name)
+    end
+
+    # Returns the state of the current render stack. Useful from inside
+    # a tag definition. Normally just use TagBinding#nesting.
+    def current_nesting
+      @tag_binding_stack.collect { |tag| tag.name }.join(':')
+    end
+
+    private
+
+    # A convienence method for managing the various parts of the
+    # tag binding stack.
+    def stack(name, attributes, block)
+      previous = @tag_binding_stack.last
+      previous_locals = previous.nil? ? @globals : previous.locals
+      locals = DelegatingOpenStruct.new(previous_locals)
+      binding = TagBinding.new(self, locals, name, attributes, block)
+      @tag_binding_stack.push(binding)
+      result = yield(binding)
+      @tag_binding_stack.pop
+      result
+    end
+
+    # Returns a fully qualified tag name based on state of the
+    # tag binding stack.
+    def qualified_tag_name(name)
+      nesting_parts = @tag_binding_stack.collect { |tag| tag.name }
+      nesting_parts << name unless nesting_parts.last == name
+      specific_name = nesting_parts.join(':') # specific_name always has the highest specificity
+      unless @definitions.has_key? specific_name
+        possible_matches = @definitions.keys.grep(/(^|:)#{name}$/)
+        specificity = possible_matches.inject({}) { |hash, tag| hash[numeric_specificity(tag, nesting_parts)] = tag; hash }
+        max = specificity.keys.max
+        if max != 0
+          specificity[max]
+        else
+          name
+        end
+      else
+        specific_name
+      end
+    end
+
+    # Returns the specificity for +tag_name+ at nesting defined
+    # by +nesting_parts+ as a number.
+    def numeric_specificity(tag_name, nesting_parts)
+      nesting_parts = nesting_parts.dup
+      name_parts = tag_name.split(':')
+      specificity = 0
+      value = 1
+      if nesting_parts.last == name_parts.last
+        while nesting_parts.size > 0
+          if nesting_parts.last == name_parts.last
+            specificity += value
+            name_parts.pop
+          end
+          nesting_parts.pop
+          value *= 0.1
+        end
+        specificity = 0 if (name_parts.size > 0)
+      end
+      specificity
+    end
+  end
+end