haml_user_tags 0.9.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MTY2YzM3MWE1NmUyY2M1MDQ0YmYzZDIxNTE2YmYxOWIwMTk0NjhkMw==
+  data.tar.gz: !binary |-
+    YjQ5YzM4ODRmZTY4MTE5ZTAzZjE5MGFkNTNiMDM0MDE0MjA1NjZiOA==
+SHA512:
+  metadata.gz: !binary |-
+    MWRkNDEyMjQ2ZmQ5MTAxZjAxNTUxNzg0Y2E5ODM2MDZhZjQ3Yzc1YjRhYTli
+    N2NlMzE4MDA5OTZkZmEzM2RhNGM4MjQ1ZGIzYzNlNzY5NGE2MDNiYjc3MDk4
+    Nzc1NGRlOTVhY2Y3MmEzMzM5YzhiOWZiOGVjOTRlN2Y1NWNhNjc=
+  data.tar.gz: !binary |-
+    YmYyMzllODZkYzMzZjg2YzM2NjY5YWUwNjI1NmQ1NWZlOWFiZTRjZjliYzAz
+    ZDY5ZmE0OWVjMzQwNGQ0ZDcxMTA3NDM1MDhiZmFjNjZjOWE1OWZmYWU3MzQz
+    MzM1MDk0ZmIxZjcxNTQzNGVmZmY5YTAwZTBjMjYwYzNhNDhjNDI=

data/.gitignore

@@ -0,0 +1,24 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+/site/public
+/publish

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in haml_user_tags.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Ryan Patterson
+
+MIT License
+
+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,50 @@
+# HamlUserTags
+
+Define reusable functions in Haml that can be called with native Haml syntax.
+
+## Features
+
+- Native Haml syntax for calling helper functions
+- Ability to define helper functions using Haml
+- Ability to include user tags from one Haml file in another
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'haml_user_tags'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install haml_user_tags
+
+## Usage
+
+TODO: Write usage instructions here
+
+## TODO
+
+- Verify it works on Ruby 1.9.7 / Rails 3.2.9
+- Find best use cases inside SI code and bring in
+- Explain the lazy evaluation of content
+- Document how to migrate from partials
+- Create a wrapper around render :partial to set it as a custom tag.
+
+It should ensure that tags in the partial don't get included. Potentially use
+Haml::to_method or whatever to do the defining.
+
+## Motivation
+
+Guy Steele's [Growing a Language](http://www.cs.virginia.edu/~evans/cs655/readings/steele.pdf) ([Video](https://www.youtube.com/watch?v=_ahvzDzKdB0)) gives a great demonstration of why user tags in Haml are an essential feature.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/haml_user_tags/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,45 @@
+require "bundler/gem_tasks"
+require 'cucumber/rake/task'
+
+task :site => 'site:publish'
+namespace :site do
+  desc "Build web site and commit to gh-pages"
+  task :publish do
+    `git diff --exit-code && git diff --cached --exit-code`
+    unless $?.success?
+      warn "Publish the site from a clean working directory"
+      raise "Exiting"
+    end
+    local_commit = `git rev-parse HEAD`
+    cmd = [
+      'cd site',
+      'stasis',
+      'cd ..',
+      "( [ -d publish ] || git clone -sn --branch gh-pages #{File.dirname __FILE__} publish )",
+      'cp -R site/public/ publish',
+      'cd publish',
+      'git add -A .',
+      "git commit -m 'Exported site from #{local_commit}'",
+      'git push origin gh-pages'
+    ].join " &&\n"
+    `#{cmd}`
+  end
+
+  desc "Spawn a local server for the site"
+  task :dev do
+    pid = spawn "cd site && ( stasis -d & python -m SimpleHTTPServer )"
+    begin
+      Process.wait pid
+    rescue Interrupt
+      Process.kill pid
+    end
+  end
+
+  task :default => :publish
+end
+
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = "features --format pretty"
+end
+
+task :default => :features

data/bin/hamlut

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# The command line Haml parser, augmented with HamlUserTags.
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'haml_user_tags'
+require 'haml/exec'
+
+opts = Haml::Exec::Haml.new(ARGV)
+opts.instance_eval do
+  @options[:for_engine][:compiler_class] = HamlUserTags::Compiler
+end
+opts.parse!

data/features/define_tag.feature

