erbook 6.1.0 → 7.0.0

data/lib/erbook/rdoc.rb

@@ -1,17 +1,23 @@
-# Workaround for: `rdoc --fmt xml` does not dump information about methods.
-
+# Workaround for `rdoc --fmt xml` not dumping information about methods.
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
+require 'rubygems'
+gem 'rdoc', '>= 2.4.3', '< 2.5'
 require 'rdoc/rdoc'
 
 module RDoc
   class TopLevel
     # Returns an array of all classes recorded thus far.
     def self.all_classes
-      @@all_classes.values
+      @all_classes.values
     end
 
     # Returns an array of all modules recorded thus far.
     def self.all_modules
-      @@all_modules.values
+      @all_modules.values
     end
 
     # Returns an array of RDoc::AnyMethod objects
@@ -25,10 +31,10 @@ module RDoc
     def self.refresh_all_classes_and_modules
       visit = lambda do |node|
         if node.is_a? NormalClass or node.is_a? SingleClass
-          @@all_classes[node.full_name] = node
+          @all_classes[node.full_name] = node
 
         elsif node.is_a? NormalModule
-          @@all_modules[node.full_name] = node
+          @all_modules[node.full_name] = node
         end
 
         (node.classes + node.modules).each {|n| visit[n] }
@@ -48,14 +54,15 @@ module RDoc
     # RDoc will ignore the given code string!  :-(
     #
     def self.parse aCodeString, aFileName = __FILE__
-      top = ParserFactory.parser_for(
-        TopLevel.new(aFileName), aFileName,
-        aCodeString, DummyOptions.new, Stats.new
-      ).scan
+      tl = TopLevel.new(aFileName)
+      op = DummyOptions.new
+      st = Stats.new(0)
+
+      result = Parser.for(tl, aFileName, aCodeString, op, st).scan
 
       refresh_all_classes_and_modules
 
-      top
+      result
     end
 
     # Returns a RDoc::TopLevel object containing information

data/lib/erbook/template.rb

@@ -1,210 +1,120 @@
-require 'erb'
-require 'pathname'
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
+require 'ember'
 
 module ERBook
   ##
-  # An eRuby template which allows access to the underlying result
+  # eRuby template that provides access to the underlying result
   # buffer (which contains the result of template evaluation thus
   # far) and provides sandboxing for isolated template rendering.
   #
-  # In addition to the standard <% eRuby %> directives, this template supports:
-  #
-  # * Lines that begin with '%' are treated as normal eRuby directives.
-  #
-  # * Include directives (<%#include YOUR_PATH #%>) are replaced by the result
-  #   of reading and evaluating the YOUR_PATH file in the current context.
-  #
-  #   * Unless YOUR_PATH is an absolute path, it is treated as being
-  #     relative to the file which contains the include directive.
-  #
-  #   * Errors originating from included files are given a proper
-  #     stack trace which shows the chain of inclusion plus any
-  #     further trace steps originating from the included file itself.
-  #
-  # * eRuby directives delimiting Ruby blocks (<% ...  do %>
-  #   ...  <% end %>) can be heirarchically unindented by the
-  #   crown margin of the opening (<% ...  do %>) delimiter.
-  #
-  class Template < ERB
-    # The result of template evaluation thus far.
-    attr_reader :buffer
+  class Template < Ember::Template
+    attr_reader :sandbox
 
     ##
-    # @param [String] source
+    # ==== Parameters
+    #
+    # [source]
     #   Replacement for the ambiguous '(erb)' identifier in stack traces;
     #   so that the user can better determine the source of an error.
     #
-    # @param [String] input
+    # [input]
     #   A string containing eRuby directives.
     #
-    # @param [boolean] unindent
+    # [unindent]
     #   If true, then all content blocks will be unindented hierarchically,
-    #   by the leading space of their 'do' and 'end' delimiters.
     #
-    # @param safe_level
+    # [safe_level]
     #   See safe_level in ERB::new().
     #
