walrus 0.1

data/lib/walrus/runner.rb

@@ -0,0 +1,356 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id: /mirrors/Walrus/trunk/walrus/lib/walrus/runner.rb 6751 2007-04-12T16:56:29.067618Z wincent  $
+
+require 'walrus'
+require 'fileutils'
+require 'optparse'
+require 'ostruct'
+require 'pathname'
+require 'rubygems'
+require 'wopen3'
+
+module Walrus
+  
+  class Runner
+    
+    class Error < Exception ; end
+
+    class ArgumentError < Error ; end
+    
+    def initialize
+      
+      @options = OpenStruct.new
+      @options.output_dir         = nil
+      @options.input_extension    = 'tmpl'
+      @options.output_extension   = 'html'
+      @options.recurse            = false
+      @options.backup             = true
+      @options.force              = false
+      @options.debug              = false
+      @options.halt               = false
+      @options.dry                = false
+      @options.verbose            = false
+      
+      @command  = nil # "compile", "fill" (saves to disk), "run" (prints to standard out)
+      @inputs   = []  # list of input files and/or directories
+      parser    = OptionParser.new do |o|
+        
+        o.banner  = "Usage: #{o.program_name} command input-file(s)-or-directory/ies [options]"
+        o.separator ''
+        o.separator '   _____________'
+        o.separator '  /             \\'
+        o.separator " /     o   o     \\  #{o.program_name}"
+        o.separator ' |       b       |  Command-line front-end for the Walrus templating system'
+        o.separator '  \\   ~-----~   /   Copyright 2007 Wincent Colaiuta'
+        o.separator '   \\ / /   \\ \\ /'
+        o.separator '    / /-----\\ \\'
+        o.separator '   |_/       \\_|'
+        o.separator ''
+        o.separator 'Commands: compile -- compile templates to Ruby code'
+        o.separator '          fill    -- runs compiled templates, writing output to disk'
+        o.separator '          run     -- runs compiled templates, printing output to standard output'
+        o.separator ''
+        
+        o.on('-o', '--output-dir DIR', 'Output directory (when filling)', 'defaults to same directory as input file') do |opt|
+          @options.output_dir = Pathname.new(opt)
+        end
+        
+        o.on('-i', '--input-extension EXT', 'Extension for input file(s)', 'default: tmpl') do |opt|
+          @options.input_extension = opt
+        end
+        
+        o.on('-e', '--output-extension EXT', 'Extension for output file(s) (when filling)', 'default: html') do |opt|
+          @options.output_extension = opt
+        end
+        
+        o.on('-R', 'Search subdirectories recursively for input files', 'default: on') do |opt|
+          @options.recurse = opts
+        end
+        
+        o.on('-b', '--[no-]backup', 'Make backups before overwriting', 'default: on') do |opt|
+          @options.backup = opt
+        end
+        
+        o.on('-f', '--force', 'Force a recompile (when filling)', 'default: off (files only recompiled if source newer than output)') do |opt|
+          @options.force = opt
+        end
+        
+        o.on('--halt', 'Halts on encountering an error (even a non-fatal error)', 'default: off') do |opt|
+          @options.halt = opt
+        end
+        
+        o.on('-t', '--test', 'Performs a "dry" (test) run', 'default: off') do |opt|
+          @options.dry = opt
+        end
+        
+        o.on('-d', '--debug', 'Print debugging information to standard error', 'default: off') do |opt|
+          @options.debug = opt
+        end
+        
+        o.on('-v', '--verbose', 'Run verbosely', 'default: off') do |opt|
+          @options.verbose = opt
+        end
+        
+        o.separator ''
+        
+        o.on_tail('-h', '--help', 'Show this message') do
+          $stderr.puts o
+          exit
+        end
+        
+        o.on_tail('--version', 'Show version') do
+          $stderr.puts 'Walrus ' + Walrus::VERSION
+          exit
+        end
+        
+      end
+      
+      begin
+        parser.parse!
+      rescue OptionParser::InvalidOption => e
+        raise ArgumentError.new(e)
+      end
+      
+      parser.order! do |item|
+        if @command.nil? :  @command = item               # get command first ("compile", "fill" or "run")
+        else                @inputs << Pathname.new(item) # all others (and there must be at least one) are file or directory names
+        end
+      end
+      
+      raise ArgumentError.new('no command specified') if @command.nil?
+      raise ArgumentError.new('no inputs specified') unless @inputs.length > 0
+    end
+    
+    def run
+      log "Beginning processing: #{Time.new.to_s}."
+      
+      # TODO: flush memoizing cache after each file
+      
+      expand(@inputs).each do |input|
+        case @command
+        when 'compile'
+          log "Compiling '#{input}'."
+          compile(input)
+        when 'fill'
+          log "Filling '#{input}'."
+          compile_if_needed(input)
+          begin
+            write_string_to_path(get_output(input), filled_output_path_for_input(input))
+          rescue Exception => e
+            handle_error(e)
+          end
+        when 'run'
+          log "Running '#{input}'."
+          compile_if_needed(input)
+          begin
+            printf('%s', get_output(input))
+            $stdout.flush
+          rescue Exception => e
+            handle_error(e)
+          end
+        else
+          raise ArgumentError.new("unrecognized command '#{@command}'")
+        end
+      end
+      log "Processing complete: #{Time.new.to_s}."
+    end
+    
+    # Expects an array of Pathname objects.
+    # Directory inputs are themselves recursively expanded if the "recurse" option is set to true; otherwise only their top-level entries are expanded.
+    # Returns an expanded array of Pathname objects.
+    def expand(inputs)
+      expanded = []
+      inputs.each do |input|
+        if input.directory?
+          input.entries.each do |entry|
+            if entry.directory?
+              if @options.recurse
+                expanded.concat expand(entry.entries)
+              end
+            else # not a directory
+              expanded << entry
+            end
+          end
+        else # not a directory
+          expanded << input
+        end
+      end
+      expanded
+    end
+    
+    def compile_if_needed(input)
+      compile(input, false)
+    end
+    
+    def compiled_path_older_than_source_path(compiled_path, source_path)
+      begin
+        compiled  = File.mtime(compiled_path)
+        source    = File.mtime(source_path)
+      rescue SystemCallError # perhaps one of them doesn't exist
+        return true
+      end
+      compiled < source
+    end
+    
+    def compile(input, force = true)
+      template_source_path  = template_source_path_for_input(input)
+      compiled_path         = compiled_source_path_for_input(input)
+      if force or @options.force or not compiled_path.exist? or compiled_path_older_than_source_path(compiled_path, template_source_path)
+        begin
+          template = Template.new(template_source_path)
+        rescue Exception => e
+          handle_error("failed to read input template '#{template_source_path}' (#{e.to_s})")
+          return
+        end
+        
+        begin
+          compiled = template.compile
+        rescue Grammar::ParseError => e
+          handle_error("failed to compile input template '#{template_source_path}' (#{e.to_s})")
+          return
+        end
+        
+        write_string_to_path(compiled, compiled_path, true)
+        
+      end
+      
+    end
+    
+    def get_output(input)
+      if @options.dry
+        "(no output: dry run)\n"
+      else
+        # use Wopen3 (backticks choke if there is a space in the path, open3 throws away the exit status)
+        output = ''
+        Wopen3.popen3([compiled_source_path_for_input(input).realpath, '']) do |stdin, stdout, stderr|
+          threads = []
+          threads << Thread.new(stdout) do |out|
+            out.each { |line| output << line }
+          end
+          threads << Thread.new(stderr) do |err|
+            err.each { |line| STDERR.puts line }
+          end
+          threads.each { |thread| thread.join }      
+        end
+        status = $?.exitstatus
+        raise SystemCallError.new("non-zero exit status (#{status})") if status != 0
+        output
+      end
+    end
+    
+    def write_string_to_path(string, path, executable = false)
+      
+      if @options.dry
+        log "Would write '#{path}' (dry run)."
+      else
+        
+        unless path.dirname.exist?
+          begin
+            log "Creating directory '#{path.dirname}'."
+            FileUtils.mkdir_p path.dirname
+          rescue SystemCallError => e
+            handle_error(e)
+            return
+          end
+        end
+        
+        log "Writing '#{path}'."
+        begin
+          File.open(path, "a+") do |f|
+            if not File.zero? path and @options.backup
+              log "Making backup of existing file at '#{path}'."
+              dir, base = path.split
+              FileUtils.cp path, dir + "#{base.to_s}.bak"
+            end
+            f.flock File::LOCK_EX
+            f.truncate 0
+            f.write string
+            f.chmod 0744 if executable
+          end
+        rescue SystemCallError => e
+          handle_error(e)
+        end
+      end
+    end
+    
+    def adjusted_output_path(path)
+      if @options.output_dir
+        if path.absolute?
+          path = @options.output_dir + path.to_s.sub(/\A\//, '')
+        else
+          path = @options.output_dir + path
+        end
+      else
+        path
+      end
+    end
+    
+    # If "input" already has the right extension it is returned unchanged.
+    # If the "input extension" is zero-length then "input" is returned unchanged.
+    # Otherwise the "input extension" is added to "input" and returned.
+    def template_source_path_for_input(input)
+      return input if input.extname == ".#{@options.input_extension}" # input already has the right extension
+      return input if @options.input_extension.length == 0            # zero-length extension, nothing to add
+      dir, base = input.split      
+      dir + "#{base.to_s}.#{@options.input_extension}"                # otherwise, add extension and return
+    end
+    
+    def compiled_source_path_for_input(input)
+      
+      # remove input extension if present
+      if input.extname == ".#{@options.input_extension}" and @options.input_extension.length > 0
+        dir, base = input.split
+        input = dir + base.basename(base.extname)
+      end
+      
+      # add rb as an extension
+      dir, base = input.split
+      dir + "#{base.to_s}.rb"
+    end
+    
+    def filled_output_path_for_input(input)
+      
+      # remove input extension if present
+      if input.extname == ".#{@options.input_extension}" and @options.input_extension.length > 0
+        dir, base = input.split
+        input = dir + base.basename(base.extname)
+      end
+      
+      # add output extension if appropriate
+      if @options.output_extension.length > 0
+        dir, base = input.split
+        adjusted_output_path(dir + "#{base.to_s}.#{@options.output_extension}")
+      else
+        adjusted_output_path(input)
+      end
+      
+    end
+    
+  private
+    
+    # Writes "message" to standard error if user supplied the "--verbose" switch.
+    def log(message)
+      if @options.verbose
+        $stderr.puts message
+      end
+    end
+    
+    # If the user supplied the "--halt" switch raises an Runner::Error exception based on "message". Otherwise merely prints "message" to the standard error.
+    def handle_error(message)
+      if @options.halt
+        raise Error.new(message)
+      else
+        $stderr.puts message
+      end
+    end
+    
+    
+  end # class Runner
+  
+end # module Walrus
+

data/lib/walrus/template.rb

@@ -0,0 +1,75 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id: /mirrors/Walrus/trunk/walrus/lib/walrus/template.rb 6730 2007-04-11T13:48:51.166868Z wincent  $
+
+require 'walrus'
+
+module Walrus
+  class Template
+    
+    attr_reader   :base_text
+    
+    # If initialized using a Pathname or File, returns the pathname. Otherwise returns nil.
+    attr_reader   :origin
+    
+    # Accepts input of class String, Pathname or File
+    def initialize(input)
+      raise ArgumentError if input.nil?
+      if input.respond_to? :read # should work with Pathname or File
+        @base_text  = input.read
+        @origin     = input.to_s
+      else
+        @base_text  = input.to_s.clone
+      end
+    end
+    
+    # The fill method returns a string containing the output produced when executing the compiled template.
+    def fill
+      @filled ||= instance_eval(compiled)
+    end
+    
+    def filled
+      fill
+    end
+    
+    # Parses template, returning compiled input (suitable for writing to disk).
+    def compile
+      @parser   ||= Parser.new
+      @compiled ||= @parser.compile(@base_text, :class_name => class_name, :origin => @origin)
+    end
+    
+    # Returns the compiled text of the receiver
+    def compiled
+      compile
+    end
+    
+    # Prints output obtained by running the compiled template.
+    def run
+      p fill
+    end
+    
+    def class_name
+      if @class_name
+        @class_name
+      else
+        if @origin.nil? : @class_name = Compiler::DEFAULT_CLASS # "DocumentSubclass"
+        else              @class_name = strip_extensions(@origin).to_class_name
+        end
+      end
+    end
+    
+    def strip_extensions(path)
+      extension = File.extname(path)
+      if extension != ""  # recurse
+        strip_extensions File.basename(path, extension) 
+      else                # no more extensions
+        path
+      end
+    end
+    
+  end # class Template
+end # module Walrus

data/lib/walrus/walrus_grammar/assignment_expression.rb

@@ -0,0 +1,24 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id: /mirrors/Walrus/trunk/walrus/lib/walrus/walrus_grammar/assignment_expression.rb 6701 2007-04-09T14:55:55.352472Z wincent  $
+
+require 'walrus/parser.rb' # make sure that RawText class has been defined prior to extending it
+
+module Walrus
+  class WalrusGrammar
+    
+    class AssignmentExpression
+      
+      def compile(options = {})
+        @lvalue.source_text + '=' + @expression.source_text
+      end
+      
+    end # class AssignmentExpression
+    
+  end # class WalrusGrammar
+end # Walrus
+

data/lib/walrus/walrus_grammar/block_directive.rb

@@ -0,0 +1,28 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus/parser.rb' # make sure that RawText class has been defined prior to extending it
+
+module Walrus
+  class WalrusGrammar
+    
+    class BlockDirective
+      
+      # Returns a string containing the compiled (Ruby) version of receiver.
+      def compile(options = {})
+        inner, outer = super
+        inner = '' if inner.nil?
+        inner << "lookup_and_accumulate_placeholder(#{@identifier.to_s.to_sym.inspect})\n"
+        [inner, outer]
+      end
+      
+    end # class BlockDirective
+    
+  end # class WalrusGrammar
+end # Walrus
+

data/lib/walrus/walrus_grammar/comment.rb

@@ -0,0 +1,24 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus/parser.rb' # make sure that RawText class has been defined prior to extending it
+
+module Walrus
+  class WalrusGrammar
+    
+    class Comment
+      
+      def compile(options = {})
+        '# Comment:' + @lexeme.to_s + "\n"
+      end
+      
+    end
+    
+  end # class WalrusGrammar
+end # Walrus
+

data/lib/walrus/walrus_grammar/def_directive.rb

@@ -0,0 +1,64 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id: /mirrors/Walrus/trunk/walrus/lib/walrus/walrus_grammar/def_directive.rb 6719 2007-04-10T15:00:33.886928Z wincent  $
+
+require 'walrus/parser.rb' # make sure that RawText class has been defined prior to extending it
+
+module Walrus
+  class WalrusGrammar
+    
+    class DefDirective
+      
+      # Returns a string containing the compiled (Ruby) version of receiver.
+      def compile(options = {})
+        internal = ''
+        
+        if @params == []
+          external = "def #{@identifier.to_s}\n"
+        else
+          # this will work for the simple case where params are plain identifiers
+          params = (@params.kind_of? Array) ? @params : [@params]
+          param_list  = params.collect { |param| param.compile }.join(', ')
+          external = "def #{@identifier.to_s}(#{param_list})\n"
+        end
+        
+        nested  = nil
+        
+        if @content.respond_to? :each   : content = @content
+        else                              content = [@content]
+        end
+        
+        content.each do |element|
+          if element.kind_of? WalrusGrammar::DefDirective # must handle nested def blocks here
+            inner, outer = element.compile(options)
+            nested = ['', ''] if nested.nil?
+            external << inner if inner
+            nested[1] << "\n" + outer
+          else
+            # again, may wish to forget the per-line indenting here if it breaks sensitive directive types
+            # (#ruby blocks for example, which might have here documents)
+            element.compile(options).each do |lines| # may return a single line or an array of lines
+              lines.each { |line| external << '  ' + line }
+            end
+          end
+        end
+        
+        external << "end\n\n"
+        
+        if nested
+          external << nested[1]
+        end
+        
+        internal = nil if internal == '' # better to return nil than an empty string here (which would get indented needlessly)
+        [internal, external]
+      end
+      
+    end # class DefDirective
+    
+  end # class WalrusGrammar
+end # Walrus
+

data/lib/walrus/walrus_grammar/echo_directive.rb

@@ -0,0 +1,44 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id: /mirrors/Walrus/trunk/walrus/lib/walrus/walrus_grammar/echo_directive.rb 6701 2007-04-09T14:55:55.352472Z wincent  $
+
+require 'walrus/parser.rb' # make sure that RawText class has been defined prior to extending it
+
+module Walrus
+  class WalrusGrammar
+    
+    class EchoDirective
+      
+      def compile(options = {})
+        
+        if @expression.respond_to? :each
+          expression = @expression
+        else
+          expression = [@expression]
+        end
+        
+        # TODO: potentially include line, col and file name info in the comments generated by the compiler
+        
+        compiled  = ''
+        first     = true
+        expression.each do |expr|
+          if first
+            compiled << "accumulate(instance_eval { %s }) # Echo directive\n" % expr.compile
+            first = false
+          else
+            compiled << "accumulate(instance_eval { %s }) # Echo directive (continued)\n" % expr.compile
+          end
+        end
+        compiled
+        
+      end
+      
+    end # class EchoDirective
+    
+  end # class WalrusGrammar
+end # Walrus
+

data/lib/walrus/walrus_grammar/escape_sequence.rb

@@ -0,0 +1,24 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus/parser.rb' # make sure that RawText class has been defined prior to extending it
+
+module Walrus
+  class WalrusGrammar
+    
+    class EscapeSequence
+      
+      def compile(options = {})
+        "accumulate(%s) \# EscapeSequence\n" % @lexeme.to_s.dump
+      end
+      
+    end
+    
+  end # class WalrusGrammar
+end # Walrus
+

data/lib/walrus/walrus_grammar/import_directive.rb

@@ -0,0 +1,44 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus/parser.rb' # make sure that the class has been defined prior to extending it
+require 'ostruct'
+
+module Walrus
+  class WalrusGrammar
+    
+    class ImportDirective
+      
+      # Returns an OpenStruct encapsulating information about the receiver for use by the compiler
+      def compile(options = {})
+        info = OpenStruct.new
+        path = Pathname.new @class_name.lexeme.to_s
+        
+        if path.absolute?
+          # it will work just fine as it is
+          info.class_name   = path.basename.to_s.to_class_name
+          info.require_line = "require '#{path.to_s}'"
+        else
+          dir, base       = path.split
+          info.class_name = base.to_s.to_class_name
+          if dir.to_s == '.'
+            # desired template is in the same directory
+            info.require_line = "require File.join(File.dirname(__FILE__), '#{base.to_s}').to_s"
+          else
+            # desired template is in a relative directory
+            info.require_line = "require File.join(File.dirname(__FILE__), '#{dir.to_s}', '#{base.to_s}').to_s"
+          end
+        end  
+        info
+      end
+      
+    end # class ImportDirective
+    
+  end # class WalrusGrammar
+end # Walrus
+