Skip to content

Add HAML support (.haml views and partials) - #2

Merged
jacksonpires merged 6 commits into
mainfrom
feat/haml-support
Nov 13, 2026
Merged

jacksonpires merged 6 commits into
mainfrom
feat/haml-support

Conversation

@jacksonpires

Copy link
Copy Markdown
Owner

Summary

Adds conversion of .haml views and partials, alongside .erb. convert app/views picks up both formats, and convert_string(..., format: :haml) handles HAML strings.

A new front-end, HamlParser, walks the haml gem's own parse tree and builds the same AST the ERB front-end produces. So everything downstream applies to HAML unchanged: RubyUI element mapping, link_to/render, form-builder mapping, locals/ivars detection and --literal.

.erb  ─▶ Lexer ─▶ HtmlTokenizer ─▶ Parser ──────┐
                                                ├─▶ AST ─▶ Transformer ─▶ Ruby/Phlex
.haml ─▶ Haml::Parser (haml gem) ─▶ HamlParser ─┘

haml is an optional dependency. It is required lazily, only when a .haml file is converted. ERB-only users still have just thor at runtime, and haml 7 would otherwise also pull prism, temple and tilt into every install. Apps with .haml views already have haml in their bundle. Supported: haml 5.2, 6.x and 7.x, which share the same parse tree shape. Without the gem, .erb files still convert and the CLI explains once how to add it.

What's covered (one commit per phase)

  1. Front-end and dispatch. Tags and their .class#id shorthand, =/!=/&=, if/elsif/else and case/when (HAML nests these branches inside their opener), and blocks. Also interpolated text, where the escape wrappers that haml 5/6 add around each #{} are removed.
  2. Attributes, with HAML's merge rules. class values merge and id values join with _. false/nil attributes are dropped and true becomes a boolean attribute. Literal data:/aria: hashes expand to hyphenated attributes. [@obj] becomes dom_id/dom_class, and hashes that can't be split become a **splat. String values stay static, so RubyUI rules (Checkbox, Card) keep matching.
  3. Text, whitespace, comments and filters.
    • HAML text goes through the ERB parser (#{x} → <%= x %>). Inline HTML becomes real elements, and #{link_to ...} becomes Link(...).
    • A text line next to other content gets a separating space, mirroring HAML's line break (%tag> is respected).
    • A / comment with nested content becomes comment do … end.
    • Filters: :javascript, :css, :plain, :escaped, :erb and :ruby are converted; other filters become TODO comments.
  4. Converter and CLI. Two templates that would generate the same .rb (show.html.erb + show.html.haml, or a +variant) now report the second one as an error. The CLI explains a missing haml gem once.
  5. E2E. script/rails_e2e/run.sh also adds haml-rails, scaffolds a Supplier with HAML views, converts them and renders index/show/new/edit/create. Passed locally on Rails 8.1 / Ruby 3.4; CI runs it across the full Rails × Ruby matrix.
  6. Docs. README (HAML section, compatibility, limitations), CHANGELOG, CLAUDE.md and the gemspec.

Changes that also affect ERB output

  • Fix: an unparenthesized form_with model: @x do |form| now activates the form-builder mapping. Before, the model capture swallowed do |form|.
  • Fix: a same-line space between inline siblings (<em>a</em> <%= b %>) is now kept as Phlex whitespace instead of being dropped. Line breaks between tags are still discarded.
  • Cosmetic: attribute expressions that already close on themselves ([a, b], {...}, dom_id(user, :row)) are no longer wrapped in parentheses.

Testing

  • Unit suite: 104 → 169 tests. Every commit passes on its own.
  • HAML tests also pass locally against haml 6.4 and 5.2 (pinned throwaway bundles). In CI, Ruby 3.0/3.1 resolve haml 6 and Ruby 3.2+ resolve haml 7, so both interpolation shapes are covered.
  • E2E with real haml-rails scaffold views: passed locally on Rails 8.1.

Known limitations

Documented in the README:

  • HAML whitespace is only approximated.
  • {id: [a, b]} joins with a space in Phlex, but with _ in HAML.
  • [@obj] on a new record gives new_user (HAML gives user_new).
  • IE conditional comments and exotic filters are left as TODO comments.

Pre-existing and left for a separate PR: HTML entities in text (&copy;) come out escaped, in ERB as well.

🤖 Generated with Claude Code

jacksonpires and others added 6 commits November 13, 2026 09:06
Introduce HamlParser, which walks the haml gem's own parse tree
(Haml::Parser, haml 5.2/6/7) and builds the same Nodes AST the ERB
front-end produces, so the Transformer, RubyUI mapping, RailsHelpers,
FormBuilder and LocalsDetector are reused unchanged. The haml gem is an
optional dependency, required lazily with a friendly error.

- RubyUIConverter.parse(source, format:) dispatches on :erb/:haml;
  convert_string accepts format:, Template derives it from the extension
  and FileWalker picks up **/*.{erb,haml}.
- Tags, =/!=/&=, control flow with flattened else/elsif/when, blocks,
  interpolated text (unwrapping haml 5/6 escape wrappers), comments and
  doctype. Dynamic attribute hashes are splatted for now.
- RubyLiteral splits Ruby string literals into text/code parts (Ripper).
- Fix: an unparenthesized form_with (model: @x do |form|) now activates
  the form-builder mapping.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
HamlAttributes builds the attribute parts list from static attributes,
html-style and hash attributes and object references: class values merge
(strings into one string, expressions into a Phlex-flattened array), id
values join with "_", false/nil drop, true is boolean, symbols become
text, literal data:/aria: hashes expand to hyphenated attributes,
[@obj] maps to dom_id/dom_class, and unsplittable hashes become a splat.
String literals become static text so ComponentMap rules (Checkbox, Card)
keep matching.

Attribute expressions that are already self-delimited ([a, b], {...},
dom_id(user, :row)) are no longer wrapped in parentheses.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- HAML text is routed through the ERB parser (#{x} -> <%= x %>), so
  inline HTML becomes elements and interpolated helpers such as link_to
  map like their ERB equivalents.
- Text next to rendered siblings gets a separating space (HAML's line
  break), except around tags that remove outer whitespace.
- A / comment with nested content becomes comment do ... end
  (Comment#children; locals inside it are detected); IE conditional
  comments are left as a TODO.
- Filters: :javascript/:css -> script/style, :plain/:preserve, :escaped,
  :erb (ERB parser), :ruby (statements); others become TODO comments.
- Fix: a same-line space between inline siblings is kept as Phlex
  whitespace instead of being dropped (ERB too).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Two templates generating the same .rb in one run (show.html.erb +
show.html.haml, or a +variant) now report the later one as an error
instead of skipping or overwriting the first. When the haml gem is not
loadable, the CLI lists the affected files briefly and explains once how
to add the gem.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
After the ERB flow, add haml-rails, scaffold a Supplier with HAML views
(--template-engine=haml, since tailwindcss-rails registers its own
engine), convert them and render index/show/new/edit/create through the
generated classes, including the spaced "|" separator between links.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
README (HAML templates section, compatibility, limitations, pipeline
diagram), CHANGELOG, CLAUDE.md and the gemspec summary/description.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@jacksonpires
jacksonpires merged commit c857981 into main Nov 13, 2026
23 checks passed
@jacksonpires
jacksonpires deleted the feat/haml-support branch November 13, 2026 14:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant