yart 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a486f79b37a640e14193d98fdd17539bdb5415a11d678a7af8db53dff2132e4
-  data.tar.gz: 2f299305146424573840e724c2daf55a2c60b36d2d0396865437e466efa33878
+  metadata.gz: 6dd8a4e37aedd9a60366cf53c6d3a270d098fb4739d2a4044b70c9515fe3f323
+  data.tar.gz: ad1b5c369574d17de2025fb1945bbb6a611d2ea88f239dfd08877af78a3e87d1
 SHA512:
-  metadata.gz: 3601a9e16a699542998eecb169156a6a41832b8f018ff20683f9b1a1a20f9a5113702d90382d9432eabae5fb1213f38cfcb56eedc84d40534ec5031f4421f1c9
-  data.tar.gz: d63dec7ebf153492407f7116f8f1da973f547e32efd20eab87b71520452b45585d868d3c3d335867345eb961f6302e060e83a74977a0e2d2c4230ab9ae9e879d
+  metadata.gz: b5eb0adbd6e5d46267db1c655248122c7e8028700ba315f16200a995d77ba4a815213a6a7b1374def5211fff61c82c3d930940cac5c907e94d4fa169cf4ed2b0
+  data.tar.gz: accd0937be8d188c1d7f5b46bd36739be711901d5eacdb667e7e891da4bc70230e00a313d314d3d46f64b5378f4670c5bef782aa2f3681c4601aedff606ab021

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+**/.byebug_history

data/Gemfile

@@ -4,6 +4,9 @@ source "https://rubygems.org"
 
 ruby "~> 2.7"
 
-gem "minitest", "~> 5.0"
-gem "rake", "~> 13.0"
-gem "rubocop", "~> 1.7"
+group :development do
+  gem "minitest", "~> 5.0"
+  gem "rake", "~> 13.0"
+  gem "rubocop", "~> 1.7"
+  gem "byebug", "~> 11.1"
+end

data/Gemfile.lock

@@ -2,6 +2,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    byebug (11.1.3)
     minitest (5.14.4)
     parallel (1.20.1)
     parser (3.0.2.0)
@@ -25,9 +26,11 @@ GEM
     unicode-display_width (2.0.0)
 
 PLATFORMS
+  ruby
   x86_64-linux
 
 DEPENDENCIES
+  byebug (~> 11.1)
   minitest (~> 5.0)
   rake (~> 13.0)
   rubocop (~> 1.7)

data/README.md

@@ -1,38 +1,44 @@
 # YART
 
-*Yet Another Ruby Templater* is yet another way to turn ruby code into HTML.
+*Yet Another Ruby Templater* turns plain Ruby into HTML making it fun to write webpages.
 
-Can be used stand alone or embedded inside a higher level templater such as `erb` or `slim`. Is super good at building the changable bits of a webpage e.g. a form for posting to the server etc.
+- YART provides an intuitive DSL that feels natural to use and removes the boiler plate from writing HTML
+- YART has zero runtime dependencies and around 100 lines of code
+- YART is fully unit tested
 
-## Usage
+## Example Usage
+
+> login.html
 
 ```ruby
-require 'yart'
+require "yart"
 
 YART.parse do
-    h1(id: :title) { 'YART' }
-    div do
-        h2 { 'Yet Another Ruby Templater' }
-        p(class: [:content, :italic]) { 'Possibly the simplest way to turn sexy Ruby into boring HTML' }
-        text { 'Ruby ruby ruby ruby aaaaahhhhhhawwwwwwwww' }
-    end
+  form action: "/auth" do
+    input type: :email, placeholder: "Email Address", required: true, close: true
+    input type: :password, placeholder: "Password", required: true, close: true
+    button(type: :submit, id: :login) { "Login" }
+  end
 end
 ```
 
