haml_ejs 0.0.1

data/lib/haml/engine.rb

@@ -0,0 +1,312 @@
+require 'haml/helpers'
+require 'haml/buffer'
+require 'haml/parser'
+require 'haml/compiler'
+require 'haml/filters'
+require 'haml/error'
+
+module Haml
+  # This is the frontend for using Haml programmatically.
+  # It can be directly used by the user by creating a
+  # new instance and calling \{#render} to render the template.
+  # For example:
+  #
+  #     template = File.read('templates/really_cool_template.haml')
+  #     haml_engine = Haml::Engine.new(template)
+  #     output = haml_engine.render
+  #     puts output
+  class Engine
+    include Parser
+    include Compiler
+
+    # The options hash.
+    # See {file:HAML_REFERENCE.md#haml_options the Haml options documentation}.
+    #
+    # @return [{Symbol => Object}]
+    attr_accessor :options
+
+    # The indentation used in the Haml document,
+    # or `nil` if the indentation is ambiguous
+    # (for example, for a single-level document).
+    #
+    # @return [String]
+    attr_accessor :indentation
+
+    # @return [Boolean] Whether or not the format is XHTML.
+    def xhtml?
+      not html?
+    end
+
+    # @return [Boolean] Whether or not the format is any flavor of HTML.
+    def html?
+      html4? or html5?
+    end
+
+    # @return [Boolean] Whether or not the format is HTML4.
+    def html4?
+      @options[:format] == :html4
+    end
+
+    # @return [Boolean] Whether or not the format is HTML5.
+    def html5?
+      @options[:format] == :html5
+    end
+
+    # The source code that is evaluated to produce the Haml document.
+    #
+    # In Ruby 1.9, this is automatically converted to the correct encoding
+    # (see {file:HAML_REFERENCE.md#encoding-option the `:encoding` option}).
+    #
+    # @return [String]
+    def precompiled
+      return @precompiled if ruby1_8?
+      encoding = Encoding.find(@options[:encoding])
+      return @precompiled.force_encoding(encoding) if encoding == Encoding::BINARY
+      return @precompiled.encode(encoding)
+    end
+
+    # Precompiles the Haml template.
+    #
+    # @param template [String] The Haml template
+    # @param options [{Symbol => Object}] An options hash;
+    #   see {file:HAML_REFERENCE.md#haml_options the Haml options documentation}
+    # @raise [Haml::Error] if there's a Haml syntax error in the template
+    def initialize(template, options = {})
+      @options = {
+        :suppress_eval => false,
+        :attr_wrapper => "'",
+
+        # Don't forget to update the docs in doc-src/HAML_REFERENCE.md
+        # if you update these
+        :autoclose => %w[meta img link br hr input area param col base],
+        :preserve => %w[textarea pre code],
+
+        :filename => '(haml)',
+        :line => 1,
+        :ugly => false,
+        :format => :xhtml,
+        :escape_html => false,
+        :escape_attrs => true,
+      }
+
+
+      template = check_haml_encoding(template) do |msg, line|
+        raise Haml::Error.new(msg, line)
+      end
+
+      unless ruby1_8?
+        @options[:encoding] = Encoding.default_internal || template.encoding
+        @options[:encoding] = "utf-8" if @options[:encoding].name == "US-ASCII"
+      end
+      @options.merge! options.reject {|k, v| v.nil?}
+      @index = 0
+
+      unless [:xhtml, :html4, :html5].include?(@options[:format])
+        raise Haml::Error, "Invalid output format #{@options[:format].inspect}"
+      end
+
+      if @options[:encoding] && @options[:encoding].is_a?(Encoding)
+        @options[:encoding] = @options[:encoding].name
+      end
+
+      # :eod is a special end-of-document marker
+      @template = (template.rstrip).split(/\r\n|\r|\n/) + [:eod, :eod]
+      @template_index = 0
+      @to_close_stack = []
+      @output_tabs = 0
+      @template_tabs = 0
+      @flat = false
+      @newlines = 0
+      @precompiled = ''
+      @to_merge = []
+      @tab_change  = 0
+
+      compile(parse)
+    rescue Haml::Error => e
+      if @index || e.line
+        e.backtrace.unshift "#{@options[:filename]}:#{(e.line ? e.line + 1 : @index) + @options[:line] - 1}"
+      end
+      raise
+    end
+
+    # Processes the template and returns the result as a string.
+    #
+    # `scope` is the context in which the template is evaluated.
+    # If it's a `Binding` or `Proc` object,
+    # Haml uses it as the second argument to `Kernel#eval`;
+    # otherwise, Haml just uses its `#instance_eval` context.
+    #
+    # Note that Haml modifies the evaluation context
+    # (either the scope object or the `self` object of the scope binding).
+    # It extends {Haml::Helpers}, and various instance variables are set
+    # (all prefixed with `haml_`).
+    # For example:
+    #
+    #     s = "foobar"
+    #     Haml::Engine.new("%p= upcase").render(s) #=> "<p>FOOBAR</p>"
+    #
+    #     # s now extends Haml::Helpers
+    #     s.respond_to?(:html_attrs) #=> true
+    #
+    # `locals` is a hash of local variables to make available to the template.
+    # For example:
+    #
+    #     Haml::Engine.new("%p= foo").render(Object.new, :foo => "Hello, world!") #=> "<p>Hello, world!</p>"
+    #
+    # If a block is passed to render,
+    # that block is run when `yield` is called
+    # within the template.
+    #
+    # Due to some Ruby quirks,
+    # if `scope` is a `Binding` or `Proc` object and a block is given,
+    # the evaluation context may not be quite what the user expects.
+    # In particular, it's equivalent to passing `eval("self", scope)` as `scope`.
+    # This won't have an effect in most cases,
+    # but if you're relying on local variables defined in the context of `scope`,
+    # they won't work.
+    #
+    # @param scope [Binding, Proc, Object] The context in which the template is evaluated
+    # @param locals [{Symbol => Object}] Local variables that will be made available
+    #   to the template
+    # @param block [#to_proc] A block that can be yielded to within the template
+    # @return [String] The rendered template
+    def render(scope = Object.new, locals = {}, &block)
+      buffer = Haml::Buffer.new(scope.instance_variable_get('@haml_buffer'), options_for_buffer)
+
+      if scope.is_a?(Binding) || scope.is_a?(Proc)
+        scope_object = eval("self", scope)
+        scope = scope_object.instance_eval{binding} if block_given?
+      else
+        scope_object = scope
+        scope = scope_object.instance_eval{binding}
+      end
+
+      set_locals(locals.merge(:_hamlout => buffer, :_erbout => buffer.buffer), scope, scope_object)
+
+      scope_object.instance_eval do
+        extend Haml::Helpers
+        @haml_buffer = buffer
+      end
+
+      eval(precompiled + ";" + precompiled_method_return_value,
+        scope, @options[:filename], @options[:line])
+    ensure
+      # Get rid of the current buffer
+      scope_object.instance_eval do
+        @haml_buffer = buffer.upper if buffer
+      end
+    end
+    alias_method :to_html, :render
+
+    # Returns a proc that, when called,
+    # renders the template and returns the result as a string.
+    #
+    # `scope` works the same as it does for render.
+    #
+    # The first argument of the returned proc is a hash of local variable names to values.
+    # However, due to an unfortunate Ruby quirk,
+    # the local variables which can be assigned must be pre-declared.
+    # This is done with the `local_names` argument.
+    # For example:
+    #
+    #     # This works
+    #     Haml::Engine.new("%p= foo").render_proc(Object.new, :foo).call :foo => "Hello!"
+    #       #=> "<p>Hello!</p>"
+    #
+    #     # This doesn't
+    #     Haml::Engine.new("%p= foo").render_proc.call :foo => "Hello!"
+    #       #=> NameError: undefined local variable or method `foo'
+    #
+    # The proc doesn't take a block; any yields in the template will fail.
+    #
+    # @param scope [Binding, Proc, Object] The context in which the template is evaluated
+    # @param local_names [Array<Symbol>] The names of the locals that can be passed to the proc
+    # @return [Proc] The proc that will run the template
+    def render_proc(scope = Object.new, *local_names)
+      if scope.is_a?(Binding) || scope.is_a?(Proc)
+        scope_object = eval("self", scope)
+      else
+        scope_object = scope
+        scope = scope_object.instance_eval{binding}
+      end
+
+      eval("Proc.new { |*_haml_locals| _haml_locals = _haml_locals[0] || {};" +
+           precompiled_with_ambles(local_names) + "}\n", scope, @options[:filename], @options[:line])
+    end
+
+    # Defines a method on `object` with the given name
+    # that renders the template and returns the result as a string.
+    #
+    # If `object` is a class or module,
+    # the method will instead by defined as an instance method.
+    # For example:
+    #
+    #     t = Time.now
+    #     Haml::Engine.new("%p\n  Today's date is\n  .date= self.to_s").def_method(t, :render)
+    #     t.render #=> "<p>\n  Today's date is\n  <div class='date'>Fri Nov 23 18:28:29 -0800 2007</div>\n</p>\n"
+    #
+    #     Haml::Engine.new(".upcased= upcase").def_method(String, :upcased_div)
+    #     "foobar".upcased_div #=> "<div class='upcased'>FOOBAR</div>\n"
+    #
+    # The first argument of the defined method is a hash of local variable names to values.
+    # However, due to an unfortunate Ruby quirk,
+    # the local variables which can be assigned must be pre-declared.
+    # This is done with the `local_names` argument.
+    # For example:
+    #
+    #     # This works
+    #     obj = Object.new
+    #     Haml::Engine.new("%p= foo").def_method(obj, :render, :foo)
+    #     obj.render(:foo => "Hello!") #=> "<p>Hello!</p>"
+    #
+    #     # This doesn't
+    #     obj = Object.new
+    #     Haml::Engine.new("%p= foo").def_method(obj, :render)
+    #     obj.render(:foo => "Hello!") #=> NameError: undefined local variable or method `foo'
+    #
+    # Note that Haml modifies the evaluation context
+    # (either the scope object or the `self` object of the scope binding).
+    # It extends {Haml::Helpers}, and various instance variables are set
+    # (all prefixed with `haml_`).
+    #
+    # @param object [Object, Module] The object on which to define the method
+    # @param name [String, Symbol] The name of the method to define
+    # @param local_names [Array<Symbol>] The names of the locals that can be passed to the proc
+    def def_method(object, name, *local_names)
+      method = object.is_a?(Module) ? :module_eval : :instance_eval
+
+      object.send(method, "def #{name}(_haml_locals = {}); #{precompiled_with_ambles(local_names)}; end",
+                  @options[:filename], @options[:line])
+    end
+
+    protected
+
+    # Returns a subset of \{#options}: those that {Haml::Buffer} cares about.
+    # All of the values here are such that when `#inspect` is called on the hash,
+    # it can be `Kernel#eval`ed to get the same result back.
+    #
+    # See {file:HAML_REFERENCE.md#haml_options the Haml options documentation}.
+    #
+    # @return [{Symbol => Object}] The options hash
+    def options_for_buffer
+      {
+        :autoclose => @options[:autoclose],
+        :preserve => @options[:preserve],
+        :attr_wrapper => @options[:attr_wrapper],
+        :ugly => @options[:ugly],
+        :format => @options[:format],
+        :encoding => @options[:encoding],
+        :escape_html => @options[:escape_html],
+        :escape_attrs => @options[:escape_attrs],
+      }
+    end
+
+    private
+
+    def set_locals(locals, scope, scope_object)
+      scope_object.send(:instance_variable_set, '@_haml_locals', locals)
+      set_locals = locals.keys.map { |k| "#{k} = @_haml_locals[#{k.inspect}]" }.join("\n")
+      eval(set_locals, scope)
+    end
+  end
+end

