gerbil 1.0.0

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright 2006 Suraj N. Kurapati <SNK at GNA dot ORG>
+
+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:
+
+* All copies and substantial portions of the Software (the "Derivatives")
+  and their corresponding machine-readable source code (the "Code") must
+  include the above copyright notice and this permission notice.
+
+* Upon distribution, the Derivatives must be accompanied either by the Code
+  or--provided that the Code is obtainable for no more than the cost of
+  distribution plus a nominal fee--by information on how to obtain the Code.
+
+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.

data/README

@@ -0,0 +1 @@
+Please see doc/guide.html in your web browser.

data/Rakefile

@@ -0,0 +1,48 @@
+# Copyright 2007 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+require 'rake/clean'
+require 'rake/gempackagetask'
+
+# documentation
+  desc "Generate documentation."
+  task :doc => 'doc/guide.html'
+
+  file 'doc/guide.html' => 'doc/guide.erb' do |t|
+    sh "ruby bin/gerbil html #{t.prerequisites} > #{t.name}"
+  end
+
+  CLOBBER.include 'doc/guide.html'
+
+# packaging
+  require 'lib/gerbil' # project info
+
+  spec = Gem::Specification.new do |s|
+    s.name        = 'gerbil'
+    s.version     = Gerbil[:version]
+    s.summary     = 'Extensible document generator based on eRuby.'
+    s.description = s.summary
+    s.homepage    = Gerbil[:website]
+    s.files       = FileList['**/*'].exclude('_darcs')
+    s.executables = s.name
+
+    s.add_dependency 'RedCloth' # needed by the default 'html' format
+    s.add_dependency 'coderay'  # needed by the default 'html' format
+  end
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar = true
+    pkg.need_zip = true
+  end
+
+# releasing
+  desc 'Build packages for distribution.'
+  task :release => [:clobber, :doc] do
+    system 'rake package'
+  end
+
+# utility
+  desc 'Upload to project website.'
+  task :upload => :doc do
+    sh 'rsync -av doc/ ~/www/lib/gerbil'
+  end

data/bin/gerbil