-Which produces and returns (from `YART.parse`):
+Which renders:
 
 ```html
-<h1 id='title'>YART</h1>
-<div>
-    <h2>Yet Another Ruby Templater</h2>
-    <p class='content italic'>Possibly the simplest way to turn sexy Ruby into boring HTML</p>
-    Ruby ruby ruby ruby aaaaahhhhhhawwwwwwwww
-</div>
+<form action='/auth'>
+  <input type='email' placeholder='Email Address' required>
+  <input type='password' placeholder='Password' required>
+  <button type='submit' id='login'>Login</button>
+</form>
 ```
 
+Note that the above HTML snippet is *prettified* for demonstration. The actual generated HTML will be *minified*.
+
 ## Installation
 
-### Ruby Gems
+Requires Ruby `>= 2.7`
+
+### RubyGems
 
     $ gem install yart
 
@@ -40,6 +46,74 @@ Which produces and returns (from `YART.parse`):
 
     $ bundle add yart
 
+## API
+
+The best way to fully demonstrate the YART API is with a more complex example:
+
+```ruby
+require 'yart'
+
+YART.parse do
+  element "!DOCTYPE", html: true, close: true # Or just call `doctype`
+  html lang: :en do
+    head do
+      title { "YART API" }
+    end
+    body do
+      h1 { "Use a block to return a String of innerText or more elements" }
+      div data_test_id: "String attribute values will be parsed as is" do
+        h2(data_x: :sub_heading) { "Symbol attribute keys/values will be kebab-cased" }
+        text { "Set the div's innerText, before and/or after its child elements" }
+        p(class: [:content, :italic_text], id: :paragraph) do
+          "You can pass an array of attribute values and they will be space separated"
+        end
+      end
+      footer # Render an empty <footer></footer> element
+    end
+  end
+end
+```
+
+Which renders, minifies and returns the following HTML5 from `YART.parse`:
+
+```html
+<!DOCTYPE html>
+<html lang='en'>
+<head>
+  <title>YART API</title>
+</head>
+<body>
+  <h1>Use a block to return a String of innerText or more elements</h1>
+  <div data-test-id='String attribute values will be parsed as is'>
+    <h2 data-x='sub-heading'>Symbol attribute keys/values will be kebab-cased</h2>
+    Set the div's innerText, before and/or after its child elements
+    <p class='content italic-text' id='paragraph'>
+      You can pass an array of attribute values and they will be space separated
+    </p>
+  </div>
+  <footer></footer>
+</body>
+</html>
+```
+
+Main points to note:
+
+- Pass a block to `YART.parse` and it will render and return a HTML `String`.
+- Create the HTML document hierarchy using element calls and blocks.
+- Call the element as it's named in HTML, e.g. `h1`, `div`, `p` etc. This works as long as it's lowercase.
+- Call `element` when you need to render the *raw* element name (case insensitive) e.g. `!DOCTYPE`.
+- Pass the element's attributes as a `Hash` argument.
+- Pass a block to return a `String` of `innerText` or more DSL calls (which will eventually return a `String`).
+- An element doesn't require attributes or even a block. Where a block is absent, an empty element will be rendered.
+- Use the `text` method to render the `innerText` of the element when it consists of *both* inner text *and* child elements.
+- An attribute key or value of type `Symbol` will be parsed, converting `snake_case` to `kebab-case`.
+- An attribute *value* of type `String` will be parsed as is (not modified in any way).
+- An attribute *value* of `true` renders the attribute key without a value e.g. `input required: true` renders `<input required>`.
+- Several attibute *values* can be rendered by passing an `Array` e.g. `p class: [:para, :italic]`. The values will be rendered space separated.
+- Attribute *values* containing illegal characters (like quotes etc.) will be escaped in the rendered HTML.
+- The attribute `close: true` is special and tells the parser to auto-close the element (because it's empty).
+- Use the convenience methods `doctype`, `script` and `stylesheet` as needed.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/bin/console

@@ -2,14 +2,52 @@
 # frozen_string_literal: true
 
 require "bundler/setup"
-require "yart"
+require "irb"
+require "byebug" # Call "byebug" anywhere in the code to debug.
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
+# Define a method to facilitate the reloading of code changes.
+def reload
+  original_verbose = $VERBOSE
+  $VERBOSE = nil              # Suppress warning messages (from reloading CONSTANTS).
+  load "load.rb"              # (Re)load all code changes.
+  $VERBOSE = original_verbose # Activate warning messages again globally.
+  true
+end
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+# Load the most recent code into the session and include modules etc.
+reload
+
+# Load any fixture data into the session.
+def login
+  proc do
+    form action: "/auth" do
+      input type: :email, placeholder: "Email Address", required: true, close: true
+      input type: :password, placeholder: "Password", required: true, close: true
+      button(type: :submit, id: :login) { "Login" }
+    end
+  end
+end
+
+def sample
+  proc do
+    doctype
+    html lang: :en do
+      head do
+        title { "YART API" }
+      end
+      body do
+        h1 { "Use a block to return a String of innerText or more elements" }
+        div data_test_id: "String attribute values will be parsed as is" do
+          h2(data_x: :sub_heading) { "Symbol attribute keys/values will be kebab-cased" }
+          text { "Set the div's innerText, before and/or after its child elements" }
+          p(class: [:content, :italic_text], id: :paragraph) do
+            "You can pass an array of attribute values and they will be space separated"
+          end
+        end
+        footer # Render an empty <footer></footer> element
+      end
+    end
+  end
+end
 
-require "irb"
 IRB.start(__FILE__)

data/lib/yart.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "yart/version"
+require_relative "yart/parser"
 
 module YART
-  class Error < StandardError; end
-  # Your code goes here...
+  extend Parser
 end

data/lib/yart/parser.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module YART::Parser
+  CUSTOM_ATTRIBUTES = [:close]
+
+  # Parses a block of Ruby, rendering and returning a HTML String.
+  def parse(&block)
+    raise "Must pass a block to parse" unless block_given?
+
+    @@yart_buffer = []
+    instance_eval(&block)
+    @@yart_buffer.join
+  end
+
+  # Allows elements to be called and rendered via a DSL.
+  def method_missing(m, *args, &block)
+    attributes = args.fetch(0, {})
+
+    render(m, attributes, &block)
+  end
+
+  # Renders an element with the raw name (case insensitive).
+  def element(name, **attributes, &block)
+    render(name, attributes, &block)
+  end
+
+  # Renders a <!DOCTYPE html> element, for convenience.
+  def doctype
+    element("!DOCTYPE", html: true, close: true)
+  end
+
+  # Renders a JS <script src="..."> element, for convenience.
+  def script(src = nil, &block)
+    raise "Must pass a String param or a block returning a String" unless src || block_given?
+
+    src ||= block.call
+    element("script", src: src, close: true)
+  end
+
+  # Renders a CSS <link href="..."> element, for convenience.
+  def stylesheet(href = nil, &block)
+    raise "Must pass a String param or a block returning a String" unless href || block_given?
+
+    href ||= block.call
+    element("link", href: href, rel: :stylesheet, type: "text/css", close: true)
+  end
+
+  # Overrides Ruby's `p` method to render the element instead of printing.
+  def p(**attributes, &block)
+    render("p", attributes, &block)
+  end
+
+  # Sets the `innerText` of the element being rendered.
+  def text(str = nil, &block)
+    raise "Must pass a String param or a block returning a String" unless str || block_given?
+
+    str ||= block.call
+    buffer(str)
+  end
+
+  private
+
+  def buffer(str)
+    @@yart_buffer << str if str.is_a?(String)
+  end
+
+  def render(element, attributes, &block)
+    raise "Must pass attributes as a Hash" unless attributes.is_a?(Hash)
+
+    buffer(build_opening_tag(element, attributes))
+    buffer(instance_eval(&block)) if block_given?
+    buffer(build_closing_tag(element, attributes))
+  end
+
+  def build_opening_tag(element, attributes)
+    attributes_str = sanitise_attributes(attributes)
+      .reject { |k, v| CUSTOM_ATTRIBUTES.include?(k) }
+      .map { |k, v| v == true ? k.to_s : "#{k}='#{v}'" }
+      .join(" ")
+    separator = attributes_str.empty? ? "" : " "
+
+    "<#{element}#{separator}#{attributes_str}>"
+  end
+
+  def build_closing_tag(element, attributes)
+    attributes[:close] ? "" : "</#{element}>"
+  end
+
+  def sanitise_attributes(attributes)
+    attributes.map do |k, v|
+      k = kebab_case(k)
+      v = v.respond_to?(:map) ?
+        v.map { |v2| convert_attribute_value(v2) }.join(" ") :
+        convert_attribute_value(v)
+
+      [k, v]
+    end.to_h
+  end
+
+  def convert_attribute_value(value)
+    value = kebab_case(value)
+    value = replace_illegal_chars(value)
+
+    value
+  end
+
+  def kebab_case(s)
+    return s unless s.is_a?(Symbol)
+
+    s
+      .to_s
+      .gsub("_", "-")
+      .to_sym
+  end
+
+  def replace_illegal_chars(s)
+    return s unless s.is_a?(String)
+
+    s
+      .gsub('"', "&quot;")
+      .gsub("'", "&#39;")
+      .gsub("<", "&lt;")
+      .gsub(">", "&gt;")
+  end
+end

data/lib/yart/version.rb

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

data/load.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Development script which loads (all changes to) the code when called.
+
+load 'lib/yart/version.rb'
+load 'lib/yart/parser.rb'
+load 'lib/yart.rb'

data/yart.gemspec

@@ -8,9 +8,13 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Michael Telford"]
   spec.email         = ["michael.telford@live.com"]
 
-  spec.summary       = "Yet Another Ruby Templater is yet another way to turn ruby code into HTML"
+  spec.summary       = "Yet Another Ruby Templater (YART) turns plain Ruby into HTML making it fun to write webpages."
   spec.description   = <<~TEXT
-    A Ruby to HTML templater. Can be used stand alone or embedded inside a higher level templater such as erb or slim. Is super good at building the changable bits of a webpage e.g. a form for posting to the server etc.
+    Yet Another Ruby Templater (YART) turns plain Ruby into HTML making it fun to write webpages.
+
+    - YART provides an intuitive DSL that feels natural to use and removes the boiler plate from writing HTML
+    - YART has zero runtime dependencies and ~120 LOC
+    - YART is fully unit tested
   TEXT
   spec.homepage      = "https://github.com/michaeltelford/yart"
   spec.license       = "MIT"

metadata

@@ -1,20 +1,21 @@
 --- !ruby/object:Gem::Specification
 name: yart
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Michael Telford
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-07-27 00:00:00.000000000 Z
+date: 2021-08-03 00:00:00.000000000 Z
 dependencies: []
-description: 'A Ruby to HTML templater. Can be used stand alone or embedded inside
-  a higher level templater such as erb or slim. Is super good at building the changable
-  bits of a webpage e.g. a form for posting to the server etc.
+description: |
+  Yet Another Ruby Templater (YART) turns plain Ruby into HTML making it fun to write webpages.
 
-'
+  - YART provides an intuitive DSL that feels natural to use and removes the boiler plate from writing HTML
+  - YART has zero runtime dependencies and ~120 LOC
+  - YART is fully unit tested
 email:
 - michael.telford@live.com
 executables: []
@@ -34,7 +35,9 @@ files:
 - bin/console
 - bin/setup
 - lib/yart.rb
+- lib/yart/parser.rb
 - lib/yart/version.rb
+- load.rb
 - yart.gemspec
 homepage: https://github.com/michaeltelford/yart
 licenses:
@@ -61,5 +64,6 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Yet Another Ruby Templater is yet another way to turn ruby code into HTML
+summary: Yet Another Ruby Templater (YART) turns plain Ruby into HTML making it fun
+  to write webpages.
 test_files: []