data/lib/haml/error.rb

@@ -0,0 +1,22 @@
+module Haml
+  # An exception raised by Haml code.
+  class Error < StandardError
+    # The line of the template on which the error occurred.
+    #
+    # @return [Fixnum]
+    attr_reader :line
+
+    # @param message [String] The error message
+    # @param line [Fixnum] See \{#line}
+    def initialize(message = nil, line = nil)
+      super(message)
+      @line = line
+    end
+  end
+
+  # SyntaxError is the type of exception raised when Haml encounters an
+  # ill-formatted document.
+  # It's not particularly interesting,
+  # except in that it's a subclass of {Haml::Error}.
+  class SyntaxError < Haml::Error; end
+end

data/lib/haml/exec.rb

@@ -0,0 +1,362 @@
+require 'optparse'
+require 'fileutils'
+
+module Haml
+  # This module handles the various Haml executables (`haml` and `haml-convert`).
+  module Exec
+    # An abstract class that encapsulates the executable code for all three executables.
+    class Generic
+      # @param args [Array<String>] The command-line arguments
+      def initialize(args)
+        @args = args
+        @options = {:for_engine => {}}
+      end
+
+      # Parses the command-line arguments and runs the executable.
+      # Calls `Kernel#exit` at the end, so it never returns.
+      #
+      # @see #parse
+      def parse!
+        begin
+          parse
+        rescue Exception => e
+          raise e if @options[:trace] || e.is_a?(SystemExit)
+
+          $stderr.print "#{e.class}: " unless e.class == RuntimeError
+          $stderr.puts "#{e.message}"
+          $stderr.puts "  Use --trace for backtrace."
+          exit 1
+        end
+        exit 0
+      end
+
+      # Parses the command-line arguments and runs the executable.
+      # This does not handle exceptions or exit the program.
+      #
+      # @see #parse!
+      def parse
+        @opts = OptionParser.new(&method(:set_opts))
+        @opts.parse!(@args)
+
+        process_result
+
+        @options
+      end
+
+      # @return [String] A description of the executable
+      def to_s
+        @opts.to_s
+      end
+
+      protected
+
+      # Finds the line of the source template
+      # on which an exception was raised.
+      #
+      # @param exception [Exception] The exception
+      # @return [String] The line number
+      def get_line(exception)
+        # SyntaxErrors have weird line reporting
+        # when there's trailing whitespace,
+        # which there is for Haml documents.
+        return (exception.message.scan(/:(\d+)/).first || ["??"]).first if exception.is_a?(::SyntaxError)
+        (exception.backtrace[0].scan(/:(\d+)/).first || ["??"]).first
+      end
+
+      # Tells optparse how to parse the arguments
+      # available for all executables.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can add their own options.
+      #
+      # @param opts [OptionParser]
+      def set_opts(opts)
+        opts.on('-s', '--stdin', :NONE, 'Read input from standard input instead of an input file') do
+          @options[:input] = $stdin
+        end
+
+        opts.on('--trace', :NONE, 'Show a full traceback on error') do
+          @options[:trace] = true
+        end
+
+        opts.on('--unix-newlines', 'Use Unix-style newlines in written files.') do
+          @options[:unix_newlines] = true if ::Haml::Util.windows?
+        end
+
+        opts.on_tail("-?", "-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+
+        opts.on_tail("-v", "--version", "Print version") do
+          puts("Haml #{::Haml.version[:string]}")
+          exit
+        end
+      end
+
+      # Processes the options set by the command-line arguments.
+      # In particular, sets `@options[:input]` and `@options[:output]`
+      # to appropriate IO streams.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can run their respective programs.
+      def process_result
+        input, output = @options[:input], @options[:output]
+        args = @args.dup
+        input ||=
+          begin
+            filename = args.shift
+            @options[:filename] = filename
+            open_file(filename) || $stdin
+          end
+        output ||= open_file(args.shift, 'w') || $stdout
+
+        @options[:input], @options[:output] = input, output
+      end
+
+      COLORS = { :red => 31, :green => 32, :yellow => 33 }
+
+      # Prints a status message about performing the given action,
+      # colored using the given color (via terminal escapes) if possible.
+      #
+      # @param name [#to_s] A short name for the action being performed.
+      #   Shouldn't be longer than 11 characters.
+      # @param color [Symbol] The name of the color to use for this action.
+      #   Can be `:red`, `:green`, or `:yellow`.
+      def puts_action(name, color, arg)
+        return if @options[:for_engine][:quiet]
+        printf color(color, "%11s %s\n"), name, arg
+      end
+
+      # Same as \{Kernel.puts}, but doesn't print anything if the `--quiet` option is set.
+      #
+      # @param args [Array] Passed on to \{Kernel.puts}
+      def puts(*args)
+        return if @options[:for_engine][:quiet]
+        Kernel.puts(*args)
+      end
+
+      # Wraps the given string in terminal escapes
+      # causing it to have the given color.
+      # If terminal esapes aren't supported on this platform,
+      # just returns the string instead.
+      #
+      # @param color [Symbol] The name of the color to use.
+      #   Can be `:red`, `:green`, or `:yellow`.
+      # @param str [String] The string to wrap in the given color.
+      # @return [String] The wrapped string.
+      def color(color, str)
+        raise "[BUG] Unrecognized color #{color}" unless COLORS[color]
+
+        # Almost any real Unix terminal will support color,
+        # so we just filter for Windows terms (which don't set TERM)
+        # and not-real terminals, which aren't ttys.
+        return str if ENV["TERM"].nil? || ENV["TERM"].empty? || !STDOUT.tty?
+        return "\e[#{COLORS[color]}m#{str}\e[0m"
+      end
+
+      private
+
+      def open_file(filename, flag = 'r')
+        return if filename.nil?
+        flag = 'wb' if @options[:unix_newlines] && flag == 'w'
+        File.open(filename, flag)
+      end
+
+      def handle_load_error(err)
+        dep = err.message[/^no such file to load -- (.*)/, 1]
+        raise err if @options[:trace] || dep.nil? || dep.empty?
+        $stderr.puts <<MESSAGE
+Required dependency #{dep} not found!
+    Run "gem install #{dep}" to get it.
+  Use --trace for backtrace.
+MESSAGE
+        exit 1
+      end
+    end
+
+    # The `haml` executable.
+    class Haml < Generic
+      # @param args [Array<String>] The command-line arguments
+      def initialize(args)
+        super
+        @options[:for_engine] = {}
+        @options[:requires] = []
+        @options[:load_paths] = []
+      end
+
+      # Tells optparse how to parse the arguments.
+      #
+      # @param opts [OptionParser]
+      def set_opts(opts)
+        super
+
+        opts.banner = <<END
+Usage: haml [options] [INPUT] [OUTPUT]
+
+Description:
+  Converts Haml files to HTML.
+
+Options:
+END
+
+        opts.on('-c', '--check', "Just check syntax, don't evaluate.") do
+          require 'stringio'
+          @options[:check_syntax] = true
+          @options[:output] = StringIO.new
+        end
+
+        opts.on('-t', '--style NAME',
+                'Output style. Can be indented (default) or ugly.') do |name|
+          @options[:for_engine][:ugly] = true if name.to_sym == :ugly
+        end
+
+        opts.on('-f', '--format NAME',
+                'Output format. Can be xhtml (default), html4, or html5.') do |name|
+          @options[:for_engine][:format] = name.to_sym
+        end
+
+        opts.on('-e', '--escape-html',
+                'Escape HTML characters (like ampersands and angle brackets) by default.') do
+          @options[:for_engine][:escape_html] = true
+        end
+
+        opts.on('--no-escape-attrs',
+                "Don't escape HTML characters (like ampersands and angle brackets) in attributes.") do
+          @options[:for_engine][:escape_attrs] = false
+        end
+
+        opts.on('-q', '--double-quote-attributes',
+                'Set attribute wrapper to double-quotes (default is single).') do
+          @options[:for_engine][:attr_wrapper] = '"'
+        end
+
+        opts.on('-r', '--require FILE', "Same as 'ruby -r'.") do |file|
+          @options[:requires] << file
+        end
+
+        opts.on('-I', '--load-path PATH', "Same as 'ruby -I'.") do |path|
+          @options[:load_paths] << path
+        end
+
+        unless ::Haml::Util.ruby1_8?
+          opts.on('-E ex[:in]', 'Specify the default external and internal character encodings.') do |encoding|
+            external, internal = encoding.split(':')
+            Encoding.default_external = external if external && !external.empty?
+            Encoding.default_internal = internal if internal && !internal.empty?
+          end
+        end
+
+        opts.on('--debug', "Print out the precompiled Ruby source.") do
+          @options[:debug] = true
+        end
+      end
+
+      # Processes the options set by the command-line arguments,
+      # and runs the Haml compiler appropriately.
+      def process_result
+        super
+        @options[:for_engine][:filename] = @options[:filename]
+        input = @options[:input]
+        output = @options[:output]
+
+        template = input.read()
+        input.close() if input.is_a? File
+
+        @options[:load_paths].each {|p| $LOAD_PATH << p}
+        @options[:requires].each {|f| require f}
+
+        begin
+          engine = ::Haml::Engine.new(template, @options[:for_engine])
+          if @options[:check_syntax]
+            puts "Syntax OK"
+            return
+          end
+
+          if @options[:debug]
+            puts engine.precompiled
+            puts '=' * 100
+          end
+
+          result = engine.to_html
+        rescue Exception => e
+          raise e if @options[:trace]
+
+          case e
+          when ::Haml::SyntaxError; raise "Syntax error on line #{get_line e}: #{e.message}"
+          when ::Haml::Error;       raise "Haml error on line #{get_line e}: #{e.message}"
+          else raise "Exception on line #{get_line e}: #{e.message}\n  Use --trace for backtrace."
+          end
+        end
+
+        output.write(result)
+        output.close() if output.is_a? File
+      end
+    end
+
+    # The `html2haml` executable.
+    class HTML2Haml < Generic
+      # @param args [Array<String>] The command-line arguments
+      def initialize(args)
+        super
+        @module_opts = {}
+      end
+
+      # Tells optparse how to parse the arguments.
+      #
+      # @param opts [OptionParser]
+      def set_opts(opts)
+        opts.banner = <<END
+Usage: html2haml [options] [INPUT] [OUTPUT]
+
+Description: Transforms an HTML file into corresponding Haml code.
+
+Options:
+END
+
+        opts.on('-e', '--erb', 'Parse ERb tags.') do
+          @module_opts[:erb] = true
+        end
+
+        opts.on('--no-erb', "Don't parse ERb tags.") do
+          @options[:no_erb] = true
+        end
+
+        opts.on('-r', '--rhtml', 'Deprecated; same as --erb.') do
+          @module_opts[:erb] = true
+        end
+
+        opts.on('--no-rhtml', "Deprecated; same as --no-erb.") do
+          @options[:no_erb] = true
+        end
+
+        opts.on('-x', '--xhtml', 'Parse the input using the more strict XHTML parser.') do
+          @module_opts[:xhtml] = true
+        end
+
+        super
+      end
+
+      # Processes the options set by the command-line arguments,
+      # and runs the HTML compiler appropriately.
+      def process_result
+        super
+
+        require 'haml/html'
+
+        input = @options[:input]
+        output = @options[:output]
+
+        @module_opts[:erb] ||= input.respond_to?(:path) && input.path =~ /\.(rhtml|erb)$/
+        @module_opts[:erb] &&= @options[:no_erb] != false
+
+        output.write(::Haml::HTML.new(input, @module_opts).render)
+      rescue ::Haml::Error => e
+        raise "#{e.is_a?(::Haml::SyntaxError) ? "Syntax error" : "Error"} on line " +
+          "#{get_line e}: #{e.message}"
+      rescue LoadError => err
+        handle_load_error(err)
+      end
+    end
+  end
+end