rote 0.2.4.1 → 0.3.0

data/lib/rote/project/Rakefile

@@ -1,7 +1,7 @@
 # Standard Rakefile for custom Rote build
 #
 # Generated from:
-# $Id: Rakefile,v 1.1 2005/12/05 14:43:22 roscopeco Exp $
+# $Id: Rakefile,v 1.2 2005/12/12 02:45:24 roscopeco Exp $
 # 
 begin 
   require 'rubygems'
@@ -11,6 +11,7 @@ end
 require 'rake'
 require 'rake/clean'
 require 'rote'
+include Rote
 
 # Create a set of tasks with the prefix 'doc' to  build the
 # documentation set. The directory layout is as for the
@@ -29,16 +30,36 @@ require 'rote'
 #
 # In addition to these tasks, you may also wish to define a 'doc_refresh' task
 # to be run whenever modified resources are processed in monitor mode.
-ws = Rote::DocTask.new(:doc) { |site| 
+ws = Rote::DocTask.new(:doc) do |site| 
   site.output_dir = 'html'
   site.layout_dir = 'doc/layouts'
   
   site.pages.dir = 'doc/pages'
-  site.pages.include('**/*')  
-  
+  site.pages.include('**/*')   
+   
   site.res.dir = 'doc/res'
   site.res.include('**/*')
-}
+  
+  # TODO need to figure out what default mappings should be
+  site.ext_mapping(/(thtml)/, 'html') do |page|
+    page.extend Format::HTML
+    page.page_filter Filters::RedCloth.new(:textile)
+  end    
+  
+  site.ext_mapping(/mhtml/, 'html') do |page|
+    page.extend Format::HTML
+    page.page_filter Filters::RedCloth.new(:markdown)
+  end      
+  
+  site.ext_mapping(/rdoc/, 'html') do |page|
+    page.extend Format::HTML
+    page.page_filter Filters::RDoc.new
+  end      
+  
+  site.ext_mapping(/html/, 'html') do |page|
+    page.extend Format::HTML
+  end    
+end
 
 task :default => [:doc]
 

data/lib/rote/rotetasks.rb

@@ -1,8 +1,10 @@
+#--
 # Rake tasklib for Rote
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: rotetasks.rb,v 1.8 2005/12/05 14:44:32 roscopeco Exp $
+# $Id: rotetasks.rb,v 1.9 2005/12/12 02:45:24 roscopeco Exp $
+#++
 require 'rake'
 require 'rake/tasklib'
 
@@ -53,6 +55,54 @@ module Rote
       fl    
     end
   end
