erbook 5.0.0 → 6.0.0

data/lib/erbook.rb

@@ -1,13 +1,21 @@
-# Project and release information.
-module ERBook
-  PROJECT = 'erbook'
-  VERSION = '5.0.0'
-  RELEASE = '2008-11-22'
-  WEBSITE = 'http://snk.tuxfamily.org/lib/erbook'
-  SUMMARY = 'Extensible document processor based on eRuby.'
-  DISPLAY = PROJECT + ' ' + VERSION
+require 'rubygems'
+require 'inochi'
+
+Inochi.init :ERBook,
+  :program => 'erbook',
+  :version => '6.0.0',
+  :release => '2009-01-19',
+  :website => 'http://snk.tuxfamily.org/lib/erbook/',
+  :tagline => 'Extensible document processor based on eRuby',
+  :require => {
+    # gems needed by the default 'xhtml' format
+    'maruku'  => '~> 0.5',
+    'coderay' => '>= 0.7',
+  }
 
-  INSTALL_DIR = File.expand_path File.join(File.dirname(__FILE__), '..')
-  FORMATS_DIR = File.join INSTALL_DIR, 'fmt'
+module ERBook
+  FORMATS_DIR = File.join(INSTALL, 'fmt')
   FORMAT_FILES = Dir[File.join(FORMATS_DIR, '*.yaml')]
 end
+
+require 'erbook/document'

data/lib/erbook/document.rb

