rubyoshka 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dcac0e7abbbb0bad4f11b3c3b500ed7c14f506d06c6aa8ecbcec4cfc3503ce16
+  data.tar.gz: 8fd105613444edd272644aff2cb054b4c0a540789f5e63f41a4d9c033fc36577
+SHA512:
+  metadata.gz: 4f693a62532ae3235383068ed789cc144fd38ec7723c5ff728ace5b0a5b0ae267e61fc3e8140ac8972420a8c35fa0731b543dbd84016bda049843038ae5bafa4
+  data.tar.gz: 3ca48bcd081c077635cffa99d36823e2f19c1ac832a26426ae510e233d1054880a0e74b3047aeef389dcb88b4905a95339e90145cd131efcd2a8edba23599dea

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+0.1 2019-01-06
+--------------
+
+* First working version

data/README.md

@@ -0,0 +1,187 @@
+# Rubyoshka - Composable HTML templating for Ruby
+
+[INSTALL](#installing-rubyoshka) |
+[TUTORIAL](#getting-started) |
+[EXAMPLES](examples)
+
+## What is Rubyoshka
+
+Rubyoshka is an HTML templating engine for Ruby that offers the following
+features:
+
+- HTML templating using plain Ruby syntax
+- Minimal boilerplate
+- Automatic HTML escaping
+- Composable nested components
+- Access to a global context from anywhere in the component hierarchy
+- High performance
+
+With Rubyoshka you can structure your templates like a Russian doll, each
+component containing any number of nested components, in a similar fashion to
+React. The name *Rubyoshka* is a nod to Matryoshka, the Russian nesting doll.
+
+## Installing Rubyoshka
+
+```bash
+$ gem install polyphony
+```
+
+## Getting started
+
+To use Rubyoshka in your code just require it:
+
+```ruby
+require 'rubyoshka'
+```
+
+Alternatively, you can import it using [Modulation](https://github.com/digital-fabric/modulation):
+
+```ruby
+Rubyoshka = import('rubyoshka')
+```
+
+To create a template use `Rubyoshka.new` or the global method `Kernel#H`:
+
+```ruby
+# can also use Rubyoshka.new
+html = H {
+  div { p 'hello' }
+}
+```
+
+To render the template use `render`:
+
+```ruby
+H { span 'best span' }.render  #=> "<span>best span</span>"
+```
+
+The render method accepts an arbitrary context variable:
+
+```ruby
+html = H {
+  h1 context[:title]
+}
+
+html.render(title: 'My title') #=> "<h1>My title</h1>"
+```
+
+## All about tags
+
+Tags are added using unqualified method calls, and are nested using blocks:
+
+```ruby
+H {
+  html {
+    head {
+      title 'page title'
+    }
+    body {
+      article {
+        h1 'article title'
+      }
+    }
+  }
+}
+```
+
+Tag methods accept a string argument, a block, or no argument at all:
+
+```ruby
+H { p 'hello' }.render #=> "<p>hello</p>"
+
+H { p { span '1'; span '2' } }.render #=> "<p><span>1</span><span>2</span></p>"
+
+H { hr() }.render #=> "<hr/>"
+```
+
+Tag methods also accept tag attributes, given as a hash:
+
+```ruby
+H { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
+
+H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
+```
+
+## Templates as components
+
+Rubyoshka makes it easy to compose multiple templates into a whole HTML
+document. Each template can be defined as a self-contained component that can
+be reused inside other components. Components should be defined as constants,
+either in the global namespace, or on the Rubyoshka namespace:
+
+```ruby
+# Item is actually a Proc that returns a template
+Item = ->(id:, text:, checked:) {
+  H {
+    li {
+      input name: id, type: 'checkbox', checked: checked
+      label text, for: id
+    }
+  }
+}
+
+def render_items(items)
+  html = H {
+    ul {
+      items.each { |id, attributes|
+        Item id: id, text: attributes[:text], checked: attributes[:active]
+      }
+    }
+  }.render
+end
+```
+
+## Wrapping arbitrary HTML
+
+Components can be used to wrap arbitrary HTML content by defining them as procs
+that accept blocks:
+
+```ruby
+Header = ->(&inner_html) {
+  header {
+    h1 'title'
+    emit inner_html
+  }
+}
+
+H { Header { button 'OK'} }.render #=> "<header><h1>title</h1><button>OK</button></header>"
+```
+
+## Some interesting use cases
+
+Rubyoshka opens up all kinds of new possibilities when it comes to putting
+together pieces of HTML. Feel free to explore the possibilities!
+
+### Routing in the view
+
+The following example demonstrates a router component implemented as a pure
+function. The router simply returns the correct component for the given path:
+
+```ruby
+Router = ->(path) {
+  case path
+  when '/'
+    PostIndex()
+  when /^posts\/(.+)$/
+    post = get_post($1)
+    if post
+      Post(post)
+    else
+      ErrorPage(404)
+    end
+  end
+}
+
+Blog = H {
+  html {
+    head {
+      title: 'My blog'
+    }
+    body {
+      Topbar()
+      Sidebar()
+      div id: 'content' { Router(context[:path]) }
+    }
+  }
+}
+```

data/lib/rubyoshka.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'modulation/gem'
+require 'escape_utils'
+
+export_default :Rubyoshka
+
+# A Rubyoshka is a template representing a piece of HTML
+class Rubyoshka
+  # A Rendering is a rendering of a Rubyoshka
+  class Rendering
+    attr_reader :context
+  
+    # Initializes attributes and renders the given block
+    # @param context [Hash] rendering context
+    # @param block [Proc] template block
+    # @return [void]
+    def initialize(context, &block)
+      @context = context
+      @buffer = +''
+      instance_eval(&block)
+    end
+  
+    # Returns the result of the rendering
+    # @return [String]
+    def to_s
+      @buffer
+    end
+  
+    S_TAG_METHOD = <<~EOF
+      def %1$s(*args, &block)
+        tag(:%1$s, *args, &block)
+      end
+    EOF
+
+    R_CONST_SYM = /^[A-Z]/
+  
+    # Catches undefined tag method call and handles them by defining the method
+    # @param sym [Symbol] HTML tag or component identifier
+    # @param args [Array] method call arguments
+    # @param block [Proc] block passed to method call
+    # @return [void]
+    def method_missing(sym, *args, &block)
+      if sym =~ R_CONST_SYM
+        o = instance_eval(sym.to_s) rescue Rubyoshka.const_get(sym) \
+            rescue Object.const_get(sym)
+        case o
+        when ::Proc
+          self.class.define_method(sym) { |*a, &b| emit o.(*a, &b) }
+          emit o.(*args, &block)
+        when Rubyoshka
+          self.class.define_method(sym) { emit o }
+          emit(o)
+        when ::String
+          @buffer << o
+        else
+          e = StandardError.new "Cannot render #{o.inspect}"
+          e.set_backtrace(caller)
+          raise e
+        end
+      else
+        self.class.class_eval(S_TAG_METHOD % sym)
+        tag(sym, *args, &block)
+      end
+    end
+  
+    # Emits the given object into the rendering buffer
+    # @param o [Proc, Rubyoshka, String] emitted object
+    # @return [void]
+    def emit(o)
+      case o
+      when ::Proc
+        instance_eval(&o)
+      when Rubyoshka
+        instance_eval(&o.block)
+      else
+        @buffer << o.to_s
+      end
+    end
+    alias_method :e, :emit
+  
+    S_LT              = '<'
+    S_GT              = '>'
+    S_LT_SLASH        = '</'
+    S_SPACE_LT_SLASH  = ' </'
+    S_SLASH_GT        = '/>'
+    S_SPACE           = ' '
+    S_EQUAL_QUOTE     = '="'
+    S_QUOTE           = '"'
+
+    E = EscapeUtils
+  
+    # Emits an HTML tag
+    # @param sym [Symbol] HTML tag
+    # @param text [String] text content of tag
+    # @param props [Hash] tag attributes
+    # @param block [Proc] nested HTML block
+    # @return [void]
+    def tag(sym, text = nil, **props, &block)
+      sym = sym.to_s
+  
+      @buffer << S_LT << sym
+      emit_props(props) unless props.empty?
+  
+      if block
+        @buffer << S_GT
+        instance_eval(&block)
+        @buffer << S_LT_SLASH << sym << S_GT
+      elsif Rubyoshka === text
+        @buffer << S_GT
+        emit(text)
+        @buffer << S_LT_SLASH << sym << S_GT
+      elsif text
+        @buffer << S_GT << E.escape_html(text.to_s) <<
+          S_LT_SLASH << sym << S_GT
+      else
+        @buffer << S_SLASH_GT
+      end
+    end
+
+    # Emits tag attributes into the rendering buffer
+    # @param props [Hash] tag attributes
+    # @return [void]
+    def emit_props(props)
+      props.each { |k, v|
+        case k
+        when :text
+        when :src, :href
+          @buffer << S_SPACE << k.to_s << S_EQUAL_QUOTE <<
+            E.escape_uri(v) << S_QUOTE
+        else
+          if v == true
+            @buffer << S_SPACE << k.to_s
+          else
+            @buffer << S_SPACE << k.to_s << S_EQUAL_QUOTE << v << S_QUOTE
+          end
+        end
+      }
+    end
+
+    # Emits the p tag
+    # @param text [String] text content of tag
+    # @param props [Hash] tag attributes
+    # @para block [Proc] nested HTML block
+    # @return [void]
+    def p(text = nil, **props, &block)
+      tag(:p, text, **props, &block)
+    end
+  
+    S_HTML5_DOCTYPE = '<!DOCTYPE html>'
+  
+    # Emits an HTML5 doctype tag and an html tag with the given block
+    # @param block [Proc] nested HTML block
+    # @return [void]
+    def html5(&block)
+      @buffer << S_HTML5_DOCTYPE
+      self.html(&block)
+    end
+
+    # Emits text into the rendering buffer
+    # @param data [String] text
+    def text(data)
+      @buffer << E.escape_html(text)
+    end
+  end
+
+  attr_reader :block
+
+  # Initializes a Rubyoshka with the given block
+  # @param block [Proc] nested HTML block
+  # @param [void]
+  def initialize(&block)
+    @block = block
+  end
+
+  # Renders the associated block and returns the string result
+  # @param context [Hash] context
+  # @return [String]
+  def render(context = {})
+    Rendering.new(context, &block).to_s
+  end
+end
+
+module ::Kernel
+  # Convenience method for creating a new Rubyoshka
+  def H(&block)
+    Rubyoshka.new(&block)
+  end
+end

data/lib/rubyoshka/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Rubyoshka
+  VERSION = '0.1'
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: rubyoshka
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Sharon Rosner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: modulation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: escape_utils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.11.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.11.3
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.7.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.7.2
+- !ruby/object:Gem::Dependency
+  name: erubis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+description: 
+email: ciconia@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- CHANGELOG.md
+- README.md
+- lib/rubyoshka.rb
+- lib/rubyoshka/version.rb
+homepage: http://github.com/digital-fabric/rubyoshka
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/digital-fabric/rubyoshka
+post_install_message: 
+rdoc_options:
+- "--title"
+- rubyoshka
+- "--main"
+- README.md
+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.7.3
+signing_key: 
+specification_version: 4
+summary: 'Rubyoshka: composable HTML templating for Ruby'
+test_files: []