├── .github
    └── workflows
    │   ├── ci.yml
    │   └── weekly.yml
├── .gitignore
├── LICENSE
├── README.md
├── shard.yml
├── spec
    ├── html_builder_spec.cr
    └── spec_helper.cr
└── src
    ├── html
        └── builder
        │   ├── builder.cr
        │   └── version.cr
    └── html_builder.cr


/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
 1 | name: CI
 2 | on:
 3 |   push:
 4 |   pull_request:
 5 | 
 6 | jobs:
 7 |   test:
 8 |     name: Test
 9 |     runs-on: ubuntu-latest
10 |     steps:
11 |       - name: Download source
12 |         uses: actions/checkout@v3
13 | 
14 |       - name: Install Crystal
15 |         uses: crystal-lang/install-crystal@v1
16 | 
17 |       - name: Run tests
18 |         run: crystal spec
19 | 


--------------------------------------------------------------------------------
/.github/workflows/weekly.yml:
--------------------------------------------------------------------------------
 1 | name: Weekly CI
 2 | on:
 3 |   schedule:
 4 |     - cron: 0 0 * * 1 # At 00:00 on Monday
 5 | 
 6 | jobs:
 7 |   tests:
 8 |     strategy:
 9 |       fail-fast: false
10 |       matrix:
11 |         include:
12 |           - {os: ubuntu-latest, crystal: latest}
13 |           - {os: ubuntu-latest, crystal: nightly}
14 |           - {os: macos-latest}
15 |           - {os: windows-latest}
16 | 
17 |     name: Tests
18 |     runs-on: ${{matrix.os}}
19 |     steps:
20 |       - name: Download source
21 |         uses: actions/checkout@v3
22 | 
23 |       - name: Install Crystal
24 |         uses: crystal-lang/install-crystal@v1
25 |         with:
26 |           crystal: ${{matrix.crystal}}
27 |           shards: false
28 | 
29 |       - name: Run tests
30 |         run: crystal spec
31 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | /doc/
 2 | /libs/
 3 | /.crystal/
 4 | /.shards/
 5 | 
 6 | 
 7 | # Libraries don't need dependency lock
 8 | # Dependencies will be locked in application that uses them
 9 | /shard.lock