+  
+  # Special type of Hash that uses Regexp keys and maintains insertion order.
+  # When searching for a string, the first match (of either kind) is used. 
+  # Allows backreferences from the key match to be used in the value with $1..$n 
+  # notation in val str.
+  #
+  # Entries are kept in insertion order. Searches/insertion are slow, iteration
+  # is constant time. It's basically an unbucketed hash.
+  class ExtHash
+    class << self
+      alias :[] :new
+    end
+        
+    # Create a new RxHash, copying the supplied
+    # map (in random order).
+    def initialize(map = nil)
+      @data = []
+      map.each { |k,v| self[k] = v } if map
+    end
+  
+    # Insert the given regex key unless it already exists.
+    # You may use string representations for the keys, but
+    # they are converted as-is to regexps.    
+    #
+    # Returns the value that was inserted, or nil.
+    def []=(key,value)
+      @data << [key,value] unless member?(key)      
+    end
+    
+    # Fetch the first matching data.
+    def [](key)
+      md = nil
+      if v = @data.detect { |it| md = /^#{it[0]}$/.match(key.to_s) }
+        v[1][0].gsub!(/\$(\d)/) { md[$1.to_i] }
+        v[1]
+      end
+    end
+    
+    # Fetch a single entry based on key equality.
+    def fetch_entry(key)
+      @data.detect { |it| it[0] == key }
+    end
+    
+    # Determine membership based on key equality.
+    def member?(key)
+      true if fetch_entry(key)
+    end
+  end
 
   #####
   ## Rake task library that provides a set of tasks to transform documentation
@@ -95,8 +145,25 @@ module Rote
     # +FileList+.
     attr_reader :res
     
+    # Ordered +ExtHash+ that supplies mappings between input and output 
+    # file extensions. Keys are regexps that are matched in order 
+    # against the search key.
+    #
+    # The values are [extension, ({ |page| ...})] . If a mapping has a 
+    # block, it is executed when pages with a matching extension are,
+    # instantiated (before common and page code). It can be used to apply
+    # filters, for example, on a per-extension basis. 
+    attr_reader :ext_mappings
+    
+    # Define an extension mapping for the specified regex, which will 
+    # be replaced with the specified extension. If a block is supplied
+    # it will be called with each matching +Page+ as it's created.
+    def ext_mapping(match, extension, &block)
+      @ext_mappings[match] = [extension,block]      
+    end
+    
     # If +show_page_tasks+ is +true+, then the file tasks created for each
-    # source page will be shown in the Rake task listing from the command line.
+    # output file will be shown in the Rake task listing from the command line.
     attr_accessor :show_file_tasks         
     alias :show_file_tasks? :show_file_tasks
     alias :show_file_tasks= :show_file_tasks=
@@ -111,16 +178,17 @@ module Rote
     
     # Create a new DocTask, using the supplied block for configuration,
     # and define tasks with the specified base-name within Rake.
-    def initialize(name = :site) # :yield: self if block_given?
+    def initialize(name = :doc) # :yield: self if block_given?
       @name = name
       @output_dir = '.'      
       @pages = FilePatterns.new('.')
       @res = FilePatterns.new('.')
       @monitor_interval = 1
-      DEFAULT_SRC_EXCLUDES.each { |excl| @pages.exclude(excl) }
-      
+      @ext_mappings = ExtHash.new
       @show_page_tasks = false
       
+      DEFAULT_SRC_EXCLUDES.each { |excl| @pages.exclude(excl) }
+      
       yield self if block_given?
             
       define
@@ -135,16 +203,32 @@ module Rote
       nil
     end
     
+    # Get a target filename for a source filename. The dir_rx must
+    # match the portion of the directory that will be replaced 
+    # with the target directory. The extension is mapped through
+    # ext_mappings. If a block is configured for this extension,
+    # it is returned too.
+    #
+    # Returns [target_fn, ({ |page| ...})]
+    def target_fn(dir_rx, fn)
+      tfn = fn.sub(dir_rx, output_dir)      
+      ext = File.extname(tfn)
+      ext.sub!(/^\./,'') # strip leading dot                  
+      new_ext, blk = ext_mappings[ext] || [ext,nil]               
+      [tfn.sub(/#{ext}$/,new_ext),blk]
+    end
+    
     # define a task for each resource, and 'all resources' task
     def define_res_tasks
       res_fl = res.to_filelist
       tasks = res_fl.select { |fn| not File.directory?(fn) }.map do |fn|
-        tfn = fn.sub(/^#{res.dir}/, output_dir)
-        desc "#{fn} => #{tfn}" if show_file_tasks?
+        tfn, = target_fn(/^#{res.dir}/, fn)
+        
+        desc "#{fn} => #{tfn}" #if show_file_tasks?
         file tfn => [fn] do
           dn = File.dirname(tfn)
           mkdir_p dn unless File.exists?(dn)
-          cp fn, tfn
+          cp fn, tfn, :preserve => true        
         end
         tfn
       end
@@ -156,22 +240,52 @@ module Rote
     # define a task for each page, and 'all pages' task
     def define_page_tasks
       pages_fl = pages.to_filelist    
-      tasks = pages_fl.select { |fn| not File.directory?(fn) }.map do |fn| 
-        tfn = fn.sub(/^#{pages.dir}/, output_dir)          
-        desc "#{fn} => #{tfn}" if show_file_tasks?
+
+      gen_files = pages_fl.select { |fn| not File.directory?(fn) }.map do |fn|
+        tfn, blk = target_fn(/^#{pages.dir}/, fn) 
+                 
+        desc "#{fn} => #{tfn}" #if show_file_tasks?
         file tfn => [fn] do
           dn = File.dirname(tfn)
           mkdir_p dn unless File.exists?(dn)
-          File.open(tfn, 'w+') do |f|
-            puts "tr #{fn} => #{tfn}"
-            f << Page.new(fn,layout_dir).render
-          end          
+          puts "tr #{fn} => #{tfn}"
+          begin
+            File.open(tfn, 'w+') do |f|
+              # new page, run extension block, render out, throw away
+              f << Page.new(fn,pages.dir,layout_dir,&blk).render
+            end
+          rescue => e
+            # Oops... Unlink file and dump backtrace
+            File.unlink(tfn)
+            bt = e.backtrace
+            end_idx = bt.each_with_index do |entry, idx|
+              break idx if entry =~ /^#{File.dirname(__FILE__)}/
+            end
+            puts bt[0...end_idx]
+            raise
+          end
+        end
+        
+        # Each page depends properly on source and common - thx again
+        # Jonathan :)
+        src_rb = Page::page_ruby_filename(fn)
+        if File.exists?(src_rb)
+          file tfn => [src_rb]
         end
+        
+        common_rbs = Page::resolve_common_rubys(File.dirname(fn))
+        file tfn => common_rbs unless common_rbs.empty?
+        
         tfn
       end
       
       desc "Render new/changed documentation pages"
-      task "#{name}_pages" => tasks
+      task "#{name}_pages" => gen_files
+      task "clobber_#{name}_pages" do
+        gen_files.each do |f|
+          rm_f f
+        end
+      end    
     end
     
     def define_main_tasks
@@ -200,13 +314,12 @@ module Rote
       
     end
     
-  end #class  
-  
+  end #class    
 end #module
 
-## The -run task requires a few mods to Rake to let us fire
+## The +monitor+ task requires a few mods to Rake to let us fire
 ## and reset task invocations in a loop.
-module Rake
+module Rake # :nodoc: all
   class Task
     def reset
       @already_invoked = false

data/test/gem_tests.rb

@@ -1,2 +1,4 @@
 TEST_FROM_GEM = true
-require File.join(File.dirname(__FILE__), 'test_page.rb')
+$: << File.join(File.dirname(__FILE__),'../lib')
+Dir[File.join(File.dirname(__FILE__), '**/test_*.rb')].each { |test| require test }
+

data/test/layouts/simple.rb

@@ -0,0 +1 @@
+@layout_code_works = true

data/test/pages/markdown.txt

@@ -1,4 +1,8 @@
-<% format_opts << :markdown %>
+<% 
+		extend Format::HTML
+		format_opts << :markdown 
+%>
+
 *this* is a _test_
 ==================
 

data/test/pages/rdoc.txt

@@ -1,3 +1,6 @@
-<% format_opts << :rdoc %>
+<% 
+		extend Format::HTML
+		format_opts << :rdoc 
+%>
 == RDoc
 === Markup

data/test/pages/textile.rb

@@ -1 +1,3 @@
+extend Format::HTML
+
 format_opts << :textile

data/test/test_formatting.rb

@@ -0,0 +1,140 @@
+begin
+  require 'rubygems'
+rescue LoadError
+  nil
+end
+
+require 'test/unit'
+require 'rote/page'
+require 'rote/filters/redcloth'
+require 'rote/filters/rdoc'
+require 'rote/filters/proc'
+require 'rote/filters/toc'
+require 'rote/filters/syntax'
+
+SYNTEST = <<-EOM  
+  <p>Non-code</p>
+  #:code#ruby#
+  def amethod(arg)
+    puts arg
+  end
+  #:code#
+  <p>More non-code</p>
+  #:code#ruby#
+  def amethod_too(arg)
+    puts arg
+  end
+  #:code#
+
+EOM
+
+SYNEXPECT = <<-EOM
+  <p>Non-code</p>
+<pre class='ruby'><code>  <span class=\"keyword\">def </span><span class=\"method\">amethod</span><span class=\"punct\">(</span><span class=\"ident\">arg</span><span class=\"punct\">)</span>
+    <span class=\"ident\">puts</span> <span class=\"ident\">arg</span>
+  <span class=\"keyword\">end</span></code></pre>
+  <p>More non-code</p>
+<pre class='ruby'><code>  <span class=\"keyword\">def </span><span class=\"method\">amethod_too</span><span class=\"punct\">(</span><span class=\"ident\">arg</span><span class=\"punct\">)</span>
+    <span class=\"ident\">puts</span> <span class=\"ident\">arg</span>
+  <span class=\"keyword\">end</span></code></pre>
+EOM
+
+TOCTEST = <<-EOM
+  <h2>Section One</h2>
+  <p>This is section one</p>  
+  <h3>Section Two</h3>
+  <p>This is section two</p>  
+EOM
+
+TOCEXPECTH2 = <<-EOM
+  <a name='section_one'></a><h2>Section One</h2>
+  <p>This is section one</p>  
+  <h3>Section Two</h3>
+  <p>This is section two</p>  
+EOM
+
+TOCEXPECTALL = <<-EOM
+  <a name='section_one'></a><h2>Section One</h2>
+  <p>This is section one</p>  
+  <a name='section_two'></a><h3>Section Two</h3>
+  <p>This is section two</p>  
+EOM
+
+module Rote  
+  class TestFormatting < Test::Unit::TestCase
+    ############## filters/redcloth #################    
+    def test_render_default     # textile
+      t = Filters::RedCloth.new.filter('*Textile* _Test_', nil)
+      assert_equal '<p><strong>Textile</strong> <em>Test</em></p>', t
+    end
+
+    def test_render_textile
+      t = Filters::RedCloth.new(:textile).filter('*Textile* _Test_', nil)
+      assert_equal '<p><strong>Textile</strong> <em>Test</em></p>', t
+    end
+
+    def test_render_markdown
+      t = Filters::RedCloth.new(:markdown).filter("*this* is a _test_\n==================", nil)
+      assert_equal '<h1>*this* is a _test_</h1>', t
+    end
+
+    ############## filters/rdoc #################
+    # FIXME Fails under Gem install, but passes when run normally (???)
+    unless defined?(TEST_FROM_GEM)
+      def test_render_rdoc
+        t = Filters::RDoc.new.filter("== RDoc\n=== Markup",nil)
+        assert_equal "<h2>RDoc</h2>\n<h3>Markup</h3>\n", t
+      end
+    end
+    
+    ############## filters/proc #################
+    # FIXME Fails under Gem install, but passes when run normally (???)
+    def test_proc_no_block
+      begin
+        Filters::Proc.new
+      rescue ArgumentError => ex
+        assert_equal 'No block given', ex.message
+      end      
+    end
+    
+    def test_render_with_proc
+      f = Filters::Proc.new { |text, page| text + page }
+      assert_equal f.filter('some text ', 'fake page'), 'some text fake page'      
+
+      # equivalent
+      f = Filters::Proc.with do |text, page| 
+        text + page 
+      end      
+      assert_equal f.filter('some text ', 'fake page'), 'some text fake page'      
+    end
+    
+    # Toc filter is a non-output filter - it's used to get a list of links in 
+    # the page, from layout code. It should output it's input directly, so
+    # that it doesn't matter where in the chain it is.
+    def test_toc_filter
+      # default RE
+      toc = Filters::TOC::new
+      assert_equal '<p>Has no sections</p>', toc.filter('<p>Has no sections</p>', nil)
+      assert toc.links.empty?
+
+      assert_equal TOCEXPECTALL, toc.filter(TOCTEST, nil)
+      assert_equal "<a href='#section_one'>Section One</a> - <a href='#section_two'>Section Two</a>", toc.links.join(' - ')
+
+      # custom RE
+      toc = Filters::TOC::new(/h2/)
+      assert_equal TOCEXPECTH2, toc.filter(TOCTEST, nil)
+      assert_equal "<a href='#section_one'>Section One</a>", toc.links.join(' - ')
+    end
+    
+    def test_syntax_filter
+      # bad
+      assert_equal '', Filters::Syntax.new.filter('', nil)    
+      assert_equal 'Has no source', Filters::Syntax.new.filter('Has no source', nil)    
+      
+      # good
+      assert_equal SYNEXPECT.chomp, Filters::Syntax.new.filter(SYNTEST, nil)    
+    end
+  end
+  
+end    
+