@@ -0,0 +1,233 @@
+require 'yaml'
+require 'erbook/template'
+
+module ERBook
+  class Document
+    # Data from the format specification file.
+    attr_reader :format
+
+    # All root nodes in the document.
+    attr_reader :roots
+
+    # All nodes in the document.
+    attr_reader :nodes
+
+    # All nodes in the document arranged by node type.
+    attr_reader :nodes_by_type
+
+    ##
+    # @param [String] format
+    #   Either the short-hand name of a built-in format
+    #   or the path to a format specification file.
+    #
+    # @param [String] input_text
+    #   The body of the input document.
+    #
+    # @param [String] input_file
+    #   Name of the file from which the input document originated.
+    #
+    # @param [Hash] options
+    #   Additional method parameters:
+    #
+    #   [boolean] :unindent =>
+    #     If true, all node content is unindented hierarchically.
+    #
+    def initialize format, input_text, input_file, options = {}
+      # process format specification
+        @format_file = format.to_s
+
+        File.file? @format_file or
+          @format_file = File.join(ERBook::FORMATS_DIR, @format_file + '.yaml')
+
+        begin
+          @format = YAML.load_file(@format_file)
+          @format[:file] = File.expand_path(@format_file)
+          @format[:name] = File.basename(@format_file).sub(/\..*?$/, '')
+
+          if @format.key? 'code'
+            eval @format['code'].to_s, TOPLEVEL_BINDING, "#{@format_file}:code"
+          end
+
+        rescue Exception
+          error "Could not load format specification file #{@format_file.inspect}"
+        end
+
+        @node_defs = @format['nodes']
+
+      # process input document
+        begin
+          # create sandbox for input evaluation
+            template = Template.new(input_file, input_text, options[:unindent])
+
+            @template_vars = {
+              :@format        => @format,
+              :@roots         => @roots = [], # root nodes of all trees
+              :@nodes         => @nodes = [], # all nodes in the forest
+              :@nodes_by_type => @nodes_by_type = Hash.new {|h,k| h[k] = [] },
+              :@node_stack    => [], # stack for all nodes
+              :@index_stack   => [], # stack for nodes having index only
+            }.each_pair {|k,v| template.instance_variable_set(k, v) }
+
+            class << template
+              private
+
+              # Handles the method call from a node
+              # placeholder in the input document.
+              def __node__ node_type, *node_args, &node_content
+                node = Node.new(
+                  :type => node_type,
+                  :defn => @format['nodes'][node_type],
+                  :args => node_args,
+                  :children => [],
+
+                  # omit erbook internals from the stack trace
+                  :trace => caller.reject {|t|
+                    [$0, ERBook::INSTALL].any? {|f| t.index(f) == 0 }
+                  }
+                )
+                @nodes << node
+                @nodes_by_type[node.type] << node
+
+                # calculate occurrence number for this node
+                if node.defn['number']
+                  @count ||= Hash.new {|h,k| h[k] = []}
+                  node.number = (@count[node.type] << node).length
+                end
+
+                # assign node family
+                if parent = @node_stack.last
+                  parent.children << node
+                  node.parent = parent
+                  node.depth = parent.depth
+                  node.depth += 1 if node.defn['depth']
+
+                  # calculate latex-style index number for this node
+                  if node.defn['index']
+                    parent = @index_stack.last
+                    branches = parent.children.select {|n| n.index }
+                    node.index = [parent.index, branches.length + 1].join('.')
+                  end
+                else
+                  @roots << node
+                  node.parent = nil
+                  node.depth = 0
+
+                  # calculate latex-style index number for this node
+                  if node.defn['index']
+                    branches = @roots.select {|n| n.index }
+                    node.index = (branches.length + 1).to_s
+                  end
+                end
+
+                # assign node content
+                if block_given?
+                  @index_stack.push node if node.defn['index']
+                  @node_stack.push node
+                  content = content_from_block(node, &node_content)
+                  @node_stack.pop
+                  @index_stack.pop if node.defn['index']
+
+                  digest = Document.digest(content)
+                  self.buffer << digest
+                else
+                  content = nil
+                  digest = Document.digest(node.object_id)
+                end
+
+                node.content = content
+                node.digest = digest
+
+                digest
+              end
+            end
+
+            @node_defs.each_key do |type|
+              # XXX: using a string because define_method()
+              #      does not accept a block until Ruby 1.9
+              file, line = __FILE__, __LINE__ + 1
+              template.instance_eval %{
+                def #{type} *node_args, &node_content
+                  __node__ #{type.inspect}, *node_args, &node_content
+                end
+              }, file, line
+            end
+
+          # evaluate the input & build the document tree
+            @processed_document = template.instance_eval { result binding }
+
+          # chain block-level nodes together for local navigation
+            block_nodes = @nodes.reject {|n| @node_defs[n.type]['inline'] }
+
+            require 'enumerator'
+            block_nodes.each_cons(2) do |a, b|
+              a.next_node = b
+              b.prev_node = a
+            end
+
+          # replace node placeholders with their corresponding output
+            expander = lambda do |n, buf|
+              # calculate node output
+              source = "#{@format_file}:nodes:#{n.type}:output"
+              n.output = Template.new(
+                source, @node_defs[n.type]['output'].to_s.chomp
+              ).render_with(@template_vars.merge(:@node => n))
+
+              # expand all child nodes in this node's output
+              n.children.each {|c| expander[c, n.output] }
+
+              # replace this node's placeholder with its output in the buffer
+              buf[n.digest] = @node_defs[n.type]['silent'] ? '' : n.output
+            end
+
+            @roots.each {|n| expander[n, @processed_document] }
+
+        rescue Exception
+          puts input_text # so the user can debug line numbers in the stack trace
+          error "Could not process input document #{input_file.inspect}"
+        end
+    end
+
+    ##
+    # Returns the output of this document.
+    #
+    def to_s
+      Template.new("#{@format_file}:output", @format['output'].to_s).
+      render_with(@template_vars.merge(:@content => @processed_document))
+    end
+
+    require 'ostruct'
+    class Node < OpenStruct
+      # deprecated in Ruby 1.8; removed in Ruby 1.9
+      undef id if respond_to? :id
+      undef type if respond_to? :type
+
+      # Returns the output of this node.
+      def to_s
+        output
+      end
+    end
+
+    require 'digest/sha1'
+    ##
+    # Returns a digest of the given string that
+    # will not be altered by String#to_xhtml.
+    #
+    def Document.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
+
+    private
+
+    ##
+    # Prints the given message and raises the given error.
+    #
+    def error message, error = $!
+      STDERR.printf "%s:\n\n", message
+      raise error
+    end
+  end
+end

data/lib/erbook/template.rb

@@ -0,0 +1,210 @@
+require 'erb'
+require 'pathname'
+
+module ERBook
+  ##
+  # An eRuby template which allows 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
+
+    ##
+    # @param [String] 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
+    #   A string containing eRuby directives.
+    #
+    # @param [boolean] unindent
+    #   If true, then all content blocks will be unindented hierarchically,
+    #   by the leading space of their 'do' and 'end' delimiters.
+    #
+    # @param 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
+        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
+
+      self.filename = source
+    end
+
+    # Renders this template within a fresh object 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
+        inst_vars.each_pair do |var, val|
+          instance_variable_set var, val
+        end
+
+        binding
+      end
+
+      result context
+    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
+
+      if tail > head
+        @buffer.slice! head..tail
+      else
+        body
+      end.to_s
+    end
+  end
+end