haml2html 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e1c4e54e801d2d2bf84e9258139c58af9f8096b06b321af619e19483eaf592a
+  data.tar.gz: b7df8ef491439377c23adc35a05ae9845fd25c002056cdacf7a1341b69001604
+SHA512:
+  metadata.gz: 95e12f9a8e0fd412dd71312bfd19db9f320440d21e15be51feefc6d52fa77062a385e7fa28e57cdaef2509d5f1dcf0250b240f2bfcc93840062ad1b7257708dd
+  data.tar.gz: 8d791b7b6a3bfb126ba4c46a7488ebd5c006382a78f73ffe265839ceb3c947d94498068493781f938fc234d1044444f35abb3e137b7bf293d9b6c2503954fd9f

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial Haml-to-ERB converter.
+- CLI for stdin/stdout and explicit input/output files.
+- Rails render-equivalence test coverage for common Haml constructs.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,56 @@
+# haml2html
+
+`haml2html` converts Haml templates to Rails ERB templates. It is built for Rails app migrations where rendered HTML equivalence matters more than preserving original source formatting.
+
+## Install
+
+```sh
+gem install haml2html
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "haml2html"
+```
+
+## CLI
+
+```sh
+haml2html app/views/posts/show.html.haml app/views/posts/show.html.erb
+haml2html --stdin < app/views/posts/show.html.haml
+```
+
+The CLI writes to stdout unless an output path is provided. Unsupported syntax is reported with file and line diagnostics and exits nonzero.
+
+## Ruby API
+
+```ruby
+require "haml2html"
+
+erb = Haml2html::Converter.new("%p= post.title\n", filename: "show.html.haml").render
+```
+
+## Supported
+
+- Haml tags, nesting, static attributes, text, interpolation.
+- Ruby output and control flow: `=`, `!=`, `- if`, `- each do`, and similar blocks.
+- Public comments and silent comments.
+- `:plain`, `:escaped`, `:javascript`, `:css`, and `:erb` filters.
+- Dynamic Haml attributes and object references through `Haml::AttributeBuilder`.
+
+Generated ERB may call `Haml::AttributeBuilder` for dynamic attributes and object references. Keep `haml` available at runtime until those converted templates are simplified.
+
+## Limitations
+
+This is a migration tool, not a full source-preserving formatter. Output whitespace and quote style may differ from Haml output, while rendered HTML should remain equivalent for supported constructs. Unsupported filters or nodes fail with diagnostics instead of emitting known-wrong ERB.
+
+Batch directory conversion is planned after the single-file converter is stable.
+
+## Publishing Checklist
+
+1. Verify gemspec URLs match the final repository URL.
+2. Run `rake test`.
+3. Run `gem build haml2html.gemspec --strict`.
+4. Inspect package contents with `gem spec haml2html-0.1.0.gem files`.
+5. Publish with RubyGems MFA enabled.