@@ -0,0 +1,275 @@
+#!/usr/bin/env ruby
+
+# Gerbil is an extensible document generator based on eRuby.
+#
+# * STDIN will be read if an input file is not specified.
+#
+# * If an error occurs, the input document will be printed to STDOUT
+#   so you can investigate line numbers in the error's stack trace.
+#
+#   Otherwise, the final output document will be printed to STDOUT.
+
+# Copyright 2007 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+require 'erb'
+include ERB::Util
+
+require 'digest/sha1'
+require 'yaml'
+require 'ostruct'
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'gerbil'
+
+# Prints the given message and raises the given error.
+def hoist aMessage, aError = $!
+  STDERR.printf "%s:\n\n", aMessage
+  raise aError
+end
+
+class String
+  # Returns a SHA1 digest (in hex format) of this string.
+  def digest
+    Digest::SHA1.hexdigest(self)
+  end
+end
+
+class Template < ERB
+  # Returns the result of template evaluation thus far.
+  attr_reader :buffer
+
+  # aName:: String that replaces the ambiguous '(erb)' identifier in stack
+  #         traces, so that the user can better determine the source of an
+  #         error.
+  #
+  # args:: Arguments for ERB::new
+  def initialize aName, *args
+    # silence the code-only <% ... %> directive, just like PHP does
+    args[0].gsub!(/^[ \t]*<%[^%=]((?!<%).)*?[^%]%>[ \t]*\r?\n/m) {|s| s.strip}
+
+    args[3] = '@buffer'
+    super(*args)
+
+    @filename = aName
+  end
+
+  # Renders this template within a fresh object that
+  # is populated with the given instance variables.
+  def render_with aInstVars = {}
+    context = Object.new.instance_eval do
+      aInstVars.each_pair do |var, val|
+        instance_variable_set var, val
+      end
+
+      binding
+    end
+
+    result(context)
+  end
+
+  private
+
+  # Returns the content that the given block wants to append to
+  # the buffer.  If the given block does not want to append to the
+  # buffer, then returns the result of invoking the given block.
+  def content_from_block *aBlockArgs
+    raise ArgumentError, 'block must be given' unless block_given?
+
+    start = @buffer.length
+    value = yield(*aBlockArgs) # this will do: buffer << content
+    finish = @buffer.length
+
+    if finish > start
+      @buffer.slice! start..-1
+    else
+      value
+    end.to_s
+  end
+end
+
+class Node < OpenStruct
+  undef id, type # these are deprecated in Ruby 1.8 anyway
+end
+
+# the basename() is for being launched by a RubyGems executable
+if __FILE__ == $0 or File.basename(__FILE__) == File.basename($0)
+  # parse command-line options
+    require 'optparse'
+
+    opts = OptionParser.new('')
+
+    opts.on '-h', '--help', 'show usage information' do
+      # show program description located at the top of this file
+      puts File.read(__FILE__).split(/^$\n/)[1].gsub(/^# ?/, '')
+
+      puts "\nUsage: #{File.basename $0} [Option...] Format|SpecFile [InputFile]\n"
+
+      puts "\nOption: #{opts}"
+
+      puts "\nFormat:"
+      Gerbil[:format_files].each do |file|
+        name = File.basename(file, '.yaml')
+        desc = YAML.load_file(file)['desc'] rescue nil
+        puts '    %-32s %s' % [name, desc]
+      end
+
+      exit
+    end
+
+    opts.on '-v', '--version', 'show version information' do
+      puts "%s %s (%s) %s %s" %
+        [:name, :version, :release, :website, :home].map { |m| Gerbil[m] }
+      exit
+    end
+
+    opts.parse! ARGV
+
+  # load format specification file
+    specFile = ARGV.shift or
+      raise ArgumentError, "Format was not specified.  Try `{$0} -h` for help."
+
+    File.file? specFile or
+      specFile = File.join(Gerbil[:format_home], specFile + '.yaml')
+
+    begin
+      specData = YAML.load_file(specFile).merge! \
+        :file => File.expand_path(specFile),
+        :name => File.basename(specFile).sub(/\..*?$/, '')
+
+    rescue Exception
+      hoist "Error when loading the format specification file (#{specFile.inspect})"
+    end
+
+    if specData.key? 'code'
+      eval specData['code'].to_s, binding, "#{specFile}:code"
+    end
+
+  # load input document
+    input = ARGF.read
+
+    # expand all "include" directives in the input
+    begin end while input.gsub! %r/<%#\s*include\s+(.+?)\s*%>/ do
+      "<%#begin(#{name = $1.inspect})%>#{File.read $1}<%#end(#{name})%>"
+    end
+
+  # process input document
+    template = Template.new('INPUT', input)
+
+    templateVars = {
+      :@spec => specData,
+      :@roots => roots = [], # root nodes of all trees
+      :@nodes => nodes = [], # all nodes in the forest
+      :@types => types = Hash.new {|h,k| h[k] = []}, # nodes by type
+    }.each_pair { |k,v| template.instance_variable_set(k, v) }
+
+    nodeDefs = specData['nodes'].each_pair do |name, info|
+      template.instance_eval %{
+        #
+        # XXX: using a string because define_method()
+        #      does not accept a block until Ruby 1.9
+        #
+        def #{name} *aArgs, &aBlock
+          node = Node.new(
+            :type => #{name.inspect},
+            :args => aArgs,
+            :trace => caller,
+            :children => []
+          )
+          @nodes << node
+          @types[node.type] << node
+
+          # calculate occurrence number for this node
+          if #{info['number']}
+            @count ||= Hash.new {|h,k| h[k] = []}
+            node.number = (@count[node.type] << node).length
+          end
+
+          @stack ||= []
+
+          # assign node family
+          if parent = @stack.last
+            parent.children << node
+            node.parent = parent
+            node.depth = parent.depth.next
+
+            # calculate latex-style index number for this node
+            if #{info['index']}
+              branches = parent.children.select {|n| n.index}
+              node.index = [parent.index, branches.length.next].join('.')
+            end
+          else
+            @roots << node
+            node.parent = nil
+            node.depth = 0
+
+            # calculate latex-style index number for this node
+            if #{info['index']}
+              branches = @roots.select {|n| n.index}
+              node.index = branches.length.next.to_s
+            end
+          end
+
+          # assign node content
+          if block_given?
+            @stack << node
+            content = content_from_block(node, &aBlock)
+            @stack.pop
+
+            digest = content.digest
+
+            node.content = content
+            node.digest  = digest
+
+            @buffer << digest
+          else
+            digest = node.object_id.to_s.digest
+            node.digest = digest
+          end
+
+          digest
+        end
+      },  __FILE__, Kernel.caller.first[/\d+/].to_i.next
+    end
+
+    begin
+      # build the document tree
+      document = template.instance_eval { result(binding) }
+
+      # replace nodes with output
+      expander = lambda do |n, buf|
+        # unindent content
+        if defined? $unindent and n.content
+          n.content.gsub! %r/^(#{Regexp.escape $unindent}){0,#{n.depth.next}}/, ''
+        end
+
+        # calculate node output
+        source = "#{specFile}:nodes:#{n.type}:output"
+        n.output = Template.new(source, nodeDefs[n.type]['output'].to_s.chomp).
+                   render_with(templateVars.merge(:@node => n))
+
+        # replace node with output
+        if nodeDefs[n.type]['silent']
+          buf.sub! n.digest, ''
+          buf = n.output
+        else
+          buf.sub! n.digest, n.output
+        end
+
+        # repeat for all child nodes
+        n.children.each {|c| expander[c, buf]}
+      end
+
+      roots.each {|n| expander[n, document]}
+
+    rescue Exception
+      puts input # so the user can debug the line numbers in the stack trace
+      hoist 'Error when processing the input document (INPUT)'
+    end
+
+  # produce output document
+    output = Template.new("#{specFile}:output", specData['output'].to_s).
+             render_with(templateVars.merge(:@content => document))
+
+    puts output
+end

data/doc/HelloWorld.input

@@ -0,0 +1,37 @@
+<% $style = "border-left: thick solid salmon; padding-left: 1em;" %>
+<% hello "Pretentious" do %>
+  <big>I'm</big> the very first node, oh _yes_ I am! *sneer*
+
+  <% hello "Bashful" do %>
+    Hi, I... *hide*
+
+    <% hello "Hopeful" do %>
+      *sigh*
+
+      <% hello "Confused" do %>
+        Huh?
+      <% end %>
+    <% end %>
+
+    <% hello "Raving" do %>
+      Oh it's *on* now! You're going *down*!
+    <% end %>
+  <% end %>
+
+  <% hello "Sleepy" do %>
+    *yawn* Just five more minutes...
+
+    <% hello "Peaceful" do %>
+      So _be_ happy my friend, *happy*!
+
+      <%= hello "Lonely (as you can see, I have no block)" %>
+    <% end %>
+  <% end %>
+<% end %>
+
+<% hello "Snappy" do %>
+  Zip! Zap! Wake up, you sap!
+  _Whoo I'm wild!_ ;-)
+<% end %>
+
+<%= hello "Independent (no block, no parents, I am _free_!)" %>

data/doc/HelloWorld.spec

@@ -0,0 +1,66 @@
+desc: A illustrative format.
+
+code: |
+  # Returns a random, but pronounceable, name.
+  def generate_name
+    letters = ('a'..'z').to_a - %w[ c q w x ] # redundant sounds
+    vowels = %w[a e i o u]
+    consonants = letters - vowels
+    sets = [consonants, vowels]
+
+    length = 3 + rand(5)
+
+    name = ''
+    length.times do |i|
+      set = sets[i % sets.length]
+      name << set[rand(set.length)]
+    end
+
+    name
+  end
+
+  class Node
+    def name
+      @name ||= generate_name
+    end
+  end
+
+nodes:
+  hello:
+    index: true
+    number: true
+    silent: false
+    output: |
+      <h1><%= @node.type %> #<%= @node.index %>: <%= @node.name.inspect %></h1>
+      My name is <%= @node.name.inspect %> and these are my properties:
+      <table>
+        <tr>
+          <th>Property</th>
+          <th>Value</th>
+        </tr>
+        <tr>
+          <td>args</td>
+          <td><%= @node.args.inspect %></td>
+        </tr>
+        <tr>
+          <td>index</td>
+          <td><%= @node.index.inspect %></td>
+        </tr>
+        <tr>
+          <td>number</td>
+          <td><%= @node.number.inspect %></td>
+        </tr>
+        <tr>
+          <td>trace</td>
+          <td><ul><%= @node.trace.map {|s| "<li>#{s}</li>"} %></ul></td>
+        </tr>
+        <tr>
+          <td>content</td>
+          <td><%= @node.content %></td>
+        </tr>
+      </table>
+
+output: |
+  Welcome to the "<%= @spec[:name] %>" format.
+  <div style="<%= $style %>"><%= @content %></div>
+  That's all folks!