@@ -0,0 +1,94 @@
+Feature: Define user tags
+  HamlUserTags allows you to define a helper function directly in a Haml
+  template. The helper function will be accessible to the template it was
+  included from.
+
+  Scenario: Basic user tags
+    Given a file named "template.haml" that contains:
+      """haml
+      - define_tag :Tag do
+        %p This is Tag.
+      %Tag
+      %Tag
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      <p>This is Tag.</p>
+      <p>This is Tag.</p>
+      """
+
+  Scenario: User tags with attributes
+    Given a file named "template.haml" that contains:
+      """haml
+      - define_tag :Tag do |attributes|
+        %p= attributes.inspect
+      %Tag{ :foo => :bar }
+      %Tag#first_tag.cls
+      %Tag.a{ :class => "b" }
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      <p>{"foo"=>"bar"}</p>
+      <p>{"id"=>"first_tag", "class"=>"cls"}</p>
+      <p>{"class"=>"a b"}</p>
+      """
+
+  Scenario: User tags with content
+    Given a file named "template.haml" that contains:
+      """haml
+      - define_tag :Tag do |attributes, content|
+        %p= content
+      %Tag inline content
+      %Tag
+        %strong
+          nested content
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      <p>inline content</p>
+      <p>
+        <strong>
+          nested content
+        </strong>
+      </p>
+      """
+
+  Scenario: Lazy evaluation of content
+    Given a file named "template.haml" that contains:
+      """haml
+      - define_tag :Tag do |attributes, content|
+        - begin
+          = content
+        - rescue
+          Caught an exception!
+      %Tag
+        - raise "Threw an exception!"
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      Caught an exception!
+      """
+
+  Scenario: Pass content through multiple user tags
+    Given a file named "template.haml" that contains:
+      """haml
+      - define_tag :A do |attributes, content|
+        %p= content
+      - define_tag :B do |attributes, content|
+        %A
+          = content
+      - define_tag :C do |attributes, content|
+        %A= content
+      %B foo
+      %C bar
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      <p>foo</p>
+      <p>bar</p>
+      """

data/features/engine.feature

@@ -0,0 +1,56 @@
+Feature: Call functions from Haml
+  HamlUserTags allows you to call helper functions that have a special signature using standard Haml tag syntax.
+
+  Background:
+    Given a helper module that contains:
+      """ruby
+      def CustomTag attributes, &block
+        content = capture_haml &block if block
+        "CustomTag called with #{attributes.inspect}, #{content.inspect}"
+      end
+
+      def class_name
+        "class_name"
+      end
+      """
+
+  Scenario: Basic user tags
+    Given a file named "template.haml" that contains:
+      """haml
+      %CustomTag
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      CustomTag called with {}, nil
+      """
+
+  Scenario: User tags with attribute
+    Given a file named "template.haml" that contains:
+      """haml
+      %CustomTag#id.c1.c2{ :class => class_name, :title => 'Title' }
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      CustomTag called with {"id"=>"id", "class"=>"c1 c2 class_name", "title"=>"Title"}, nil
+      """
+
+  Scenario: User tags with content
+    Given a file named "template.haml" that contains:
+      """haml
+      %CustomTag
+      %CustomTag inline content
+      %CustomTag= "Ruby content"
+      %CustomTag
+        = "Ruby"
+        and normal
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      CustomTag called with {}, nil
+      CustomTag called with {}, "inline content"
+      CustomTag called with {}, "Ruby content"
+      CustomTag called with {}, "Ruby\nand normal\n"
+      """

data/features/include_tags.feature

