dhtml 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d19e6ad8effeadc4ba60d79a1df5cc0a66ca25e7c8f75f513e73faf439abccf
+  data.tar.gz: 42e1449cda9a9874bd36bb0b261537c4f147b2af56b0e26aba742b231297332f
+SHA512:
+  metadata.gz: f26aaa41af798393b2865477d742bf59c9723dc3714d43e1f2e7c463c8465801c7947c1cc33b45671e05ef68f63bff1f7db5e684cbd50720d6df3f9cf18c286a
+  data.tar.gz: 07c3a590c080c087a543628db94fe171e16f7746f7863110c82b7a9a6aa18a55378d39abb95b64abd96b47251b94e25d3e0f3b4831d2f652431e8637b09d2152

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog], and this project adheres to [Semantic Versioning].
+
+## [Unreleased]
+
+## [0.1.3] - 2021-05-10
+### Fixed
+- The gemspec no longer uses absolute paths for the sources.
+
+## [0.1.2] - 2021-05-10
+### Added
+- `reset` method so the document can be generated more than once.
+
+## [0.1.0] - 2021-05-10
+- Initial release
+
+
+[Unreleased]: https://github.com/hi5dev/dhtml/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/hi5dev/dhtml/compare/v0.1.2..v0.1.0
+[0.1.0]: https://github.com/hi5dev/dhtml/releases/tag/v0.1.0
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Semantic Versioning]: https://semver.org/spec/v2.0.0.html

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake', '~> 13.0'
+
+gem 'minitest', '~> 5.14'
+
+gem 'opal', '~> 1.0'

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    dhtml (0.1.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    minitest (5.14.2)
+    opal (1.1.1)
+      ast (>= 2.3.0)
+      parser (~> 3.0)
+    parser (3.0.1.1)
+      ast (~> 2.4.1)
+    rake (13.0.3)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  dhtml!
+  minitest (~> 5.14)
+  opal (~> 1.0)
+  rake (~> 13.0)
+
+BUNDLED WITH
+   2.2.16

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Hi5 Development, LLC
+
+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,111 @@
+# DHTML
+
+A fast, simple, and elegant DSL for generating HTML using Ruby that is compatible with [Opal](https://opalrb.com/).
+
+Here's an example:
+
+```ruby
+extend DHTML
+
+doctype :html
+
+html(lang: 'en') {
+  head {
+    meta charset: 'utf-8'
+    title { 'Example' }
+    link rel: 'stylesheet', href: 'style.css'
+    script src: 'main.js'
+  }
+  body {
+    div(id: 'main') {
+      _p { <<~TEXT }
+        Some of Ruby's internal methods would be overwritten if this library added a method for all the
+        HTML tags. To solve this, the alias for these methods begins with an underscore:
+      TEXT
+
+      ol {
+        li { code { '_p' } }
+        li { code { '_select' } }
+      }
+    }
+  }
+}
+
+puts read_html
+```
+
+## Proof of Concept
+
+Using Ruby to generate HTML makes it possible to write modular, easily testable views. Here's a simple
+example:
+
+```ruby
+module Layout
+  include DHTML
+
+  def inner_body
+  end
+
+  def render
+    reset if document.length > 0
+
+    doctype :html
+
+    html do
+      head do
+        title { 'Proof of Concept' }
+      end
+      body do
+        inner_body
+      end
+    end
+
+    finish
+  end
+end
+
+class IndexPage
+  include Layout
+
+  def inner_body
+    h1 { 'It works!' }
+  end
+end
+
+page = IndexPage.new
+
+html = page.render
+
+puts html.read
+
+# => "<!doctype html><html><head><title>Proof of Concept</title></head><body><h1>It works!</h1></body></html>"
+```
+
+It's easy to see how that could be plugged into many Ruby web frameworks. Here's how the above example can work with
+Rack:
+
+```ruby
+run -> (_env) do
+  [200, { Rack::CONTENT_TYPE => 'text/html' }, IndexPage.new.render]
+end
+```
+
+## Development
+
+A `Dockerfile` and Docker Compose configuration is provided to simplify the onboarding process. After cloning this 
+repository, all you have to do to get started is run the tests with:
+
+    $ docker-compose run test
+
+You can log into the container with:
+
+    $ docker-compose run ruby ash
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/hi5dev/dhtml. Make sure to add your 
+contact information to `spec.authors` and `spec.email` in the gemspec file if you do contribute.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/dhtml.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'lib/dhtml/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'dhtml'
+  spec.version = DHTML::VERSION
+  spec.authors = ['Travis Haynes']
+  spec.email = %w[travis@hi5dev.com]
+
+  spec.summary = 'A fast, simple, and elegant DSL for generating HTML using Ruby. Also compatible with Opal.'
+  spec.description = spec.summary
+  spec.homepage = 'https://www.hi5dev.com/dhtml'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.4.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/hi5dev/dhtml'
+  spec.metadata['changelog_uri'] = 'https://github.com/hi5dev/dhtml/blob/base/CHANGELOG.md'
+
+  spec.files = %w[
+    CHANGELOG.md
+    dhtml.gemspec
+    Gemfile
+    Gemfile.lock
+    lib/dhtml.rb
+    lib/dhtml/document.rb
+    lib/dhtml/opal.rb
+    lib/dhtml/version.rb
+    LICENSE.txt
+    README.md
+  ]
+
+  spec.require_paths = %w[lib]
+end

data/lib/dhtml/document.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module DHTML
+  # Provides methods for generating HTML.
+  #
+  # @since 0.1.0
+  module Document
+    # Most commonly used HTML escape sequences.
+    #
+    # @type [Hash<String => String>]
+    # @since 0.1.0
+    ESCAPE_HTML = {
+      "'" => '&#x27;',
+      '"' => '&quot;',
+      '&' => '&amp;',
+      '/' => '&#x2F;',
+      '<' => '&lt;',
+      '>' => '&gt;',
+    }
+
+    # Regular expression that matches the most common characters that need to be escaped in HTML strings.
+    #
+    # @type [Regexp]
+    # @since 0.1.0
+    ESCAPE_HTML_PATTERN = Regexp.union(*ESCAPE_HTML.keys)
+
+    # Writes the HTML doctype.
+    #
+    # @param [Symbol] type of document
+    # @return [Integer] number of bytes written to the document.
+    # @since 0.1.0
+    def doctype(type)
+      tag = case type
+      when :html3
+        %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">|
+      when :html4
+        %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">|
+      when :html4_framesets, :html4_fr
+        %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">|
+      when :html4_transitional, :html4_tr
+        %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">|
+      when :html5, :html
+        %|<!doctype html>|
+      else
+        fail ArgumentError, "unsupported doctype: #{type.inspect}"
+      end
+
+      document.write(tag)
+    end
+
+    # The document is written to this buffer.
+    #
+    # @return [StringIO]
+    # @since 0.1.0
+    def document
+      @document ||= StringIO.new
+    end
+
+    # Rewinds the document so it can be read.
+    #
+    # @return [StringIO]
+    # @since 0.1.0
+    def finish
+      document.tap(&:rewind)
+    end
+
+    # Generates an HTML attribute (e.g. +class="form"+).
+    #
+    # @param [Symbol, String] name
+    # @param [Symbol, String] value
+    # @return [String]
+    # @since 0.1.0
+    def html_attribute(name, value)
+      [h(name.to_s), h(value.to_s).inspect].join('=')
+    end
+
+    # Generates a string of HTML attributes from a Hash.
+    #
+    # @param [Hash] attributes
+    # @return [String]
+    # @since 0.1.0
+    def html_attributes(attributes)
+      # noinspection RubyYardParamTypeMatch
+      attributes.inject([]) { _1 << html_attribute(_2[0], _2[1]) }.join(' ')
+    end
+
+    # Escape ampersands, brackets and quotes for HTML.
+    #
+    # @param [String] string to escape.
+    # @return [String] HTML escaped string.
+    # @since 0.1.0
+    def html_escape(string)
+      string.to_s.gsub(ESCAPE_HTML_PATTERN) { ESCAPE_HTML[_1] }
+    end
+
+    alias_method :h, :html_escape
+
+    # Reads the entire HTML document.
+    #
+    # @return [String]
+    # @since 0.1.0
+    def read_html
+      document.tap(&:rewind).read
+    end
+
+    # Clears all content from the document.
+    #
+    # @return [StringIO]
+    # @since 0.1.1
+    def reset
+      document.close
+      document.reopen
+    end
+
+    # Writes the opening element for the given HTML tag to the document.
+    #
+    # @!attribute [String] tag
+    # @!attribute [Hash] attributes
+    # @return [Integer] Number of bytes written to the stream.
+    # @since 0.1.0
+    def write_html_element(tag, attributes = {})
+      document << '<'
+      document << tag
+      document << " #{html_attributes(attributes)}" unless attributes.empty?
+      document << '>'
+    end
+
+    # Write a tag to the HTML document.
+    #
+    # @param [Symbol] tag name.
+    # @param [Hash] attributes for the tag.
+    # @param [Proc] inner_html to include in the tag.
+    # @return [void]
+    # @since 0.1.0
+    def write_html_tag(tag: __callee__, **attributes, &inner_html)
+      # Ensure the method isn't being called directly.
+      fail ArgumentError, 'invalid tag' if tag == :write_html_tag
+
+      # Remove the underscore prefix added to prevent conflicts with internal Ruby methods.
+      tag = tag.to_s
+      tag = tag[1..-1] if tag[0] == '_'
+
+      # Opening tag with its HTML attributes - e.g. <div id="main">
+      write_html_element(tag, attributes)
+
+      # Capture the inner HTML.
+      content = inner_html&.call(document)
+
+      # Write the inner HTML to the document when present.
+      document.write(content) if content.is_a?(String)
+
+      # Close the tag when necessary.
+      document.write("</#{tag}>") if content.is_a?(String) || block_given? || !void?(tag.to_sym)
+    end
+  end
+end

data/lib/dhtml/opal.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Only continue when not running in Opal, and the gem is available.
+return if RUBY_ENGINE == 'opal' || !defined?(Opal)
+
+# Add the library to the Opal load path when it's available.
+Opal.append_path File.expand_path(File.join('..', '..'), __FILE__)

data/lib/dhtml/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DHTML
+  # The gem's semantic version number.
+  #
+  # @see https://semver.org/spec/v2.0.0.html
+  # @type [String]
+  VERSION = '0.1.3'
+end

data/lib/dhtml.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative 'dhtml/document'
+require_relative 'dhtml/opal'
+require_relative 'dhtml/version'
+
+# @since 0.1.0
+module DHTML
+  include DHTML::Document
+
+  # List of tags that do not require a closing tag.
+  #
+  # @type [Array<Symbol>]
+  # @since 0.1.0
+  VOID_TAGS = %i[area audio base br col hr img input link meta param picture source video]
+
+  # @param [Symbol] tag
+  # @return [TrueClass, FalseClass]
+  # @since 0.1.0
+  def void?(tag)
+    VOID_TAGS.include?(tag)
+  end
+
+  if RUBY_ENGINE == 'opal'
+    # Opal does not support __callee__, so #alias_method is being overridden to provide implementation sufficient for
+    # this module.
+    #
+    # @param [Symbol] tag
+    # @return [Symbol] The name of the aliased method.
+    # @since 0.1.0
+    def self.alias_method(tag, _)
+      define_method(tag) do |**attributes, &block|
+        write_html_tag(tag: tag, **attributes, &block)
+      end
+    end
+  end
+
+  # An underscore is added to HTML tags that already have Ruby methods. This makes it both easy to remember, and to
+  # detect them in #write_html_tag.
+  begin
+    alias_method :_p, :write_html_tag
+    alias_method :_select, :write_html_tag
+  end
+
+  # The HTML tags are aliased to #write_html_tag, which uses reflection to determine which tag to generate.
+  begin
+    alias_method :a, :write_html_tag
+    alias_method :abbr, :write_html_tag
+    alias_method :address, :write_html_tag
+    alias_method :area, :write_html_tag
+    alias_method :article, :write_html_tag
+    alias_method :aside, :write_html_tag
+    alias_method :audio, :write_html_tag
+    alias_method :b, :write_html_tag
+    alias_method :base, :write_html_tag
+    alias_method :bdi, :write_html_tag
+    alias_method :bdo, :write_html_tag
+    alias_method :blockquote, :write_html_tag
+    alias_method :body, :write_html_tag
+    alias_method :br, :write_html_tag
+    alias_method :button, :write_html_tag
+    alias_method :canvas, :write_html_tag
+    alias_method :caption, :write_html_tag
+    alias_method :cite, :write_html_tag
+    alias_method :code, :write_html_tag
+    alias_method :col, :write_html_tag
+    alias_method :colgroup, :write_html_tag
+    alias_method :data, :write_html_tag
+    alias_method :datalist, :write_html_tag
+    alias_method :dd, :write_html_tag
+    alias_method :del, :write_html_tag
+    alias_method :details, :write_html_tag
+    alias_method :dfn, :write_html_tag
+    alias_method :dialog, :write_html_tag
+    alias_method :div, :write_html_tag
+    alias_method :dl, :write_html_tag
+    alias_method :dt, :write_html_tag
+    alias_method :em, :write_html_tag
+    alias_method :embed, :write_html_tag
+    alias_method :fieldset, :write_html_tag
+    alias_method :figcaption, :write_html_tag
+    alias_method :figure, :write_html_tag
+    alias_method :footer, :write_html_tag
+    alias_method :form, :write_html_tag
+    alias_method :h1, :write_html_tag
+    alias_method :h2, :write_html_tag
+    alias_method :h3, :write_html_tag
+    alias_method :h4, :write_html_tag
+    alias_method :h5, :write_html_tag
+    alias_method :h6, :write_html_tag
+    alias_method :head, :write_html_tag
+    alias_method :header, :write_html_tag
+    alias_method :hgroup, :write_html_tag
+    alias_method :hr, :write_html_tag
+    alias_method :html, :write_html_tag
+    alias_method :i, :write_html_tag
+    alias_method :iframe, :write_html_tag
+    alias_method :img, :write_html_tag
+    alias_method :input, :write_html_tag
+    alias_method :ins, :write_html_tag
+    alias_method :kbd, :write_html_tag
+    alias_method :label, :write_html_tag
+    alias_method :legend, :write_html_tag
+    alias_method :li, :write_html_tag
+    alias_method :link, :write_html_tag
+    alias_method :main, :write_html_tag
+    alias_method :map, :write_html_tag
+    alias_method :mark, :write_html_tag
+    alias_method :meta, :write_html_tag
+    alias_method :meter, :write_html_tag
+    alias_method :nav, :write_html_tag
+    alias_method :noscript, :write_html_tag
+    alias_method :object, :write_html_tag
+    alias_method :ol, :write_html_tag
+    alias_method :optgroup, :write_html_tag
+    alias_method :option, :write_html_tag
+    alias_method :output, :write_html_tag
+    alias_method :param, :write_html_tag
+    alias_method :picture, :write_html_tag
+    alias_method :pre, :write_html_tag
+    alias_method :progress, :write_html_tag
+    alias_method :q, :write_html_tag
+    alias_method :rb, :write_html_tag
+    alias_method :rp, :write_html_tag
+    alias_method :rt, :write_html_tag
+    alias_method :rtc, :write_html_tag
+    alias_method :ruby, :write_html_tag
+    alias_method :s, :write_html_tag
+    alias_method :samp, :write_html_tag
+    alias_method :script, :write_html_tag
+    alias_method :section, :write_html_tag
+    alias_method :slot, :write_html_tag
+    alias_method :small, :write_html_tag
+    alias_method :source, :write_html_tag
+    alias_method :span, :write_html_tag
+    alias_method :strong, :write_html_tag
+    alias_method :style, :write_html_tag
+    alias_method :sub, :write_html_tag
+    alias_method :summary, :write_html_tag
+    alias_method :sup, :write_html_tag
+    alias_method :table, :write_html_tag
+    alias_method :tbody, :write_html_tag
+    alias_method :td, :write_html_tag
+    alias_method :template, :write_html_tag
+    alias_method :textarea, :write_html_tag
+    alias_method :tfoot, :write_html_tag
+    alias_method :th, :write_html_tag
+    alias_method :thead, :write_html_tag
+    alias_method :time, :write_html_tag
+    alias_method :title, :write_html_tag
+    alias_method :tr, :write_html_tag
+    alias_method :track, :write_html_tag
+    alias_method :u, :write_html_tag
+    alias_method :ul, :write_html_tag
+    alias_method :var, :write_html_tag
+    alias_method :video, :write_html_tag
+    alias_method :wbr, :write_html_tag
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: dhtml
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- Travis Haynes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-05-11 00:00:00.000000000 Z
+dependencies: []
+description: A fast, simple, and elegant DSL for generating HTML using Ruby. Also
+  compatible with Opal.
+email:
+- travis@hi5dev.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- dhtml.gemspec
+- lib/dhtml.rb
+- lib/dhtml/document.rb
+- lib/dhtml/opal.rb
+- lib/dhtml/version.rb
+homepage: https://www.hi5dev.com/dhtml
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.hi5dev.com/dhtml
+  source_code_uri: https://github.com/hi5dev/dhtml
+  changelog_uri: https://github.com/hi5dev/dhtml/blob/base/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.16
+signing_key: 
+specification_version: 4
+summary: A fast, simple, and elegant DSL for generating HTML using Ruby. Also compatible
+  with Opal.
+test_files: []