data/bin/haml2html

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "optparse"
+require "haml2html"
+
+options = {}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: haml2html [options] [INPUT] [OUTPUT]"
+  opts.on("-s", "--stdin", "Read input from standard input") { options[:stdin] = true }
+  opts.on("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+  opts.on("-v", "--version", "Print version") do
+    puts Haml2html::VERSION
+    exit
+  end
+end
+
+parser.parse!
+
+begin
+  input_path, output_path = ARGV
+
+  if options[:stdin]
+    source = STDIN.read
+  elsif input_path
+    source = File.read(input_path)
+  else
+    warn parser
+    exit 1
+  end
+
+  result = Haml2html::Converter.new(source, filename: input_path).render
+
+  if output_path
+    File.write(output_path, result)
+  else
+    print result
+  end
+rescue Haml2html::ConversionError => error
+  warn error.message
+  exit 2
+end

data/lib/haml2html/converter.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "haml"
+
+require_relative "diagnostic"
+
+module Haml2html
+  class Converter
+    VOID_TAGS = %w[area base br col embed hr img input link meta param source track wbr].freeze
+    SUPPORTED_FILTERS = %w[plain escaped javascript css erb].freeze
+
+    attr_reader :diagnostics
+
+    def initialize(template, options = {})
+      @template = template.respond_to?(:read) ? template.read : template.to_s
+      @lines = @template.lines
+      @filename = options[:filename]
+      @diagnostics = []
+    end
+
+    def render
+      ast = Haml::Parser.new(filename: @filename).call(@template)
+      output = emit_children(ast.children, 0)
+      raise ConversionError, diagnostics if diagnostics.any?
+
+      output
+    end
+
+    private
+
+    def emit_children(children, indent)
+      children.map { |child| emit_node(child, indent) }.join
+    end
+
+    def emit_node(node, indent)
+      case node.type
+      when :root
+        emit_children(node.children, indent)
+      when :plain
+        emit_plain(node, indent)
+      when :tag
+        emit_tag(node, indent)
+      when :script
+        emit_script(node, indent)
+      when :silent_script
+        emit_silent_script(node, indent)
+      when :haml_comment
+        "#{spaces(indent)}<%# #{node.value[:text].to_s.strip} %>\n"
+      when :comment
+        emit_comment(node, indent)
+      when :doctype
+        emit_doctype(node, indent)
+      when :filter
+        emit_filter(node, indent)
+      else
+        unsupported(node, node.type, "unsupported Haml node")
+        ""
+      end
+    end
+
+    def emit_plain(node, indent)
+      text = interpolate_text(node.value[:text].to_s)
+      "#{spaces(indent)}#{text}\n"
+    end
+
+    def emit_tag(node, indent)
+      value = node.value
+      name = value.fetch(:name)
+      attrs = emit_attributes(node)
+      open = "#{spaces(indent)}<#{name}#{attrs}>"
+      close = "</#{name}>"
+
+      if value[:self_closing] || (VOID_TAGS.include?(name) && node.children.empty? && blank?(value[:value]))
+        return "#{spaces(indent)}<#{name}#{attrs}>\n"
+      end
+
+      inline = inline_tag_value(node)
+      if node.children.empty? && !blank?(inline)
+        return "#{open}#{inline}#{close}\n"
+      end
+
+      "#{open}\n#{emit_children(node.children, indent + 1)}#{spaces(indent)}#{close}\n"
+    end
+
+    def inline_tag_value(node)
+      value = node.value
+      return nil if value[:parse].nil? && blank?(value[:value])
+
+      if value[:parse]
+        marker = raw_script_line?(node) ? "<%==" : "<%="
+        raw = "#{marker} #{value[:value].to_s.strip} %>"
+        value[:preserve_script] ? raw : raw
+      else
+        interpolate_text(value[:value].to_s)
+      end
+    end
+
+    def emit_attributes(node)
+      value = node.value
+      return runtime_attributes(value) if runtime_attributes?(value)
+
+      attrs = value[:attributes].sort.map do |name, attr_value|
+        %( #{name}="#{escape_attr(interpolate_text(attr_value.to_s))}")
+      end
+      attrs.join
+    end
+
+    def emit_script(node, indent)
+      code = node.value[:text].to_s.strip
+      if interpolated_string_literal?(code)
+        return "#{spaces(indent)}#{interpolate_text(unquote_string_literal(code))}\n"
+      end
+
+      marker = raw_script_line?(node) ? "<%==" : "<%="
+      "#{spaces(indent)}#{marker} #{code} %>\n"
+    end
+
+    def emit_silent_script(node, indent)
+      code = node.value[:text].to_s.strip
+      output = +"#{spaces(indent)}<% #{code} %>\n"
+      output << emit_children(node.children, indent + 1)
+      output << "#{spaces(indent)}<% end %>\n" if closes_with_end?(node)
+      output
+    end
+
+    def emit_comment(node, indent)
+      conditional = node.value[:conditional]
+      text = node.value[:text].to_s
+      if conditional
+        "#{spaces(indent)}<!--[#{conditional}]>#{text}<![endif]-->\n"
+      elsif text.include?("\n")
+        "#{spaces(indent)}<!--\n#{indent_block(text, indent + 1)}#{spaces(indent)}-->\n"
+      else
+        "#{spaces(indent)}<!-- #{text.strip} -->\n"
+      end
+    end
+
+    def emit_doctype(node, indent)
+      version = node.value[:version]
+      type = node.value[:type].to_s
+      html5 = version.nil? && type.empty?
+      text = html5 ? "<!DOCTYPE html>" : "<!DOCTYPE html>"
+      "#{spaces(indent)}#{text}\n"
+    end
+
+    def emit_filter(node, indent)
+      name = node.value[:name].to_s
+      text = node.value[:text].to_s
+
+      unless SUPPORTED_FILTERS.include?(name)
+        unsupported(node, "filter :#{name}", "unsupported filter")
+        return ""
+      end
+
+      case name
+      when "plain"
+        indent_block(text, indent)
+      when "escaped"
+        indent_block(CGI.escapeHTML(text), indent)
+      when "javascript"
+        "#{spaces(indent)}<script>\n#{indent_block(text, indent + 1)}#{spaces(indent)}</script>\n"
+      when "css"
+        "#{spaces(indent)}<style>\n#{indent_block(text, indent + 1)}#{spaces(indent)}</style>\n"
+      when "erb"
+        indent_block(text, indent)
+      end
+    end
+
+    def runtime_attributes?(value)
+      object_ref = value[:object_ref]
+      return true unless object_ref.nil? || object_ref == :nil
+
+      dynamic = value[:dynamic_attributes]
+      return false unless dynamic
+
+      dynamic_literals(dynamic).any?
+    end
+
+    def runtime_attributes(value)
+      args = ["true", '"\\"".freeze', ":html", object_ref_literal(value[:object_ref])]
+      args << value[:attributes].inspect unless value[:attributes].empty?
+      args.concat(dynamic_literals(value[:dynamic_attributes]))
+
+      %(<%== (require "haml"; ::Haml::AttributeBuilder.build(#{args.join(", ")})) %>)
+    end
+
+    def object_ref_literal(object_ref)
+      return "nil" if object_ref.nil? || object_ref == :nil
+
+      object_ref
+    end
+
+    def dynamic_literals(dynamic)
+      return [] unless dynamic
+
+      [dynamic.new, stripped_old_dynamic_literal(dynamic.old)].compact
+    end
+
+    def stripped_old_dynamic_literal(old)
+      return nil if old.nil?
+
+      old.dup.sub(/\A{/, "").sub(/}\z/m, "")
+    end
+
+    def diagnose_object_ref(node, value)
+      object_ref = value[:object_ref]
+      return if object_ref.nil? || object_ref == :nil
+
+      unsupported(node, "object reference", "object references cannot be faithfully converted to inline attrs")
+    end
+
+    def diagnose_dynamic_attributes(node, value)
+      dynamic = value[:dynamic_attributes]
+      return unless dynamic
+
+      if dynamic.respond_to?(:new) && dynamic.new
+        unsupported(node, "dynamic attributes", "new-style dynamic attributes are not supported")
+      end
+
+      if dynamic.respond_to?(:old) && dynamic.old
+        unsupported(node, "dynamic attributes", "old-style dynamic attributes are not supported")
+      end
+    end
+
+    def closes_with_end?(node)
+      keyword = node.value[:keyword].to_s
+      return true if %w[if unless case begin for while until].include?(keyword)
+
+      node.value[:text].to_s.match?(/\bdo(\s*\|.*\|)?\s*\z/)
+    end
+
+    def interpolate_text(text)
+      text.gsub(/#\{([^{}]+)\}/, '<%= \1 %>')
+    end
+
+    def interpolated_string_literal?(code)
+      code.match?(/\A"(?:[^"\\]|\\.|#\{[^{}]+\})*"\z/)
+    end
+
+    def unquote_string_literal(code)
+      code[1...-1].gsub('\"', '"').gsub('\n', "\n")
+    end
+
+    def escape_attr(value)
+      value.gsub("&", "&amp;").gsub('"', "&quot;")
+    end
+
+    def indent_block(text, indent)
+      text.to_s.each_line.map { |line| "#{spaces(indent)}#{line}" }.join
+    end
+
+    def unsupported(node, feature, message)
+      diagnostics << Diagnostic.new(filename: @filename, line: node.line, feature: feature.to_s, message: message)
+    end
+
+    def raw_script_line?(node)
+      line = @lines.fetch(node.line.to_i - 1, "")
+      line.lstrip.start_with?("!=") || line.include?("!=")
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.empty?
+    end
+
+    def spaces(indent)
+      "  " * indent
+    end
+  end
+end

data/lib/haml2html/diagnostic.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Haml2html
+  Diagnostic = Struct.new(:filename, :line, :feature, :message, keyword_init: true) do
+    def to_s
+      location = [filename, line].compact.join(":")
+      location = "haml" if location.empty?
+      "#{location}: #{feature}: #{message}"
+    end
+  end
+
+  class ConversionError < StandardError
+    attr_reader :diagnostics
+
+    def initialize(diagnostics)
+      @diagnostics = diagnostics
+      super(diagnostics.map(&:to_s).join("\n"))
+    end
+  end
+end

data/lib/haml2html/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Haml2html
+  VERSION = "0.1.0"
+end

data/lib/haml2html.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "haml2html/converter"
+require_relative "haml2html/diagnostic"
+require_relative "haml2html/version"
+
+module Haml2html
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: haml2html
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kyle
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: haml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Haml-to-ERB migration tool for Rails templates.
+email:
+- kyle.duncan.dev@gmail.com
+executables:
+- haml2html
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/haml2html
+- lib/haml2html.rb
+- lib/haml2html/converter.rb
+- lib/haml2html/diagnostic.rb
+- lib/haml2html/version.rb
+homepage: https://github.com/kyle/haml2html
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kyle/haml2html
+  source_code_uri: https://github.com/kyle/haml2html/tree/main
+  changelog_uri: https://github.com/kyle/haml2html/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Convert Haml templates to Rails ERB.
+test_files: []