@@ -0,0 +1,79 @@
+Feature: Include tags in Haml templates
+  Once you have created a template that defines some tags in Haml, those tags can be imported into other templates and reused.
+
+  Background:
+    Given a file named "helper.haml" that contains:
+      """haml
+      - define_tag :RemoteTag do
+        %p Remote tag
+
+      Output from the helper file is discarded
+      """
+
+  Scenario: Importing directly into a template
+    Given a file named "template.haml" that contains:
+      """haml
+      - include_tags "helper.haml"
+      %RemoteTag
+      %RemoteTag
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      <p>Remote tag</p>
+      <p>Remote tag</p>
+      """
+
+  Scenario: Importing into a helper
+    Given a helper module that contains:
+      """ruby
+      extend HamlUserTags::Helpers
+      include_tags "helper.haml"
+      """
+    And a file named "template.haml" that contains:
+      """haml
+      %RemoteTag
+      %RemoteTag
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """html
+      <p>Remote tag</p>
+      <p>Remote tag</p>
+      """
+
+  Scenario: Calling user tags from outside Haml
+    Given a helper module that contains:
+      """ruby
+      extend HamlUserTags::Helpers
+      include_tags "helper.haml"
+      """
+    When I evaluate the ruby code:
+      """ruby
+      foo = Class.new do
+        include CucumberHelper
+      end.new
+      foo.RemoteTag
+      """
+    Then the output should be:
+      """html
+      <p>Remote tag</p>
+      """
+
+  Scenario: Binding to the importing context
+    Given a file named "helper.haml" that contains:
+      """haml
+      - define_tag :DebugSelf do |attributes|
+        = (attributes["target"].equal?(self)).inspect
+      """
+    And a file named "template.haml" that contains:
+      """haml
+      - include_tags "helper.haml"
+      %DebugSelf{ "target" => self }
+      """
+    When I render the template "template.haml"
+    Then the output should be:
+      """
+      true
+      """
+

data/features/step_definitions.rb

@@ -0,0 +1,37 @@
+require 'haml_user_tags'
+require 'rspec/expectations'
+require 'fakefs/safe'
+
+World(RSpec::Matchers)
+
+Before do
+  module CucumberHelper
+  end
+  FakeFS.activate!
+end
+
+After do
+  Object.send(:remove_const, :CucumberHelper)
+  FakeFS.deactivate!
+end
+
+Given(/^a helper module that contains:$/) do |string|
+  CucumberHelper.module_eval string
+end
+
+Given(/^a file named "(.*?)" that contains:$/) do |name, content|
+  File.write(name, content)
+end
+
+When(/^I render the template "(.*?)"$/) do |filename|
+  template = "- extend CucumberHelper\n#{File.read(filename)}"
+  @output = HamlUserTags::Engine.new(template).to_html
+end
+
+When(/^I evaluate the ruby code:$/) do |string|
+  @output = eval(string).to_s
+end
+
+Then(/^the output should be:$/) do |string|
+  expect(@output).to be == "#{string}\n"
+end

data/haml_user_tags.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'haml_user_tags/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "haml_user_tags"
+  spec.version       = HamlUserTags::VERSION
+  spec.authors       = ["Ryan Patterson"]
+  spec.email         = ["cgamesplay@cgamesplay.com"]
+  spec.summary       = %q{Define reusable functions in Haml that can be called with native Haml syntax.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "haml", "~> 4.0"
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+
+  # Site dependencies
+  spec.add_development_dependency "stasis"
+  spec.add_development_dependency "therubyracer"
+  spec.add_development_dependency "less"
+  spec.add_development_dependency "pygments.rb"
+
+  # Test dependencies
+  spec.add_development_dependency "cucumber"
+  spec.add_development_dependency "rspec-expectations"
+  spec.add_development_dependency "fakefs"
+end

data/lib/haml_user_tags/compiler.rb

@@ -0,0 +1,50 @@
+module HamlUserTags
+  class Compiler < Haml::Compiler
+    def compile(node)
+      if node.type == :tag and node.value[:name] =~ HamlUserTags::TAG_NAME_REGEX
+        node = convert_user_tag_to_script node
+      end
+      super node
+    end
+
+    private
+    def convert_user_tag_to_script(node)
+      t = node.value
+      attributes = t[:attributes]
+      attributes_hashes = t[:attributes_hashes]
+      object_ref = t[:object_ref]
+
+      if object_ref == "nil" and attributes.length == 0 and attributes_hashes.empty?
+        attributes = "{}"
+      else
+        if attributes_hashes.empty?
+          attributes_hashes = ''
+        elsif attributes_hashes.size == 1
+          attributes_hashes = ", #{attributes_hashes.first}"
+        else
+          attributes_hashes = ", #{attributes_hashes.join(", ")}"
+        end
+        attributes = "HamlUserTags::Helpers.attributes_hash(#{inspect_obj(t[:attributes])}, #{object_ref}#{attributes_hashes})"
+      end
+
+      if node.children.length > 0
+        contents = " do"
+      elsif t[:value] and t[:parse]
+        contents = " { _hamlout.push_text(#{t[:value]}, 0, false) }"
+      elsif t[:value] and not t[:parse]
+        contents = " { _hamlout.push_text(#{inspect_obj t[:value]}, 0, false) }"
+      end
+
+      code = "#{t[:name]}(#{attributes})#{contents}"
+      script_value = t.clone.update({
+        :text => code,
+        :escape_html => false,
+        :preserve => false,
+        :keyword => nil,
+        :value => nil,
+        :parse => nil,
+      })
+      Haml::Parser::ParseNode.new(:script, node.line, script_value, node.parent, node.children)
+    end
+  end
+end

data/lib/haml_user_tags/engine.rb

@@ -0,0 +1,18 @@
+module HamlUserTags
+  class Engine < Haml::Engine
+    def initialize(template, options = {})
+      options = options.clone.update(:compiler_class => HamlUserTags::Compiler)
+      super template, options
+    end
+
+    # Defines a method for each user tag in the template that renders the tag
+    # and returns the result as a string.
+    def extend_object obj
+      mod = Module.new
+      mod.send :include, Haml::Helpers
+      render mod
+      method = obj.is_a?(Module) ? :include : :extend
+      obj.send method, mod
+    end
+  end
+end

data/lib/haml_user_tags/helpers.rb

@@ -0,0 +1,62 @@
+require 'delegate'
+
+module HamlUserTags
+  module Helpers
+    # Same as Haml::Buffer.attributes, but returns the hash instead of writing
+    # the attributes to the buffer.
+    def self.attributes_hash(class_id, obj_ref, *attributes_hashes)
+      attributes = class_id
+      attributes_hashes.each do |old|
+        Haml::Buffer.merge_attrs(attributes, Hash[old.map {|k, v| [k.to_s, v]}])
+      end
+      Haml::Buffer.merge_attrs(attributes, Haml::Buffer.new.parse_object_ref(obj_ref)) if obj_ref
+      attributes
+    end
+
+    def define_tag name, &tag
+      unless name =~ HamlUserTags::TAG_NAME_REGEX
+        raise "define_tag: #{name.inspect} is not a valid user tag name. It must match #{HamlUserTags::TAG_NAME_REGEX}"
+      end
+
+      func = proc do |attributes = {}, &contents|
+        @haml_buffer ||= Haml::Buffer.new(nil, Haml::Options.defaults)
+        tag.binding.eval("proc { |v| _hamlout = v }").call @haml_buffer
+        # Use a proxy String class that will only evaluate its contents once
+        # it is referenced. This make the behavior similar to how "yield"
+        # would be in a ruby helper.
+        content_getter = LazyContents.new { capture_haml(&contents) || "" } if contents
+        capture_haml { instance_exec attributes, content_getter, &tag }
+      end
+
+      define_singleton_method name, &func
+      if self.is_a?(Module)
+        define_method name, &func
+      end
+    end
+
+    def include_tags path
+      source = File.read path
+      HamlUserTags::Engine.new(source).extend_object self
+      nil
+    end
+  end
+
+  class LazyContents < DelegateClass(String)
+    def initialize(&generator)
+      @generator = generator
+    end
+
+    def __getobj__
+      unless @results
+        @results, @generator = @generator.call, nil
+      end
+      @results
+    end
+  end
+end
+
+module Haml
+  module Helpers
+    include HamlUserTags::Helpers
+  end
+end

data/lib/haml_user_tags/rails/helpers.rb

@@ -0,0 +1,21 @@
+module HamlUserTags
+  module Helpers
+    alias_method :include_tags_without_rails, :include_tags
+    # Override the base include_tags to take advantage of Rails' template
+    # location features
+    def include_tags path
+      view_paths = ActionController::Base._view_paths
+      lookup_context = ActionView::LookupContext.new(view_paths, {}, [])
+      template = lookup_context.find_template(path, [], true)
+      HamlUserTags::Engine.new(template.source).extend_object self
+      nil
+    end
+
+    class << self
+      def attributes_hash_with_indifference *args
+        ActiveSupport::HashWithIndifferentAccess.new attributes_hash_without_indifference *args
+      end
+      alias_method_chain :attributes_hash, :indifference
+    end
+  end
+end

data/lib/haml_user_tags/rails/reloader.rb

@@ -0,0 +1,11 @@
+module HamlUserTags
+  class Reloader < Rails::Railtie
+    initializer "haml_user_tags.enable_reloading" do
+      watcher = ActiveSupport::FileUpdateChecker.new([], "#{Rails.root}/app/views/helpers" => %w{haml}) {}
+      Rails.application.reloaders << watcher
+      ActionDispatch::Reloader.to_prepare do
+        watcher.execute_if_updated
+      end
+    end
+  end
+end

data/lib/haml_user_tags/version.rb

@@ -0,0 +1,3 @@
+module HamlUserTags
+  VERSION = "0.9.0"
+end

data/lib/haml_user_tags.rb

@@ -0,0 +1,17 @@
+require "haml"
+require "haml_user_tags/version"
+require "haml_user_tags/compiler"
+require "haml_user_tags/engine"
+require "haml_user_tags/helpers"
+
+module HamlUserTags
+  TAG_NAME_REGEX = /^[A-Z][a-zA-Z]*$/
+end
+
+if defined? ActiveSupport
+  require 'haml_user_tags/rails/helpers'
+  require "haml_user_tags/rails/reloader"
+
+  # Set up Haml to use HamlUserTags by default
+  Haml::Template.options[:compiler_class] = HamlUserTags::Compiler
+end