10 | 
11 | 


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


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # html_builder [![Build Status](https://travis-ci.org/crystal-lang/html_builder.svg)](https://travis-ci.org/crystal-lang/html_builder)
  2 | 
  3 | DSL for creating HTML programatically (extracted from Crystal's standard library).
  4 | 
  5 | ## Installation
  6 | 
  7 | Add this to your application's `shard.yml`:
  8 | 
  9 | ```yaml
 10 | dependencies:
 11 |   html_builder:
 12 |     github: crystal-lang/html_builder
 13 | ```
 14 | 
 15 | 
 16 | ## Usage
 17 | 
 18 | #### Basic usage
 19 | ```crystal
 20 | require "html_builder"
 21 | 
 22 | html = HTML.build do
 23 |   a(href: "http://crystal-lang.org") do
 24 |     text "crystal is awesome"
 25 |   end
 26 | end
 27 | 
 28 | puts html
 29 | ```
 30 | 
 31 | **Output** (this output is formatted for better display):
 32 | ```html
 33 | <a href="http://crystal-lang.org">
 34 |   crystal is awesome
 35 | </a>
 36 | ```
 37 | 
 38 | 
 39 | #### Full HTML5 page
 40 | ```crystal
 41 | html = HTML.build do
 42 |   doctype
 43 |   html(lang: "pt-BR") do
 44 |     head do
 45 |       title { text "Crystal Programming Language" }
 46 | 
 47 |       meta(charset: "UTF-8")
 48 |     end
 49 |     body do
 50 |       a(href: "http://crystal-lang.org") { text "Crystal rocks!" }
 51 |       form(method: "POST") do
 52 |         input(name: "name")
 53 |       end
 54 |     end
 55 |   end
 56 | end
 57 | 
 58 | puts html
 59 | ```
 60 | 
 61 | **Output** :
 62 | ```html
 63 | <!DOCTYPE html>
 64 | 
 65 | <html lang="pt-BR">
 66 |   <head>
 67 |     <title>Crystal Programming Language</title>
 68 | 
 69 |     <meta charset="UTF-8">
 70 |   </head>
 71 | 
 72 |   <body>
 73 |     <a href="http://crystal-lang.org">Crystal rocks!</a>
 74 |     <form method="POST">
 75 |       <input name="name">
 76 |     </form>
 77 |   </body>
 78 | </html>
 79 | ```
 80 | 
 81 | #### Custom tags
 82 | 
 83 | ```crystal
 84 | html = HTML.build do
 85 |   tag("v-button", to: "home") { text "Home" }
 86 | end
 87 | 
 88 | puts html
 89 | ```
 90 | 
 91 | **Output**:
 92 | ```html
 93 | <v-button to="home">
 94 |   Home
 95 | </v-button>
 96 | ```
 97 | 
 98 | #### Safety
 99 | 
100 | HTML::Builder escapes attribute values:
101 | ```crystal
102 | html = HTML.build do
103 |   a(href: "<>") { }
104 | end
105 | 
106 | puts html
107 | ```
108 | 
109 | **Output**:
110 | ```html
111 | <a href="&lt;&gt;"></a>
112 | ```
113 | 
114 | And escapes text:
115 | ```crystal
116 | html = HTML.build do
117 |   a { text "<>" }
118 | end
119 | 
120 | puts html
121 | ```
122 | 
123 | **Output**:
124 | ```html
125 | <a>&lt;&gt;</a>
126 | ```
127 | ## Contributing
128 | 
129 | 1. Fork it ( https://github.com/crystal-lang/html_builder/fork )
130 | 2. Create your feature branch (git checkout -b my-new-feature)
131 | 3. Commit your changes (git commit -am 'Add some feature')
132 | 4. Push to the branch (git push origin my-new-feature)
133 | 5. Create a new Pull Request
134 | 


--------------------------------------------------------------------------------
/shard.yml:
--------------------------------------------------------------------------------
1 | name: html_builder
2 | version: 0.2.2
3 | 
4 | authors:
5 |   - Ary Borenszweig <aborenszweig@manas.com.ar>
6 | 
7 | license: MIT
8 | 


--------------------------------------------------------------------------------
/spec/html_builder_spec.cr:
--------------------------------------------------------------------------------
 1 | require "./spec_helper"
 2 | require "../src/html/builder"
 3 | 
 4 | describe HTML::Builder do
 5 |   it "builds html" do
 6 |     str = HTML::Builder.build do
 7 |       doctype
 8 |       html do
 9 |         head do
10 |           title { text "Crystal Programming Language" }
11 |         end
12 |         body do
13 |           a(href: "http://crystal-lang.org") { text "Crystal rocks!" }
14 |           form(method: "POST") do
15 |             input(name: "name")
16 |           end
17 |         end
18 |       end
19 |     end
20 |     str.should eq %(<!DOCTYPE html><html><head><title>Crystal Programming Language</title></head><body><a href="http://crystal-lang.org">Crystal rocks!</a><form method="POST"><input name="name"></form></body></html>)
21 |   end
22 | 
23 |   it "builds html with some tag attributes" do
24 |     str = HTML::Builder.new.build do
25 |       a(href: "http://crystal-lang.org", class: "crystal", id: "main") do
26 |         text "Crystal rocks!"
27 |       end
28 |     end
29 |     str.should eq %(<a href="http://crystal-lang.org" class="crystal" id="main">Crystal rocks!</a>)
30 |   end
31 | 
32 |   it "builds html with some tag attributes, using a hash" do
33 |     str = HTML::Builder.new.build do
34 |       a(href: "http://crystal-lang.org", class: "crystal", id: "main") do
35 |         text "Crystal rocks!"
36 |       end
37 |     end
38 |     str.should eq %(<a href="http://crystal-lang.org" class="crystal" id="main">Crystal rocks!</a>)
39 |   end
40 | 
41 |   it "builds html with some tag attributes, using a named tuple" do
42 |     str = HTML::Builder.new.build do |builder|
43 |       builder.a({href: "http://crystal-lang.org", class: "crystal", id: "main"}) do
44 |         text "Crystal rocks!"
45 |       end
46 |     end
47 |     str.should eq %(<a href="http://crystal-lang.org" class="crystal" id="main">Crystal rocks!</a>)
48 |   end
49 | 
50 |   it "builds html with an provided html string" do
51 |     str = HTML::Builder.new.build do
52 |       html "<section>Crystal rocks!</section>"
53 |     end
54 |     str.should eq %(<section>Crystal rocks!</section>)
55 |   end
56 | 
57 |   it "builds html with a custom tag with attributes" do
58 |     str = HTML::Builder.new.build do
59 |       tag("section", class: "crystal") { text "Crystal rocks!" }
60 |     end
61 |     str.should eq %(<section class="crystal">Crystal rocks!</section>)
62 |   end
63 | 
64 |   it "escapes attribute values" do
65 |     str = HTML::Builder.new.build do
66 |       a(href: "<>") { }
67 |     end
68 |     str.should eq %(<a href="&lt;&gt;"></a>)
69 |   end
70 | 
71 |   it "escapes text" do
72 |     str = HTML::Builder.new.build do
73 |       a { text "<>" }
74 |     end
75 |     str.should eq %(<a>&lt;&gt;</a>)
76 |   end
77 | end
78 | 


--------------------------------------------------------------------------------
/spec/spec_helper.cr:
--------------------------------------------------------------------------------
1 | require "spec"
2 | require "../src/html_builder"
3 | 


--------------------------------------------------------------------------------
/src/html/builder/builder.cr:
--------------------------------------------------------------------------------
  1 | require "html"
  2 | 
  3 | # Defines a DSL for creating HTML.
  4 | #
  5 | # Usage:
  6 | #
  7 | # ```
  8 | # require "html_builder"
  9 | #
 10 | # html = HTML.build do
 11 | #   a(href: "http://crystal-lang.org") do
 12 | #     text "crystal is awesome"
 13 | #   end
 14 | # end
 15 | #
 16 | # puts html # => %(<a href="http://crystal-lang.org">crystal is awesome</a>)
 17 | # ```
 18 | struct HTML::Builder
 19 |   # Creates a new HTML::Builder, yields with with `with ... yield`
 20 |   # and then returns the resulting string.
 21 |   def self.build
 22 |     new.build do |builder|
 23 |       with builder yield builder
 24 |     end
 25 |   end
 26 | 
 27 |   def initialize
 28 |     @buffer = String::Builder.new
 29 |   end
 30 | 
 31 |   def build
 32 |     with self yield self
 33 |     @buffer.to_s
 34 |   end
 35 | 
 36 |   # Renders `HTML` doctype tag.
 37 |   #
 38 |   # ```
 39 |   # HTML::Builder.new.build { doctype } # => <doctype/>
 40 |   # ```
 41 |   def doctype
 42 |     @buffer << "<!DOCTYPE html>"
 43 |   end
 44 | 
 45 |   # Renders escaped text in html tag.
 46 |   #
 47 |   # ```
 48 |   # HTML::Builder.new.build { text "crystal is awesome" }
 49 |   # # => crystal is awesome
 50 |   # ```
 51 |   def text(text)
 52 |     HTML.escape(text, @buffer)
 53 |   end
 54 | 
 55 |   # Renders the provided html string.
 56 |   #
 57 |   # ```
 58 |   # HTML::Builder.new.build { html "<p>crystal is awesome</p>" }
 59 |   # # => <p>crystal is awesome</p>
 60 |   # ```
 61 |   def html(html)
 62 |     @buffer << html
 63 |   end
 64 | 
 65 |   # Renders the provided html tag with any options.
 66 |   #
 67 |   # ```
 68 |   # HTML::Builder.new.build do
 69 |   #   tag("section", {class: "crystal"}) { text "crystal is awesome" }
 70 |   # end
 71 |   # # => <section class="crystal">crystal is awesome</section>
 72 |   # ```
 73 |   def tag(name, attrs)
 74 |     @buffer << "<"
 75 |     @buffer << name
 76 |     append_attributes_string(attrs)
 77 |     @buffer << ">"
 78 |     with self yield self
 79 |     @buffer << "</"
 80 |     @buffer << name
 81 |     @buffer << ">"
 82 |   end
 83 | 
 84 |   def tag(name, **attrs)
 85 |     @buffer << "<"
 86 |     @buffer << name
 87 |     append_attributes_string(**attrs)
 88 |     @buffer << ">"
 89 |     with self yield self
 90 |     @buffer << "</"
 91 |     @buffer << name
 92 |     @buffer << ">"
 93 |   end
 94 | 
 95 |   {% for tag in %w(a abbr address article aside audio b bdi bdo blockquote body button canvas caption cite code colgroup data datalist dd del details dfn dialog div dl dt em fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 head header hgroup html i ins kbd label legend li main map mark menu meter nav noscript object ol optgroup option output p picture pre progress q rp rt ruby s samp script section select slot small span strong style sub summary sup svg table tbody td template textarea tfoot th thead time title tr u ul var video) %}
 96 |     # Renders `{{tag.id.upcase}}` html tag with any options.
 97 |     #
 98 |     # ```
 99 |     # HTML::Builder.new.build do
100 |     #   {{tag.id}}({:class => "crystal" }) { text "crystal is awesome" }
101 |     # end
102 |     # # => <{{tag.id}} class="crystal">crystal is awesome</{{tag.id}}>
103 |     # ```
104 |     def {{tag.id}}(attrs)
105 |       @buffer << "<{{tag.id}}"
106 |       append_attributes_string(attrs)
107 |       @buffer << ">"
108 |       with self yield self
109 |       @buffer << "</{{tag.id}}>"
110 |     end
111 | 
112 |     # Renders `{{tag.id.upcase}}` html tag with any options.
113 |     #
114 |     # ```
115 |     # HTML::Builder.new.build do
116 |     #   {{tag.id}}(class: "crystal") { text "crystal is awesome" }
117 |     # end
118 |     # # => <{{tag.id}} class="crystal">crystal is awesome</{{tag.id}}>
119 |     # ```
120 |     def {{tag.id}}(**attrs)
121 |       @buffer << "<{{tag.id}}"
122 |       append_attributes_string(**attrs)
123 |       @buffer << ">"
124 |       with self yield self
125 |       @buffer << "</{{tag.id}}>"
126 |     end
127 |   {% end %}
128 | 
129 |   {% for tag in %w(area base br col embed hr img input link meta source track wbr) %}
130 |     # Renders `{{tag.id.upcase}}` html tag with any options.
131 |     #
132 |     # ```
133 |     # HTML::Builder.new.build do
134 |     #   {{tag.id}}({:class => "crystal")
135 |     # end
136 |     # # => <{{tag.id}} class="crystal">
137 |     # ```
138 |     def {{tag.id}}(attrs)
139 |       @buffer << "<{{tag.id}}"
140 |       append_attributes_string(attrs)
141 |       @buffer << ">"
142 |     end
143 | 
144 |     # Renders `{{tag.id.upcase}}` html tag with any options.
145 |     #
146 |     # ```
147 |     # HTML::Builder.new.build do
148 |     #   {{tag.id}}(class: "crystal")
149 |     # end
150 |     # # => <{{tag.id}} class="crystal">
151 |     # ```
152 |     def {{tag.id}}(**attrs)
153 |       @buffer << "<{{tag.id}}"
154 |       append_attributes_string(**attrs)
155 |       @buffer << ">"
156 |     end
157 |   {% end %}
158 | 
159 |   private def append_attributes_string(attrs)
160 |     attrs.try &.each do |name, value|
161 |       @buffer << " "
162 |       @buffer << name
163 |       @buffer << %(=")
164 |       HTML.escape(value, @buffer)
165 |       @buffer << %(")
166 |     end
167 |   end
168 | 
169 |   private def append_attributes_string(**attrs)
170 |     attrs.each do |name, value|
171 |       @buffer << " "
172 |       @buffer << name
173 |       @buffer << %(=")
174 |       HTML.escape(value, @buffer)
175 |       @buffer << %(")
176 |     end
177 |   end
178 | end
179 | 
180 | module HTML
181 |   # Convenience method which invokes `HTML::Builder#build`.
182 |   def self.build
183 |     HTML::Builder.build do |builder|
184 |       with builder yield builder
185 |     end
186 |   end
187 | end
188 | 


--------------------------------------------------------------------------------
/src/html/builder/version.cr:
--------------------------------------------------------------------------------
1 | struct HTML::Builder
2 |   VERSION = "0.2.2"
3 | end
4 | 


--------------------------------------------------------------------------------
/src/html_builder.cr:
--------------------------------------------------------------------------------
1 | require "./html/builder"
2 | 


--------------------------------------------------------------------------------