express_templates 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f322ad6cb1fb8bf620577f100a9a70274c6172d1
+  data.tar.gz: ea903155b79430c8e5ec5f557ea80ee7461d9fdd
+SHA512:
+  metadata.gz: 9b71ed00ff0f5a2424a94b84da6c4104b988942b9fa37d7e36ec7c892118ccc33be46893c862be0e5ffec0b2ded2c5ed844d713e7650b3f5d0c82f0f78d0e726
+  data.tar.gz: d026690d15f79913cd90f112f437990449af06c795e718cf512a2d1a34d037ffa43e8e8161b20f9a7db4ebe9cf4aee9ea34421f628449d5f51b2584f98460446

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 ÆLOGICA | Build it better here.
+
+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,53 @@
+# ExpressTemplates
+
+Provides a macro-ish DSL for use in constructing html templates in plain Ruby as an alternative to Erb or HAML.
+
+## Usage
+
+Add this to your gemfile:
+
+    gem 'express_templates'
+
+Rename your application.html.erb to application.html.et.
+
+Change your template to look like this.
+
+    html(lang: "en") {
+      head {
+        meta charset: 'utf-8'
+        meta name: 'viewport', content: "width=device-width, initial-scale=1.0"
+        title {
+          content_for(:title)
+        }
+        stylesheet_link_tag "application", media: 'all', 'data-turbolinks-track' => true
+        csrf_meta_tags
+      }
+      body {
+        yield
+        javascript_include_tag "application"
+      }
+    }
+
+Everything should work as you would expect.
+
+Set your editor syntax for .et files to Ruby.
+
+### How It Works
+
+ExpressTemplates works via a good-enough stand in for a true macro system in Ruby which would make this type of thing considerably easier.
+
+Basically, we use these "macros" and Ruby's block structure to build up a tree of components corresponding to the HTML structure of a document fragment.  Each HTML5 tag is a component available in the form of a macro.  Unrecognized identifiers are wrapped for later evaluation, presumably in a ViewContext.
+
+yield and local variables which we may expect to be available in a view context are also wrapped for evaluation later.
+
+## Background
+
+Sufficent motivation for this gem can be explained thusly:  The bondage of HAML is unnecessary.  The clutter of Erb is unsightly.
+
+I generall prefer "one syntax per file" for reasons of cognative load and maintainability.
+
+Ultimately my objective with ExpressTemplates is to get away from writing HTML directly and to use this as a substrate for building pages out of higher-level, reusable components which include not only DOM elements but also behaviors.
+
+ExpressTemplates are part of the AppExpress platform at [appexpress.io](http://appexpress.io).
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ExpressTemplates'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/express_templates/component.rb

@@ -0,0 +1,92 @@
+module ExpressTemplates
+  class Component
+
+    attr_accessor :children
+
+    INDENT = '  '
+
+    def initialize(*children_or_options)
+      @children = []
+      @options = {}.with_indifferent_access
+      _process(*children_or_options)
+    end
+
+    def self.macro_name
+      @macro_name ||= to_s.split('::').last.underscore
+    end
+
+    def macro_name ; self.class.macro_name end
+
+    def html_options
+      @options.each_pair.map do |name, value|
+        %Q(#{name}=\\"#{value}\\")
+      end.join(" ")
+    end
+
+    def start_tag
+      "<#{macro_name}#{html_options.empty? ? '' : ' '+html_options}>"
+    end
+
+    def close_tag
+      "</#{macro_name}>"
+    end
+
+    def add_css_class(css_class)
+      @options['class'] ||= ''
+      @options['class'] = (@options['class'].split + [css_class]).join(" ")
+    end
+
+    def method_missing(name, *args)
+      add_css_class(name)
+      _process(*args) unless args.empty?
+      return self
+    end
+
+    def compile
+      ruby_fragments = @children.map do |child|
+        if child.respond_to?(:compile)
+          child.compile
+        else
+          %Q("#{child}")
+        end
+      end
+      ruby_fragments.unshift %Q("#{start_tag}")
+      ruby_fragments.push %Q("#{close_tag}")
+      ruby_fragments.reject {|frag| frag.empty? }.join("+")
+    end
+
+    def to_template(depth = 0)
+      template_fragments = @children.map do |child|
+        if child.kind_of?(ExpressTemplates::Component)
+          child.to_template(depth+1)
+        else
+          child
+        end
+      end
+      indent = INDENT*(depth+1)
+      macro_name + _blockify(template_fragments.join("\n#{indent}"), depth)
+    end
+
+    private
+      def _indent(code)
+        code.split("\n").map {|line| INDENT + line }.join("\n")
+      end
+
+      def _blockify(code, depth)
+        indent = INDENT*depth
+        code.empty? ? code : " {\n#{_indent(code)}\n}\n"
+      end
+
+      def _process(*children_or_options)
+        children_or_options.each do |child_or_option|
+          if child_or_option.kind_of?(Hash)
+            @options.merge!(child_or_option)
+          else
+            @children << child_or_option
+          end
+        end
+      end
+
+
+  end
+end

data/lib/express_templates/components/html_tag.rb

@@ -0,0 +1,36 @@
+module ExpressTemplates
+  module Components
+    class HtmlTag < ExpressTemplates::Component
+      TAGS = [ :a, :abbr, :address, :area, :article, :aside, :audio,
+               :b, :base, :bdi, :bdo, :blockquote, :body, :br, :button,
+               :canvas, :caption, :cite, :code, :col, :colgroup,
+               :data, :datalist, :dd, :del, :details, :dfn, :div, :dl, :dt,
+               :em, :embed,
+               :fieldset, :figcaption, :figure, :footer, :form,
+               :h1, :h2, :h3, :h4, :h5, :h6, :head, :header, :hr, :html,
+               :i, :iframe, :img, :input, :ins,
+               :kbd, :keygen,
+               :label, :legend, :li, :link,
+               :main, :map, :mark, :math, :menu, :menuitem, :meta, :meter,
+               :nav, :noscript,
+               :object, :ol, :optgroup, :option, :output,
+               :p, :param, :pre, :progress,
+               :q,
+               :rp, :rt, :ruby,
+               :s, :samp, :script, :section, :select, :small, :source,
+               :span, :strong, :style, :sub, :sup, :summary, :svg,
+               :table, :tbody, :td, :textarea, :tfoot, :th, :thead, :time, :title,
+               :tr, :track,
+               :u, :ul,
+               :var, :video,
+               :wbr]
+
+    end
+
+    HtmlTag::TAGS.each do |tag|
+      klass = tag.to_s.titleize
+      ExpressTemplates::Components.module_eval "class #{klass} < HtmlTag ; end"
+    end
+
+  end
+end

data/lib/express_templates/components/wrapper.rb

@@ -0,0 +1,51 @@
+module ExpressTemplates
+  module Components
+    # wrap locals and helpers for evaluation during render
+    class Wrapper
+
+      attr_accessor :name, :args
+
+      def initialize(name, *args)
+        @name = name
+        @args = args
+      end
+
+      def compile
+        # insure nils do not blow up view
+        %Q("\#\{#{_compile}\}")
+      end
+
+      def to_template
+        _compile
+      end
+
+      def children
+        []
+      end
+
+      private
+        def _compile
+          if @args.empty?
+            return name
+          else
+            args_string = args.slice(0..-2).map(&:inspect).join(', ')
+            last_arg = ''
+            if args.last.is_a?(Hash) # expand a hash
+              unless args.last.empty?
+                # This approach has limitations - will only work on structures of
+                # immediate values
+                last_arg = args.last.inspect.match(/^\{(.*)\}$/)[1]
+                last_arg.gsub!(/:(\w+)=>/, '\1: ') # use ruby 2 hash syntax
+              else
+                last_arg = "{}" # empty hash
+              end
+            else
+              last_arg = args.last.inspect
+            end
+            args_string << (args_string.empty? ? last_arg : ", #{last_arg}")
+            return "#{name}(#{args_string})"
+          end
+        end
+    end
+  end
+end

data/lib/express_templates/components/yielder.rb

@@ -0,0 +1,21 @@
+module ExpressTemplates
+  module Components
+    class Yielder
+      def initialize(*args)
+        @arg = args.first
+      end
+
+      def compile
+        if @arg
+          "yield(#{@arg})"
+        else
+          "yield"
+        end
+      end
+
+      def to_template
+        compile
+      end
+    end
+  end
+end

data/lib/express_templates/components.rb

@@ -0,0 +1,8 @@
+module ExpressTemplates
+  module Components
+  end
+end
+require 'express_templates/component'
+require 'express_templates/components/html_tag'
+require 'express_templates/components/wrapper'
+require 'express_templates/components/yielder'

data/lib/express_templates/expander.rb

@@ -0,0 +1,116 @@
+require 'express_templates/components'
+module ExpressTemplates
+  class Expander
+
+    cattr_accessor :module_search_space
+
+    attr_accessor :stack
+
+    def self.expand(template, source)
+      expanded = new(template).expand(source)
+      compiled = expanded.map(&:compile)
+      return compiled.join("+")
+    end
+
+    def initialize(template)
+      @template = template
+      @stack = Stack.new
+    end
+
+    def expand(source=nil, &block)
+      if source
+        modified = source.gsub(/(\W)(yield)(\.*)?/, '\1 (stack << ExpressTemplates::Components::Yielder.new(\3))')
+        modified.gsub!(/(\W)(@\w+)(\W)?/, '\1 (stack << ExpressTemplates::Components::Wrapper.new("\2") )\3')
+        instance_eval(modified, @template.inspect)
+        stack.current
+      else
+        instance_eval &block
+        stack.current
+      end
+    end
+
+    # define a "macro" method for a component
+    # these methods accept args which are passed to the
+    # initializer for the component
+    # blocks supplied are evaluated and any returned objects are
+    # added as children to the component
+    def self.register_macros_for(*components)
+      components.each do |component|
+        define_method(component.macro_name.to_sym) do |*args, &block|
+            stack << if block
+                begin
+                  stack.descend!
+                  block.call
+                  # anything stored on stack.current or on stack.next is added as a child
+                  # this is a bit problematic in the case where we would have
+                  # blocks and helpers or locals mixed
+                  component.new(*(args.push(*(stack.current))))
+                ensure
+                  stack.ascend!
+                end
+              else
+                component.new(*(args))
+              end
+        end
+      end
+    end
+
+
+    @module_search_space = [ExpressTemplates::Components]
+
+    @module_search_space.each do |mod|
+      register_macros_for(*
+        mod.constants.map { |const| [mod.to_s, const.to_s].join("::").constantize }.
+          select { |klass| klass.ancestors.include? (ExpressTemplates::Component) }
+      )
+    end
+
+    def method_missing(name, *args)
+      stack.current << ExpressTemplates::Components::Wrapper.new(name.to_s, *args)
+      nil
+    end
+
+    class Stack
+      def initialize
+        @stack = [[]]
+        @frame = 0
+      end
+
+      def all
+        @stack
+      end
+
+      def dump
+        puts "Current frame: #{@frame}"
+        puts all.map(&:inspect).join("\n")
+      end
+
+      def <<(child)
+        current << child
+        child
+      end
+
+      def current
+        @stack[@frame]
+      end
+
+      def next
+        @stack[@frame+1] ||= []
+      end
+
+      def descend!
+        @frame += 1
+        @stack[@frame] ||= []
+        @stack[@frame].clear
+        @frame
+      end
+
+      def ascend!
+        raise "Cannot ascend" if @frame <= 0
+        current.clear ;
+        self.next.clear
+        @frame -= 1
+      end
+    end
+  end
+end

data/lib/express_templates/html5_emitter.rb

@@ -0,0 +1,45 @@
+module ExpressTemplates
+
+  HTML5_TAGS = [ :a, :abbr, :address, :area, :article, :aside, :audio,
+                 :b, :base, :bdi, :bdo, :blockquote, :body, :br, :button,
+                 :canvas, :caption, :cite, :code, :col, :colgroup,
+                 :data, :datalist, :dd, :del, :details, :dfn, :div, :dl, :dt,
+                 :em, :embed,
+                 :fieldset, :figcaption, :figure, :footer, :form,
+                 :h1, :h2, :h3, :h4, :h5, :h6, :head, :header, :hr, :html,
+                 :i, :iframe, :img, :input, :ins,
+                 :kbd, :keygen,
+                 :label, :legend, :li, :link,
+                 :main, :map, :mark, :math, :menu, :menuitem, :meta, :meter,
+                 :nav, :noscript,
+                 :object, :ol, :optgroup, :option, :output,
+                 :p, :param, :pre, :progress,
+                 :q,
+                 :rp, :rt, :ruby,
+                 :s, :samp, :script, :section, :select, :small, :source,
+                 :span, :strong, :style, :sub, :sup, :summary, :svg,
+                 :table, :tbody, :td, :textarea, :tfoot, :th, :thead, :time, :title,
+                 :tr, :track,
+                 :u, :ul,
+                 :var, :video,
+                 :wbr]
+
+  module Html5Emitter
+
+    HTML5_TAGS.each do |tag|
+      define_method(tag) do |*args, &block|
+        if block
+          content_tag(tag, capture(&block), *args)
+        else
+          # adjust args because content_tag expects options in the
+          # second position when have nil content
+          if args.first.is_a?(Hash)
+            content_tag(tag, *(args.unshift(nil)))
+          else
+            content_tag(tag, *args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/express_templates/renderer.rb

@@ -0,0 +1,16 @@
+module ExpressTemplates
+  module Renderer
+    # render accepts source or block, expands to macros
+    # compiles the resulting macros 
+    # and then evaluates the resulting string of ruby in the context provided
+    def render context=nil, template_source=nil, &block
+      expander = ExpressTemplates::Expander.new(nil)
+      expanded_template = if block
+        (expander.expand(&block).map(&:compile).join(';'))
+      else
+        expander.expand(template_source).map(&:compile).join(";")
+      end
+      context.instance_eval expanded_template
+    end
+  end
+end

data/lib/express_templates/template/handler.rb

@@ -0,0 +1,15 @@
+module ExpressTemplates
+  module Template
+    class Handler
+      def self.call(template)
+        new.call(template)
+      end
+
+      def call(template)
+        # returns a string to be eval'd
+        ExpressTemplates::Expander.expand(template, template.source)
+      end
+
+    end
+  end
+end

data/lib/express_templates/version.rb

@@ -0,0 +1,3 @@
+module ExpressTemplates
+  VERSION = "0.2.0"
+end

data/lib/express_templates.rb

@@ -0,0 +1,12 @@
+module ExpressTemplates
+  require 'express_templates/template/handler'
+  require 'express_templates/html5_emitter'
+  require 'express_templates/renderer'
+  require 'express_templates/expander'
+  require 'express_templates/components'
+  extend Renderer
+  if defined?(Rails)
+    ::ActionView::Template.register_template_handler :et, ExpressTemplates::Template::Handler
+  end
+
+end

data/lib/tasks/gara_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :express_templates do
+#   # Task goes here
+# end

data/test/component_test.rb

@@ -0,0 +1,77 @@
+require 'test_helper'
+
+class ComponentTest < ActiveSupport::TestCase
+
+  class Bare < ExpressTemplates::Component ; end
+  class Sub < ExpressTemplates::Component ; end
+
+  def bare_component(*args)
+    Bare.new(*args)
+  end
+
+  def sub_component(*args)
+    Sub.new(*args)
+  end
+
+
+  test "#macro_name returns the name of the class" do
+    assert_equal 'bare', bare_component.macro_name
+  end
+
+  test "#compile returns a string" do
+    assert_kind_of String, bare_component.compile
+  end
+
+  test "has no children" do
+    assert_empty bare_component.children
+  end
+
+  def bare_with_2_children
+    component = bare_component "child1", "child2"
+  end
+
+  test "can be created with children" do
+    assert_equal 2, bare_with_2_children.children.size
+    assert_equal "child2", bare_with_2_children.children.last
+  end
+
+  test "#compile on bare_with_2_children yields '\"<bare>\"+\"child1\"+\"child2\"+\"</bare>\"'" do
+    assert_equal '"<bare>"+"child1"+"child2"+"</bare>"', bare_with_2_children.compile
+  end
+
+  test "#start_tag is my macro_name as an xml start tag" do
+    assert_equal "<#{bare_component.macro_name}>", bare_component.start_tag
+  end
+
+  test "#close_tag is my macro_name as an xml close tag" do
+    assert_equal "</#{bare_component.macro_name}>", bare_component.close_tag
+  end
+
+  def component_with_subcomponent
+    bare_component sub_component
+  end
+
+  test "#compile on component_with_subcomponent returns a string which when eval'd looks like '<bare><sub></sub></bare>'" do
+    assert_equal '<bare><sub></sub></bare>', eval(component_with_subcomponent.compile)
+  end
+
+  test "#to_template on bare_component returns 'bare'" do
+    assert_equal 'bare', bare_component.to_template
+  end
+
+  test "#to_template on component_with_subcomponent returns 'bare {\n  sub\n}\n'" do
+    assert_equal "bare {\n  sub\n}\n", component_with_subcomponent.to_template
+  end
+
+  test "#to_template on nested components indents properly'" do
+    expected = %Q(bare {
+  sub {
+    sub
+  }
+}
+)
+    assert_equal expected, Bare.new(Sub.new(Sub.new)).to_template
+  end
+
+
+end

data/test/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Rails.application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/test/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any styles
+ * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
+ * file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,5 @@
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+end

data/test/dummy/app/controllers/hello_controller.rb

@@ -0,0 +1,5 @@
+class HelloController < ApplicationController
+  def show
+    @hello = "Hi there"
+  end
+end

data/test/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end