-    def initialize source, input, unindent = false, safe_level = nil
-      # expand all "include" directives in the input
-        expander = lambda do |src_file, src_text, path_stack, stack_trace|
-          src_path = File.expand_path(src_file)
-          src_line = 1 # line number of the current include directive in src_file
-
-          chunks = src_text.split(/<%#\s*include\s+(.+?)\s*#%>/)
-
-          path_stack.push src_path
-          chunks.each_with_index do |chunk, i|
-            # even number: chunk is not an include directive
-            if i & 1 == 0
-              src_line += chunk.count("\n")
-
-            # odd number: chunk is the target of the include directive
-            else
-              # resolve correct path of target file
-                dst_file = chunk
-
-                unless Pathname.new(dst_file).absolute?
-                  # target is relative to the file in
-                  # which the include directive exists
-                  dst_file = File.join(File.dirname(src_file), dst_file)
-                end
-
-                dst_path = File.expand_path(dst_file)
-
-              # include the target file
-                if path_stack.include? dst_file
-                  raise "Cannot include #{dst_file.inspect} at #{src_file.inspect}:#{src_line} because that would cause an infinite loop in the inclusion stack: #{path_stack.inspect}."
-                else
-                  stack_trace.push "#{src_path}:#{src_line}"
-                  dst_text = eval('File.read dst_file', binding, src_file, src_line)
-
-                  # recursively expand any include directives within
-                  # the expansion of the current include directive
-                  dst_text = expander[dst_file, dst_text, path_stack, stack_trace]
-
-                  # provide more accurate stack trace for
-                  # errors originating from included files
-                  line_var = "__erbook_var_#{dst_file.object_id.abs}__"
-                  dst_text = %{<%
-                    #{line_var} = __LINE__ + 2 # content is 2 newlines below
-                    begin
-                      %>#{dst_text}<%
-                    rescue Exception => err
-                      bak = err.backtrace
-
-                      top = []
-                      found_top = false
-                      prev_line = nil
-
-                      bak.each do |step|
-                        if step =~ /^#{/#{source}/}:(\\d+)(.*)/
-                          line, desc = $1, $2
-                          line = line.to_i - #{line_var} + 1
-
-                          if line > 0 and line != prev_line
-                            top << "#{dst_path}:\#{line}\#{desc}"
-                            found_top = true
-                            prev_line = line
-                          end
-                        elsif !found_top
-                          top << step
-                        end
-                      end
-
-                      if found_top
-                        bak.replace top
-                        bak.concat #{stack_trace.reverse.inspect}
-                      end
-
-                      raise err
-                    end
-                  %>}
-
-                  stack_trace.pop
-                end
-
-                chunks[i] = dst_text
-            end
-          end
-          path_stack.pop
-
-          chunks.join
-        end
-
-        input = expander[source, input, [], []]
-
-      # convert "% at beginning of line" usage into <% normal %> usage
-        input.gsub! %r{^([ \t]*)(%[=# \t].*)$}, '\1<\2 %>'
-        input.gsub! %r{^([ \t]*)%%}, '\1%'
-
-      # unindent node content hierarchically
-        if unindent
-          tags = input.scan(/<%(?:.(?!<%))*?%>/m)
-          margins = []
-          result = []
-
-          buffer = input
-          tags.each do |tag|
-            chunk, buffer = buffer.split(tag, 2)
-            chunk << tag
-
-            # perform unindentation
-            result << chunk.gsub(/^#{margins.last}/, '')
-
-            # prepare for next unindentation
-            case tag
-            when /<%[^%=].*?\bdo\b.*?%>/m
-              margins.push buffer[/^[ \t]*(?=\S)/]
-
-            when /<%\s*end\s*%>/m
-              margins.pop
-            end
-          end
-          result << buffer
-
-          input = result.join
+    def initialize source, input, unindent = true, safe_level = nil
+      super input,
+        :result_variable => :@buffer,
+        :source_file     => source,
+        :unindent        => unindent,
+        :shorthand       => true,
+        :infer_end       => true
+
+      @sandbox = Sandbox.new
+
+      if $DEBUG
+        IO.popen('cat -n', 'w+') do |io|
+          io.write self.program
+          io.close_write
+          STDERR.puts io.read
         end
+      end
+    end
 
-      # silence the code-only <% ... %> directive, just like PHP does
-        input.gsub! %r{^[ \t]*(<%[^%=]((?!<%).)*?[^%]%>)[ \t]*\r?\n}m, '\1'
-
-      # use @buffer to store the result of the ERB template
-      super input, safe_level, nil, :@buffer
+    ##
+    # Returns the output of evaluating this template inside the given context.
+    #
+    # If no context is given, then the sandbox of this template is used.
+    #
+    def render
+      super @sandbox.instance_eval('binding')
+    end
 
-      self.filename = source
+    ##
+    # Returns the result of template evaluation thus far.
+    #
+    def buffer
+      @sandbox.instance_variable_get(:@buffer)
     end
 
-    # Renders this template within a fresh object that is populated with
+    ##
+    # Renders this template within a fresh sandbox that is populated with
     # the given instance variables, whose names must be prefixed with '@'.
+    #
     def render_with inst_vars = {}
-      context = Object.new.instance_eval do
+      old_sandbox = @sandbox
+
+      begin
+        @sandbox = Sandbox.new
+
         inst_vars.each_pair do |var, val|
-          instance_variable_set var, val
+          @sandbox.instance_variable_set var, val
         end
 
-        binding
-      end
+        render
 
-      result context
+      ensure
+        @sandbox = old_sandbox
+      end
     end
 
-    protected
-
-    # 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 *block_args
-      raise ArgumentError, 'block must be given' unless block_given?
-
-      head = @buffer.length
-      body = yield(*block_args) # this appends 'content' to '@buffer'
-      tail = @buffer.length
+    ##
+    # Environment for template evaluation.
+    #
+    class Sandbox
+      ##
+      # Returns an array of things 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 inside an array.
+      #
+      def __block_content__ *block_args
+        raise ArgumentError, 'block must be given' unless block_given?
+
+        original = @buffer
+
+        begin
+          block_content = @buffer = []
+          return_value  = yield(*block_args) # this appends content to @buffer
+        ensure
+          @buffer = original
+        end
 
-      if tail > head
-        @buffer.slice! head..tail
-      else
-        body
-      end.to_s
+        if block_content.empty?
+          [return_value]
+        else
+          block_content
+        end
+      end
     end
   end
 end

data/lib/erbook/to_xhtml.rb

@@ -4,13 +4,18 @@
 # This particular implementation features the Markdown
 # formatting system via Maruku, syntax coloring via CodeRay,
 # and smart source code sizing (block versus inline display).
+#--
+# Copyright 2006 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
 
 require 'cgi'
+require 'digest/sha1'
 
 begin
   require 'rubygems'
   gem 'maruku', '~> 0.5'
-  gem 'coderay', '>= 0.7'
+  gem 'coderay', '>= 0.8'
 rescue LoadError
 end
 
@@ -22,23 +27,33 @@ class String
   # they are being processed by Textile.  By doing this, we
   # avoid unwanted Textile transformations, such as quotation
   # marks becoming curly ( ), in source code.
-  PROTECTED_TAGS = %w[tt code pre]
+  PROTECTED_TAGS = {
+    :pre  => :block,    # tag => is it a block or inline element?
+    :code => :inline,
+    :tt   => :inline
+  }
 
   # The content of these XHTML tags will be preserved
   # *verbatim* throughout the text-to-XHTML conversion process.
-  VERBATIM_TAGS = %w[noformat]
+  VERBATIM_TAGS = {
+    :noformat => :block # tag => is it a block or inline element?
+  }
 
+  ##
   # Transforms this string into an *inline* XHTML string (one that
   # does not contain any block-level XHTML elements at the root).
+  #
   def to_inline_xhtml
     to_xhtml true
   end
 
+  ##
   # Transforms this string into XHTML while ensuring that the
   # result contains one or more block-level elements at the root.
   #
-  # inline:: If true, the resulting XHTML will *not*
-  #          contain a block-level element at the root.
+  # [inline]
+  #   If true, the resulting XHTML will *not*
+  #   contain a block-level element at the root.
   #
   def to_xhtml inline = false
     with_protected_tags(self, VERBATIM_TAGS, true) do |text|
@@ -63,51 +78,85 @@ class String
     end
   end
 
+  ##
   # Returns the result of running this string through Maruku.
   #
-  # inline:: If true, the resulting XHTML will *not*
-  #          be wrapped in a XHTML paragraph element.
+  # [inline]
+  #   If true, the resulting XHTML will *not*
+  #   be wrapped in a XHTML paragraph element.
   #
   def thru_maruku inline = false #:nodoc:
-    html = Maruku.new(self).to_html
+    #
+    # XXX: add a newline at the beginning of the text to
+    #      prevent Maruku from interpreting the first line
+    #      of text as a parameter definition, which is the
+    #      case if that first line matches /\S{2}: /
+    #
+    #      see this bug report for details:
+    #      http://rubyforge.org/tracker/?func=detail&atid=10735&aid=25697&group_id=2795
+    #
+    html = Maruku.new("\n#{self}").to_html
     html.sub! %r{\A<p>(.*)</p>\Z}, '\1' if inline
     html
   end
 
-  # Adds syntax coloring to <code> elements in the given text.  If the
-  # <code> tag has an attribute lang="...", then that is considered the
-  # programming language for which appropriate syntax coloring should be
-  # applied.  Otherwise, the programming language is assumed to be ruby.
+  ##
+  # Adds syntax coloring to <code> elements in this string.
+  #
+  # Each <code> element is annotated with a class="line"
+  # or a class="para" attribute, according to whether it
+  # spans a single line or multiple lines of code.
+  #
+  # In the latter case, the <code> element is replaced with a <pre> element
+  # so that its multi-line body appears correctly in text-mode web browsers.
+  #
+  # If a <code> element has a lang="..." attribute,
+  # then that attribute's value is considered to be
+  # the programming language for which appropriate
+  # syntax coloring should be applied.  Otherwise,
+  # the programming language is assumed to be ruby.
+  #
   def thru_coderay #:nodoc:
     gsub %r{<(code)(.*?)>(.*?)</\1>}m do
-      atts, code = $2, CGI.unescapeHTML($3).sub(/\A\r?\n/, '')
+      elem, atts, code = $1, $2, CGI.unescapeHTML($3).sub(/\A\r?\n/, '')
       lang = atts[/\blang=('|")(.*?)\1/i, 2] || :ruby
 
-      html = CodeRay.scan(code, lang).html(:css => :style)
-      tag = if code =~ /\n/ then :pre else :code end
+      body = CodeRay.scan(code, lang).html(:css => :style)
+
+      if code =~ /\n/
+        span = :para
+        head = "<ins><pre"
+        tail = "</pre></ins>"
+
+      else
+        span = :line
+        head = "<#{elem}"
+        tail = "</#{elem}>"
+      end
 
-      %{<#{tag} class="code"#{atts}>#{html}</#{tag}>}
+      %{#{head} class="#{span}"#{atts}>#{body}#{tail}}
     end
   end
 
   private
 
+  ##
   # Protects the given tags in the given input, passes
   # that protected input to the given block, restores the
   # given tags in the result of the block and returns it.
   #
-  # verbatim:: If true, the content of the elments having the
-  #            given tags will not be temporarily altered so
-  #            that process nested elements can be processed.
+  # [verbatim]
+  #   If true, the content of the elments having the given tags will not be
+  #   temporarily altered so that process nested elements can be processed.
   #
-  def with_protected_tags input, tags, verbatim #:nodoc: :yields: input
+  def with_protected_tags input, tag_defs, verbatim #:yields: input
     raise ArgumentError unless block_given?
 
     input = input.dup
     escapes = {}
 
     # protect the given tags by escaping them
-    tags.each do |tag|
+    tag_defs.each_key do |tag|
       input.gsub! %r{(<#{tag}.*?>)(.*?)(</#{tag}>)}m do
         head, body, tail = $1, $2, $3
 
@@ -123,7 +172,7 @@ class String
             head << CGI.escapeHTML(CGI.unescapeHTML(body)) << tail
           end
 
-        escaped = ERBook::Document.digest(original)
+        escaped = calc_digest(original)
         escapes[escaped] = original
 
         escaped
@@ -136,12 +185,36 @@ class String
     # restore the protected tags by unescaping them
     until escapes.empty?
       escapes.each_pair do |esc, orig|
-        if output.gsub! esc, orig
-          escapes.delete esc
-        end
+        tag = orig[/<\/(.+?)>\s*\z/, 1].to_sym
+        raise ArgumentError, tag unless tag_defs.key? tag
+
+        restore_ok =
+          case tag_defs[tag]
+          when :inline
+            # process inline elements normally
+            output.gsub! esc, orig
+
+          when :block
+            # pull block-level elements out of paragraph tag added by Maruku
+            output.gsub!(/(<p>\s*)?#{Regexp.quote esc}/){ orig + $1.to_s }
+          end
+
+        escapes.delete esc if restore_ok
       end
     end
 
     output
   end
+
+  ##
+  # Returns a digest of the given string that
+  # will not be altered by String#to_xhtml.
+  #
+  def calc_digest input
+    Digest::SHA1.hexdigest(input.to_s).
+
+    # XXX: surround all digits with alphabets so
+    #      Maruku doesn't change them into HTML
+    gsub(/\d/, 'z\&z')
+  end
 end