tubby 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 23fa67b928c22ddfe8a88d2a31d9aec059babbb7
+  data.tar.gz: c04266360faf36cc54e517b264f978c61a47867b
+SHA512:
+  metadata.gz: a747e3bb0a99977634b781d7892c129194e931a3b3de8d133088d74a9e542be7f5fc4308c7151e90d8ab7774d709eae34e129783540fc97366debcbad3547b5f
+  data.tar.gz: 61e61741fee0eb09789521f77098c64ef4f4e12172da9a5aa48088fa09e120346e4849dba23778c9fd54eb157455d2168be4fbf89ea07a194f1cca546ed3d39c

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Tubby CHANGELOG
+
+## Changes since previous release
+
+- Initial implementation
+

data/LICENSE.md

@@ -0,0 +1,12 @@
+Copyright (C) 2018 Magnus Holm <judofyr@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,393 @@
+# Tubby: Tags in Ruby
+
+Tubby is a lightweight library for writing HTML components in plain Ruby.
+
+```ruby
+tmpl = Tubby.new { |t|
+  t.doctype!
+
+  t.h1("Hello #{current_user}!")
+
+  t << Avatar.new(current_user)
+
+  t.ul {
+    t.li("Tinky Winky")
+    t.li("Dipsy", class: "active")
+    t.li("Laa-Laa")
+    t.li("Po")
+  }
+}
+
+class Avatar
+  def initialize(user)
+    @user = user
+  end
+
+  def url
+    # Calculate URL
+  end
+
+  def to_tubby
+    Tubby.new { |t|
+      t.div(class: "avatar") {
+        t.img(src: url)
+      }
+    }
+  end
+end
+
+puts tmpl.to_s
+```
+
+Table of contents:
+
+- [Basic usage](#basic-usage)
+- [Advanced usage](#advanced-usage)
+- [Versioning](#versioning)
+- [License](#license)
+
+## Basic usage
+
+### Creating templates
+
+`Tubby.new` accepts a block and returns a `Tubby::Template`:
+
+```ruby
+tmpl = Tubby.new { |t|
+  # content inside here
+}
+```
+
+The block will be executed once you call `#to_s` (or its alias `#to_html`):
+
+```ruby
+puts tmpl.to_s
+```
+
+### Writing HTML tags
+
+The following forms are available for writing HTML inside a template:
+
+```ruby
+# Empty tag
+t.h1
+# => <h1></h1>
+
+# Tag with content
+t.h1("Welcome!")
+# => <h1>Welcome!</h1>
+
+# Tag with attributes
+t.h1(class: "big")
+# => <h1 class="big"></h1>
+
+# Tag with attributes and content
+t.h1("Welcome!", class: "big")
+# => <h1 class="big">Welcome!</h1>
+
+# Tag with block content
+t.h1 {
+  t.span("Hello")
+}
+# => <h1><span>Hello</span></h1>
+
+# Tag with block content and attributes
+t.h1(class: "big") {
+  t.span("Hello")
+}
+# => <h1 class="big"><span>Hello</span></h1>
+
+# Tag with block content, attributes and content
+t.h1("Hello ", class: "big") {
+  t.span("world!")
+}
+# => <h1 class="big">Hello <span>world!</span></h1>
+```
+
+It's recommended to use `{ }`for nesting of tags and `do/end` for nesting of
+control flow. At first it looks weird, but otherwise it becomes hard to
+visualize the control flow:
+
+```ruby
+t.ul {
+  users.each do |user|
+    t.li {
+      t.a(user.name, href: user_path(user))
+    }
+  end
+}
+```
+
+### Writing attributes
+
+Tubby supports various ways of writing attributes:
+
+```ruby
+# Plain attribute
+t.input(value: "hello")
+# => <input value="hello">
+
+# nil/false values ignores the attribute
+t.input(value: nil)
+# => <input>
+
+# A true value doesn't generate a value
+t.input(checked: true)
+# => <input checked>
+
+# An array will be space-joined
+t.input(class: ["form-control", "error"])
+# => <input class="form-control error">
+
+# ... but nil values are ignored
+t.input(class: ["form-control", ("error" if error)])
+# => <input class="form-control">
+# => <input class="form-control error">
+```
+
+### Writing plain text
+
+Inside a template you can use `<<` to append text:
+
+```ruby
+t.h1 {
+  t << "Hello "
+  t.strong("world")
+  t << "!"
+}
+# => <h1>Hello <strong>world</strong>!</h1>
+```
+
+By default, `#to_s` will be called and the value will be escaped:
+
+```ruby
+t.h1 {
+  t << "Hello & world"
+}
+# => <h1>Hello &amp; world</h1>
+```
+
+There are three ways to avoid escaping:
+
+```ruby
+class Other
+  def to_html
+    "<custom>"
+  end
+end
+
+# (1) Appending an object which implements #to_html. Tubby will call the method
+#     and append the result without escaping it
+t << Other.new
+
+# (2) If you're using Rails, html_safe? is respected
+t << "<custom>".html_safe!
+
+# (3) There's also a separate helper
+t.raw!("<custom>")
+```
+
+In addition, there's a helper for writing a HTML5 doctype:
+
+```ruby
+t.doctype!
+# => <!DOCTYPE html>
+```
+
+### Appending other templates
+
+You can also append another template:
+
+```ruby
+content = Tubby.new { |t|
+  t.h1("Users")
+}
+
+main = Tubby.new { |t|
+  t.doctype!
+  t.head {
+    t.title("My App")
+  }
+
+  t.body {
+    t << content
+  }
+}
+```
+
+This is the main building block for creating composable templates.
+
+### Implementing `#to_tubby`
+
+Before appending, Tubby will call the `#to_tubby` method if it exists:
+
+```ruby
+class Avatar
+  def initialize(user)
+    @user = user
+  end
+
+  def url
+    # Calculate URL
+  end
+
+  def to_tubby
+    Tubby.new { |t|
+      t.div(class: "avatar") {
+        t.img(src: url)
+      }
+    }
+  end
+end
+
+tmpl = Tubby.new { |t|
+  t << Avatar.new(user)
+}
+```
+
+`#to_tubby` can return any value that `<<` accepts (i.e. strings that will be
+escaped, objects that respond to `#to_html` and so on), but most of the time you
+want to create a new template object.
+
+## Advanced usage
+
+The variable `t` in all of the examples above is an instance of
+`Tubby::Renderer`. Calling `Tubby::Template#to_s` is a shortcut for the
+following:
+
+```ruby
+tmpl = Tubby.new { |t|
+  # content inside here
+}
+
+# This:
+puts tmpl.to_s
+
+# ... is the same as:
+target = String.new
+t = Tubby::Renderer.new(target)
+t << tmpl
+puts target
+```
+
+Let's look at two ways we can customize Tubby.
+
+### Custom target
+
+The target object doesn't have to be a String, it must only be an object which
+responds to `<<`. Using a custom target might be useful if you want stream the
+HTML directly into a socket/file. For instance, this will print the HTML out to
+the standard output:
+
+```ruby
+tmpl = Tubby.new { |t|
+  t.h1("Hello terminal!")
+}
+
+t = Tubby::Renderer.new($stdout)
+t << tmpl
+```
+
+### Custom renderer
+
+You are also free to subclass the Renderer to provide additional helpers/data:
+
+```ruby
+tmpl = Tubby.new { |t|
+  t.post_form(action: t.login_path) {
+    t.input(name: "username")
+    t.input(type: "password", name: "password")
+  }
+}
+
+class Renderer < Tubby::Renderer
+  include URLHelpers
+
+  attr_accessor :csrf_token
+
+  # Renders a <form>-tag with the csrf_token
+  def post_form(**opts)
+    form(method: "post", **opts) {
+      input(type: "hidden", name: "csrf_token", value: csrf_token)
+      yield
+    }
+  end
+end
+
+target = String.new
+t = Renderer.new(target)
+t.csrf_token = "hello"
+t << tmpl
+puts target
+```
+
+You should use this feature with care as it makes your components coupled to the
+data you provide. For instance, it might be tempting to have access to the Rack
+environment as `t.rack_env`, but this means you can no longer render any HTML
+outside of a Rack context (e.g: generating email). For CSRF token it makes
+sense: it's a value which is global for the whole page, you might need it deeply
+nested inside a component, and it's a hassle to pass it along.
+
+In general however you should prefer separate classes over custom renderer methods:
+
+```ruby
+# Do this:
+
+class OkCancel
+  def initialize(cancel_link:)
+    @cancel_link = cancel_link
+  end
+
+  def to_tubby
+    Tubby.new { |t|
+      t.div(class: "btn-group") {
+        t.button("Save", class: "btn", type: "submit")
+        t.a("Cancel", class: "btn", href: @cancel_link)
+      }
+    }
+  end
+end
+
+tmpl = Tubby.new { |t|
+  t << OkCancel.new(cancel_link: "/users")
+}
+
+# Don't do this:
+
+class Renderer < Tubby::Renderer
+  def ok_cancel(cancel_link:)
+    Tubby.new { |t|
+      t.div(class: "btn-group") {
+        t.button("Save", class: "btn", type: "submit")
+        t.a("Cancel", class: "btn", href: cancel_link)
+      }
+    }
+  end
+end
+
+tmpl = Tubby.new { |t|
+  t.ok_cancel(cancel_link: "/users")
+}
+```
+
+## Versioning
+
+Tubby uses version numbers on the form MAJOR.MINOR, and releases are backwards
+compatible with earlier releases with the same MAJOR version.
+
+## License
+
+Tubby is is available under the 0BSD license:
+
+> Copyright (C) 2018 Magnus Holm <judofyr@gmail.com>
+>
+> Permission to use, copy, modify, and/or distribute this software for any
+> purpose with or without fee is hereby granted.
+>
+> THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+> REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+> AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+> INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+> LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+> OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+> PERFORMANCE OF THIS SOFTWARE.

data/lib/tubby.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+require "cgi"
+
+module Tubby
+  def self.new(&blk)
+    Template.new(&blk)
+  end
+
+  class Template
+    def initialize(&blk)
+      @blk = blk
+    end
+
+    def to_s
+      target = String.new
+      renderer = Renderer.new(target)
+      render_with(renderer)
+      target
+    end
+
+    def to_html
+      to_s
+    end
+
+    def render_with(renderer)
+      @blk.call(renderer)
+    end
+  end
+
+  class Renderer
+    def initialize(target)
+      @target = target
+    end
+
+    def <<(obj)
+      obj = obj.to_tubby if obj.respond_to?(:to_tubby)
+      if obj.is_a?(Tubby::Template)
+        obj.render_with(self)
+      elsif obj.respond_to?(:to_html)
+        @target << obj.to_html
+      elsif obj.respond_to?(:html_safe?) && obj.html_safe?
+        @target << obj
+      else
+        @target << CGI.escape_html(obj.to_s)
+      end
+      self
+    end
+
+    def raw!(text)
+      @target << text.to_s
+    end
+
+    def doctype!
+      @target << "<!DOCTYPE html>"
+    end
+
+    def __attrs!(attrs)
+      attrs.each do |key, value|
+        if value.is_a?(Array)
+          value = value.compact.join(" ")
+        end
+
+        if value
+          key = key.to_s.tr("_", "-")
+
+          if value == true
+            @target << " #{key}"
+          else
+            value = CGI.escape_html(value.to_s)
+            @target << " #{key}=\"#{value}\""
+          end
+        end
+      end
+    end
+
+    def tag!(name, content = nil, **attrs)
+      @target << "<" << name
+      __attrs!(attrs)
+      @target << ">"
+      self << content if content
+      yield if block_given?
+      @target << "</" << name << ">"
+    end
+
+    def self_closing_tag!(name, **attrs)
+      @target << "<" << name
+      __attrs!(attrs)
+      @target << ">"
+    end
+
+    TAGS = %w[
+      a abbr acronym address applet article aside audio b basefont bdi bdo big
+      blockquote body button canvas caption center cite code colgroup datalist
+      dd del details dfn dir div dl dt em fieldset figcaption figure font footer
+      form frame frameset h1 h2 h3 h4 h5 h6 head header hgroup html i iframe ins
+      kbd label legend li map mark math menu meter nav
+      object ol optgroup option output p pre progress q rp rt ruby s samp
+      section select small span strike strong style sub summary sup svg table
+      tbody td textarea tfoot th thead time title tr tt u ul var video xmp
+    ]
+
+    SELF_CLOSING_TAGS = %w[
+      base link meta hr br wbr img embed param source track area col input
+      keygen command
+    ]
+
+    TAGS.each do |name|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{name}(content = nil, **attrs, &blk)
+          tag!(#{name.inspect}, content, attrs, &blk)
+        end
+      RUBY
+    end
+
+    SELF_CLOSING_TAGS.each do |name|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{name}(**attrs)
+          self_closing_tag!(#{name.inspect}, attrs)
+        end
+      RUBY
+    end
+
+    def script(content = nil, **attrs)
+      @target << "<script"
+      __attrs!(attrs)
+      @target << ">"
+      if content
+        if content =~ /<(!--|script|\/script)/
+          raise "script tags can not contain #$&"
+        end
+        @target << content
+      end
+      @target << "</script>"
+    end
+  end
+end
+

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: tubby
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Magnus Holm
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-12-25 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- judofyr@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/tubby.rb
+homepage: https://github.com/judofyr/tubby
+licenses:
+- 0BSD
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: HTML templates as Ruby
+test_files: []