rote 0.2.4.1 → 0.3.0

data/lib/rote/filters/toc.rb

@@ -0,0 +1,74 @@
+#--
+# Rote filter for TOC generation
+# (c)2005 Ross Bamford (and contributors)
+#
+# See 'rote.rb' or LICENSE for licence information.
+# $Id: toc.rb,v 1.2 2005/12/12 02:45:24 roscopeco Exp $
+#++
+
+module Rote
+  module Filters
+  
+    #####
+    ## Page filter that supports easy construction of a Table Of Contents
+    ## from your *layout*. This filter searches for tags matching the 
+    ## specified regular expression(s) (H tags by default), and stores them
+    ## to be used for TOC generation in the layout. HTML Named-anchors are
+    ## created based on the headings found.
+    ##
+    ## Additional attributes for the A tags can be passed via the +attrs+
+    ## parameter.
+    class TOC
+    
+      # An individual Heading in the +links+ array.
+      class Heading
+        class << self
+          alias :[] :new
+        end
+        
+        def initialize(tag, title, attrs = {})
+          @tag = tag
+          @title = title   
+          @attrs = attrs               
+        end        
+        
+        # The information held by this link
+        attr_accessor :tag, :title, :attrs
+        
+        def anchor
+          title.downcase.gsub(/<[^>]+>/,'').gsub(/[^a-z]+/,'_')
+        end
+        
+        def to_s
+          %Q[<a #{"#{(attrs.collect { |k,v| "#{k}='#{v}'" }).join(' ')} " unless attrs.empty?}href='##{anchor}'>#{title}</a>]        
+        end
+      end
+
+      def initialize(tags_re = /h\d+/, attrs = {})
+        @tags_re = tags_re
+        @attrs = attrs
+        @headings = []
+      end
+      
+      # Array of heading links with the
+      # heading title as the link text. Suitable
+      # for joining and outputting:
+      #
+      #   <%= links.join(" - ") %>
+      #
+      # *Note* that this isn't populated until after
+      # the filter is run.
+      attr_reader :headings
+      alias :links :headings
+      
+      def filter(text, page)
+        # find headings *and insert named anchors*
+        text.gsub(%r[<(#{@tags_re})>(.*?)</\1>]) do
+          headings << (h = Heading[$1,$2])
+          %Q[<a name='#{h.anchor}'></a>#{$&}]
+        end        
+      end   
+    end
+    
+  end
+end

data/lib/rote/format.rb

@@ -0,0 +1,9 @@
+#--
+# Require all formats
+# (c)2005 Ross Bamford (and contributors)
+#
+# See 'rote.rb' or LICENSE for licence information.
+# $Id: format.rb,v 1.2 2005/12/12 02:45:24 roscopeco Exp $
+#++
+
+Dir[File.join(File.dirname(__FILE__), 'format/*.rb')].each { |f| require f }

data/lib/rote/format/html.rb

@@ -0,0 +1,49 @@
+#--
+# Rote format helper for HTML
+# (c)2005 Ross Bamford (and contributors)
+#
+# See 'rote.rb' or LICENSE for licence information.
+# $Id: html.rb,v 1.2 2005/12/12 02:45:24 roscopeco Exp $
+#++
+require 'erb'
+
+module Rote
+  module Format
+  
+    # HTML Formatting module for Rote. This module may be mixed in to any Page
+    # instance to provide various HTML helpers (including those from ERB::Util).
+    #
+    # To use this module for a given page, simply place the following code
+    # somewhere applicable to that page:
+    #
+    #   extend Format::HTML
+    #
+    # Note that +include+ cannot be used since the page code is run via
+    # +instance_eval+.
+    module HTML
+      include ERB::Util
+      
+      ###################################################################
+      ## HELPERS
+      
+      # Make the given output-root-relative path relative to the
+      # current page's path. This is handy when you do both local
+      # preview from some deep directory, and remote deployment
+      # to a root
+      def relative(href)
+        thr = href
+        
+        if thr.is_a?(String) && href[0,1] == '/'    # only interested in absolute        
+          dtfn = File.dirname(template_name) + '/'
+          
+          count = dtfn == './' ? 0 : dtfn.split('/').length
+          thr = ('../' * count) + href[1..href.length]
+        end
+        
+        thr
+      end
+          
+      alias :link_rel :relative    # Alias 'link_rel' is deprecated, vv0.2.99 v-0.4
+    end # HTML
+  end # Format
+end # Rote

data/lib/rote/page.rb

@@ -1,34 +1,68 @@
+#--
 # Rote page class
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: page.rb,v 1.9 2005/12/05 14:44:32 roscopeco Exp $
+# $Id: page.rb,v 1.10 2005/12/12 02:45:24 roscopeco Exp $
+#++
+
 require 'erb'
-require 'rdoc/markup/simple_markup'
-require 'rdoc/markup/simple_markup/to_html'
 
-begin
-  require 'redcloth'
-rescue LoadError
-  # optional dep
-  nil
-end
+# Don't want user to have to require these in their pagecode.
+require 'rote/format/html'
 
 module Rote
-
+  STRIP_SLASHES = /^\/?(.*?)\/?$/
+  FILE_EXT = /\..*$/
+  
   #####
   ## A +Page+ object represents an individual template source file, taking
   ## input from that file and (optionally) some ruby code, and producing 
-  ## rendered (or 'merged') output as a +String+.
-  ## When a page is created, ruby source will be found alongside the 
+  ## rendered (or 'merged') output as a +String+. All user-supplied code
+  ## (COMMON.rb or page code, for example) is executed in the binding
+  ## of an instance of this class. 
+  ##
+  ## When a page is created, ruby source will be sought alongside the 
   ## file, with same basename and an '.rb' extension. If found it will
   ## run through +instance_eval+. That source can call methods
   ## and set any instance variables, for use later in the template.
+  ## Such variables or methods may also be defined in a COMMON.rb file
+  ## in or above the page's directory, in code associated with the 
+  ## +layout+ applied to a page, or (less often) in a block supplied to
+  ## +new+.
   ##
   ## Rendering happens only once for a given page object, when the 
   ## +render+ method is first called. Once a page has been rendered
   ## it is frozen.
   class Page  
+  
+    class << self
+      # Helper that returns a page-code filename given a template filename.
+      # This does not check that the source exists - use the +ruby_filename+
+      # instance method to get the actual filename (if any) of source
+      # associated with a given page instance.
+      def page_ruby_filename(template_fn)
+        fn = nil
+        if (template_fn) 
+          if (fn = template_fn.dup) =~ FILE_EXT
+            fn[FILE_EXT] = '.rb'
+          else
+            fn << '.rb' unless fn.empty?
+          end            
+        end        
+        fn
+      end
+      
+      # Find all COMMON.rb files from given dir up to FS root.
+      def resolve_common_rubys(dir, arr = [])
+        # defer to parent dir first
+        parent = File.expand_path(File.join(dir, '..'))
+        resolve_common_rubys(parent,arr) unless parent == dir # at root    
+        fn = File.join(dir,'COMMON.rb')    
+        arr << fn if (File.exists?(fn) && File.readable?(fn))
+      end  
+    end
+    
     # The text of the template to use for this page.
     attr_reader :template_text
 
@@ -36,24 +70,20 @@ module Rote
     # when (if) the page source calls layout(basename).
     attr_reader :layout_text
     
-    # Formatting options for this page. This is an array of the
-    # option symbols, as defined by RedCloth, with a further +:rdoc+ 
-    # symbol that selects RDoc formatting. The most common are 
-    # :textile. :markdown, and :rdoc, but additional options are
-    # supported by RedCloth - see it's documentation for full details
-    # of supported option symbols and their effect.
-    # 
-    # The default is [], which means 'No formatting'. This setting
-    # does not affect ERB rendering (which is always performed, before
-    # any formatting).
-    attr_reader :format_opts
-    def format_opts=(opts)
-      if !opts.nil? && opts.respond_to?(:to_ary)
-        @format_opts = opts
-      else
-        @format_opts = [opts]
-      end
-    end
+    # The names from which this page's template and layout (if any) 
+    # were read, relative to the +base_path+.
+    attr_reader :template_name, :layout_name    
+    
+    # The base paths for this page's template and layout. These point
+    # to the directories configured in the Rake tasks.
+    attr_reader :base_path, :layout_path
+    
+    # The array of page filters (applied to this page output *before* 
+    # layout is applied) and post filters (three gueses). 
+    # You can use +append_page_filter+ and +append_post_filter+ to add 
+    # new filters, which gives implicit block => Filters::Proc conversion 
+    # and checks for nil.
+    attr_reader :page_filters, :post_filters   
     
     # Reads the template, and evaluates the global and page scripts, if 
     # available, using the current binding. You may define any instance
@@ -64,49 +94,80 @@ module Rote
     # If specified, the layout path will be used to find layouts referenced
     # from templates. 
     #
-    # If a block is supplied, it is executed _after_ the global / page
-    # code, so you can locally override variables and so on. 
-    def initialize(template_fn, 
-                   layout_path = File.dirname(template_fn), 
-                   default_layout_ext = File.extname(template_fn)) # :yield: self if block_given?    
+    # If a block is supplied, it is executed _before_ the global / page
+    # code. This will be the block supplied by the file-extension mapping.
+    def initialize(template_name, pages_dir = '.', layout_dir = pages_dir, &blk) 
       @template_text = nil
+      @template_name = nil
       @layout_text = nil
+      @layout_name = nil
       @content_for_layout = nil
       @result = nil
-      @format_opts = []
-      @layout_defext = default_layout_ext
-      @layout_path = layout_path
-      @fixme_dir = File.dirname(template_fn)
+      @layout_defext = File.extname(template_name)
+      @layout_path = layout_dir[STRIP_SLASHES,1]
+      @base_path = pages_dir[STRIP_SLASHES,1]
       
+      @page_filters, @post_filters = [], []
+
       # read in the template. Layout _may_ get configured later in page code
-      read_template(template_fn)
+      # We only add the pages_dir if it's not already there, because it's
+      # easier to pass the whole relative fn from rake...
+      # template_name always needs with no prefix.
+      tfn = template_name
+      read_template(tfn)
       
-      # get script filenames, and eval them if found
-      src_rb = template_fn.sub(/\..*$/,'') + '.rb'            
-      section_rb = @fixme_dir + '/COMMON.rb'
-      instance_eval(File.read(section_rb),section_rb) if File.exists?(section_rb)     
-      instance_eval(File.read(src_rb),src_rb) if File.exists?(src_rb)    
+      blk[self] if blk
+      
+      # Eval COMMON.rb's
+      eval_common_rubys
       
-      # Allow block to have the final say
-      yield self if block_given?  
+      # get script filenames, and eval them if found
+      tfn = ruby_filename # nil if no file      
+      instance_eval(File.read(tfn),tfn) if tfn      
     end
             
-    # Sets the layout from the specified file, or disables layout if
-    # +nil+ is passed in. The specified basename should be the name
-    # of the layout file relative to the +layout_dir+, with no extension.
-    #
-    # The layout is read by this method. An exception is
-    # thrown if the layout doesn't exist.
-    #
-    # This can only be called before the first call to +render+. After 
-    # that the instance is frozen.
-    def layout(basename)
-      if basename
-        fn = layout_fn(basename)
-        raise "Layout #{fn} not found" unless File.exists?(fn)
-        @layout_text = File.read(fn)
+    # Returns the full filename of this Page's template. This is obtained by
+    # joining the base path with template name.
+    def template_filename
+      template_name ? File.join(base_path,template_name) : nil
+    end
+    
+    # Returns the full filename of this Page's template. This is obtained by
+    # joining the base path with template name.
+    def layout_filename
+      layout_name ? File.join(layout_path,layout_name) : nil
+    end
+    
+    # Returns the full filename of this Page's ruby source. If no source is
+    # found for this page (not including common source) this returns +nil+.
+    def ruby_filename
+      fn = Page::page_ruby_filename(template_filename) 
+      File.exists?(fn) ? fn : nil
+    end
+
+    # Append +filter+ to this page's page-filter chain, or create 
+    # a new Rote::Filters::TextFilter with the supplied block.
+    # This method should be preferred over direct manipulation of
+    # the +filters+ array if you are simply building a chain.
+    def page_filter(filter = nil, &block)
+      if filter
+        page_filters << filter
+      else
+        if block
+          page_filters << Filters::Proc.new(block)
+        end
+      end
+    end    
+    
+    # Append +filter+ to this page's post-filter chain.
+    # Behaviour is much the same as +append_page_filter+.
+    def post_filter(filter = nil, &block)
+      if filter
+        post_filters << filter
       else
-        @layout_text = nil
+        if block
+          post_filters << Filters::Proc.new(block)
+        end
       end
     end    
     
@@ -119,116 +180,108 @@ module Rote
     
     alias to_s render
     
-    private
+    # Sets the layout from the specified file, or disables layout if
+    # +nil+ is passed in. The specified basename should be the name
+    # of the layout file relative to the +layout_dir+, with no extension.
+    #
+    # *The* *layout* *is* *not* *read* *by* *this* *method*. It, and 
+    # it's source, are loaded only at rendering time. This prevents
+    # multiple calls by various scoped COMMON code, for example, from
+    # making a mess in the Page binding.
+    #
+    # This can only be called before the first call to +render+. After 
+    # that the instance is frozen.
+    def layout(basename)
+      if basename
+        # layout text
+        @layout_name = "#{basename}#{@layout_defext if File.extname(basename).empty?}"
+      else
+        @layout_name = nil
+      end
+    end    
+    
+    private        
         
     # Sets the template from the specified file, or clears the template if
     # +nil+ is passed in. The specified basename should be the name
     # of the layout file relative to the +layout_dir+, with no extension.
-    def read_template(fn)
+    def read_template(fn)    
       if fn
-        raise "Template #{fn} not found" unless File.exists?(fn)
-        @template_text = File.read(fn)
+        # if it's already a path that includes the pages path, strip
+        # that to get the name.
+        if fn =~ /#{base_path}/
+          @template_name = fn[/^#{base_path}\/(.*)/,1]
+        else
+          @template_name = fn
+        end
+        
+        raise "Template #{fn} not found" unless File.exists?(template_filename)
+        @template_text = File.read(template_filename)
       else
+        @template_name = nil
         @template_text = nil
       end
     end  
     
-    def render_fmt(text)
-      result = text
-    
-      # need to get opts to a known state (array), and copy it
-      # so we can modify it.
-      if @format_opts && ((@format_opts.respond_to?(:to_ary) && (!@format_opts.empty?)) || @format_opts.is_a?(Symbol)) 
-        opts = @format_opts.respond_to?(:to_ary) ? @format_opts.dup : [@format_opts] 
-          
-        # Remove :rdoc opts from array (RedCloth doesn't do 'em) 
-        # and remember for after first rendering...
-        #
-        # Cope with multiple occurences of :rdoc
-        unless (rdoc_opt = opts.grep(:rdoc)).empty?
-          opts -= rdoc_opt
-        end
-          
-        # Render out RedCloth / markdown
-        unless opts.empty?
-          if defined?(RedCloth)
-            rc = RedCloth.new(result)
-            rc.instance_eval { @lite_mode = false }   # hack around a warning
-            result = rc.to_html(*opts) 
-          else
-            puts "WARN: RedCloth options specified but no RedCloth installed"
-          end
-        end
-          
-        # Render out Rdoc
-        #
-        # TODO could support alternative output formats by having the user supply
-        #      the formatter class (ToHtml etc).         
-        unless rdoc_opt.empty?
-          p = SM::SimpleMarkup.new
-          h = SM::ToHtml.new
-          result = p.convert(result, h)                      
-        end
+    def load_layout
+      if fn = layout_filename
+        raise "Layout #{fn} not found" unless File.exists?(fn)      
+        @layout_text = File.read(fn)
+        
+        # layout code     
+        cfn = Page::page_ruby_filename(fn)
+        instance_eval(File.read(cfn), cfn) if File.exists?(cfn)        
       end
-      
-      result
     end
     
     
+    def render_page_filters(text)
+      page_filters.inject(text) { |s, f| f.filter(s, self) }      
+    end    
+        
+    def render_post_filters(text)
+      post_filters.inject(text) { |s, f| f.filter(s, self) }      
+    end    
+        
     # render, set up @result for next time. Return result too.    
     def do_render!
       # Render the page content into the @content_for_layout
       unless @template_text.nil?
-        @content_for_layout = render_fmt( ERB.new(@template_text).result(binding) )
+        # default render_fmt does nothing - different page formats may redefine it.
+        erb = ERB.new(@template_text)
+        erb.filename = template_filename
+        @content_for_layout = render_page_filters( erb.result(binding) )
       end
       
+      # Load layout _after_ page eval, allowing page to override layout.
+      load_layout
+      
       # render into the layout if supplied.
       @result = if !@layout_text.nil?
-        ERB.new(@layout_text).result(binding)   
+        erb = ERB.new(@layout_text)
+        erb.filename = layout_filename
+        erb.result(binding)   
       else 
         @content_for_layout
       end 
       
+      @result = render_post_filters(@result)      
       freeze
       
       @result 
     end
         
-    # Get a full layout filename from a basename. If the basename has no extension,
-    # the default extension is added.
-    def layout_fn(basename) 
-      ext = File.extname(basename)
-      "#{@layout_path}/#{basename}#{@layout_defext if ext.empty?}"    
-    end
-    
-    # FIXME NASTY HACK: Allow templates to inherit COMMON.rb. This should be replaced
-    # with a proper search for inherited in Page.new. Call from your COMMON.rb to 
-    # inherit the COMMON.rb immediately above this. If none exists there, this doesn't go
-    # looking beyond that - it just returns false
-    def inherit_common
-      inh = "#{@fixme_dir}/../COMMON.rb"
-      if File.exists?(inh)
-        instance_eval(File.read(inh))
-        true              
-      else
-        false
-      end
-    end
-    
-    # FIXME NASTY HACK II: relative links (kinda works, but simply. Handy when
-    # you do both local preview from some deep directory, and remote deployment
-    # to a root)
-    def link_rel(href) 
-      thr = href
-      if thr.is_a?(String) && href[0,1] == '/'    # only interested in absolute
-        thr = href[1..href.length]     
-        count = @fixme_dir.split('/').length - 2
-        if count > 0 then count.times {
-          thr = '../' + thr
-        } end      
-      end
-      thr
+    def inherit_common    # inherit_common is implicit now    vv0.2.99  v-0.5
+      warn "Warning: inherit_common is deprecated (inheritance is now implicit)"
     end
-    
+        
+    # Find and evaluate all COMMON.rb files from page dir up to FS root.
+    def eval_common_rubys
+      common_rbs = Page::resolve_common_rubys(File.expand_path(File.dirname(template_filename)))            
+      common_rbs.each { |fn| instance_eval(File.read(fn),fn) }
+            
+      true
+    end # method
+          
   end #class  
 end #module