tequila 0.2.1

data/.gitignore

@@ -0,0 +1,2 @@
+demo.sqlite3
+test/dbdebug.log

data/Changelog

@@ -0,0 +1,18 @@
+2010-05-08 Eugene Hlyzov  <hlyzov@gmail.com>
+	allow space between '-' and variable declaration
+	meaningful aliases for control symbols
+	add ability to omit some control symbols
+	allow using ' symbol to stress a variable
+	add 'pick all' and 'drop all' instructions
+2010-01-15 Eugene Hlyzov  <hlyzov@gmail.com>
+	[feature] Add configuration options
+	please check README - there is a change in default behaviour
+2009-11-01 Eugene Hlyzov  <hlyzov@gmail.com>
+        [feature] Add ability to specify static values
+2009-09-07 Eugene Hlyzov  <hlyzov@gmail.com>
+	[feature] Add ability to suppress labels
+	minor refactoring
+2009-09-06 Eugene Hlyzov  <hlyzov@gmail.com>
+	fix bug with nil association
+	fix bug with wrong label
+	add tests for fixed bugs

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009 Eugene Hlyzov (hlyzov[at]gmail[dot]com) 
+                   Ivan Nemytchenko (nemytchenko[at]gmail[dot]com)
+                   Alexandr Alexandrov (elequtree[at]gmail[dot]com)
+
+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.markdown

@@ -0,0 +1,213 @@
+## Overview ##
+
+Tequila basically is HAML for JSON generation.
+
+Today while developing web applications with rich user UI, almost everything you need from rails backend is bunch of data in JSON format.
+
+- Almost always, when you had to create unobvious set of data, your controllers became fat and ugly.
+
+        @humans.to_json(
+          :methods => [:login, :enhanced_name, :hello_world], :except => [:created_at, :updated_at],
+          :include => {:pets => { :except => [:human_id, :pet_type_id, :created_at, :updated_at],
+              :methods => :pet_type_name,
+              :include => { :toys => { :methods => [:railsize2], :only => [:color, :size]} }
+            }}
+          )
+
+- And you had to create a lot of small helper methods in your models if you want for example fullname instead of firstname, middlename and lastname or you want pretty address, instead of separate fields for zip, country, state and street adress in your JSON.
+- And you had to create child node in your JSON for has-one or belongs-to associations if you want to get even one attribute form association.
+- You cannot rename keys in your json. You might want to use keyword "type", but it is reserved by rails.
+- What about calling your method with some parameters while generating JSON? No native way, sorry...
+
+Tequila is an instrument, which lets easily move your JSON-generation logic from controllers to views. Take a look at features:
+
+## Features ##
+
+![Tequila features](http://inem.github.com/images/tequila-features.png)
+
+- [Here is Jazz template](http://gist.github.com/173339/)
+- [And here is it's JSON output](http://gist.github.com/173255/)
+
+## Installation ##
+
+./script/plugin install git://github.com/inem/tequila.git
+
+After that drop some Tequila code into an apropriate template (should have .jazz extension) - and you are there!
+
+## Examples ##
+
+    -@humans => people
+      :only
+        .name => login
+      :code => enhanced_name
+        name + "!!!"
+      :code => hello_world
+        "Hello world!"
+      +pets
+        :except
+          .human_id
+          .pet_type_id
+        +toys
+          :methods
+            .railsize("$", price.to_s)
+        +pet_type
+          :only
+            .class_name
+
+    -@humans => aa
+      :except
+        .name
+      :code => super_name
+        "→#{name}→"
+      +pets
+        :except
+          .human_id
+          .pet_type_id
+        +toys
+          :methods
+            .railsize("$", price.to_s)
+        +pet_type
+          :only
+            .class_name
+
+    -@humans => humanoids
+      :only
+        .name => login
+      :code => humanoid_names
+        name + "is Humanoid"
+      +pets => animals
+        :only
+          .human_id
+          .name
+        :code => humanoid_animals
+          name + "is Humanoid pet"
+        +toys
+          :only
+            .label
+        <pet_type
+          :only
+            .class_name => pet_type
+
+## Basic syntax ##
+
+Have you ever used to_json method in your Rails app? If so, you should be familiar with basic Tequila syntax. You still have your :only, :except and :methods keywords. Instead of writing
+
+    :include => { :association1 => {...}}
+
+You should just remember that every variable definition must be started '-' and every association with '+'.
+So example above can be written much shortly:
+
+    +association1
+
+## Advanced ##
+
+### Labels ###
+
+Label can be defined via expression (=> label) which can be added everywhere where it makes sense. It means that you can add label to such elements as :code, +association, etc.. and can not add label to :except declaration and :gluening object. Some functionality of these features are covered by standart Rails to_json method and some aren't. For instance, if you bind alias 'animals' to assoication 'pets' it will automatically leads to bound 'animal' label to each Pet model below such declaration (see [example](http://gist.github.com/173255/))
+
+### Call methods with params ###
+
+It is pretty simple. You just can pass any amount of params in any method in :methods definition. You should not create any presenters for model methods if you want to call them with params. Want to use instance method as param? No problem! With a bit of Tequila magic you can simple do so:
+
+    ...
+    :methods
+      .calculate(1,2,3, total_count)
+
+### Code blocks ###
+
+Code block are extremely useful if you need to add evaluable expression in the generated json but you don't want to store it as model (or presenter) method. For example you have attribute label, but for some reason you have to return "[# {label}]" just in one place of the code. The following feature allows you to keep your models clean:
+
+    ...
+    :code => plabel
+      '[' + label + ']'
+    end
+
+As result, in the generated data structure you will have additional field 'plabel' with desired value.
+
+### Gluing ###
+
+It is another nice feature which you always want to have (may be instinctively ;). Sometimes you have 'belongs_to' association where you need just one attribute. And 'gluing' allows you to.. glue attributes from child associations. Compare:
+
+    ...
+    :tag
+      :only
+        .label
+      +tagger
+        :only
+          .name
+    end
+    # Out:  {'tag' => {'label' => 'Happy Christmas!', 'tagger' => {'name' => 'Mr Lawrence"}}
+
+Generated json fragment looks like too comprehensive. Let us rewrite this fragment using gluing feature:
+
+    ...
+    :tag
+      :only
+        .label
+      <tagger
+        :only
+          .name => tagger_name
+    end
+    # Out:  {'tag' => {'label' => 'Happy Christmas!', 'tagger_name' => 'Mr Lawrence"}}
+
+Of course it can be handled via additional model methods, but latter is mere artifical solution. We are going to DRY, aren't we?
+
+### Configuration ###
+
+Since 0.1.3 there are ability to configure initial label rendering. Configuration options can be inserted either globally via Tequila::Config::Default class or locally with following syntax:
+
+    #!some_configure_option
+    USUAL_TEQUILA_CODE_HERE
+
+there are two available options:
+1. hide_initial_label!
+2. show_initial_label!
+
+It has a sense in a case when you are rendering collection of
+objects and don't want to output its label. Compare:
+
+    # show_initial_label! used
+    {"links" => [{"link" => {..}}, {"link => {..}}]}
+vs
+    # hide_initial_label! used
+    [{"link" => {..}}, {"link => {..}}]
+
+As we are going to be fully compatible with Rails, hide_initial_label! is default option now.
+To cancel it you can just add following lines somewhere in initializers:
+
+    class Tequila::Config::Default
+      show_initial_label!
+    end
+
+## Issues ##
+
+Strict order of definitions required! All blocks are optional.
+
+1. :only or :except
+2. :methods
+3. :code blocks
+4. +asscociations
+5. &lt;gluening
+
+### Benchmarks ###
+
+
+
+                        user        system      total       real
+    to_json             7.280000    0.440000    7.720000    (  7.811976)
+    jazz                25.920000   1.840000    27.760000   ( 28.229717)
+    jazz with preparse  17.210000   1.580000    18.790000   ( 19.122837)
+
+At least for these tests it looks like to_json is ~2.4x faster..
+But for some reason you use Ruby instead of C, right? Despite of the fact that Tequila is not too fast today we are happy to have such instrument and are going to develop it further. And we have good plans about it...
+
+### Plans ###
+
+- Grammatic review
+- Implement HashMapper fucntionality
+- Arbitrary order of defenitions
+- More tests for edge cases
+- More syntax sugar
+- Speedup
+
+And.. we are always open for your feedback! :)

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'test/bench'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the tequila plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+
+desc 'Benchmark'
+task :bench do
+  TequilaBenchmark.run
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.version = '0.2.1'
+    gemspec.name = "tequila"
+    gemspec.summary = "Language for advanced JSON generation"
+    gemspec.description = "Language for advanced JSON generation"
+    gemspec.email = "eugene.hlyzov@gmail.com"
+    gemspec.homepage = "http://github.com/inem/tequila"
+    gemspec.authors = ["Eugene Hlyzov", "Ivan Nemytchenko"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end

data/TODO

@@ -0,0 +1,15 @@
+BUGS:
+TODO:
+  - option to generate keys without quotes
+  - gluing for mas_many associations
+  - comments //
+  - :plain (some symbol for this?)
+  - :only            =>         .aaa
+      .aaa                      .bbb
+      .bbb
+  - :except          =>         !aaa
+      .aaa                      !bbb
+      .bbb
+  -  :plain by default
+  -  define :all by symbol
+

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/init.rb

@@ -0,0 +1,3 @@
+require 'ostruct'
+require 'treetop'
+require 'tequila_jazz_handler'

data/lib/preprocessor.rb

@@ -0,0 +1,71 @@
+module TequilaPreprocessor
+  EOB = "end\n".freeze
+  EOC = "end\n".freeze
+  JAZZ = ".jazz".freeze
+
+  def TequilaPreprocessor.run(source, offset = -1)
+    source = replace(source)
+    prev = offset
+    text = ""
+    code = nil
+    lines = source.split("\n")
+    for line in lines do
+      unless (line.strip =~ /\/\//) == 0
+        spaces, rest = spaces(line)
+        raise "#{spaces} spaces in line <#{line}>" if (spaces & 1 != 0)
+        tabs = spaces >> 1
+        if code
+          if tabs <= code
+            code = nil
+            text += EOC
+          else
+            text += "#{line}\n"
+            next
+          end
+        end
+        case rest
+        when /^:code/
+          code = tabs
+        when /^(\+|\-|\<|source|join|merge)/
+          diff = prev - tabs
+          diff += 1 if diff >= 0
+          diff.times { text += EOB }
+          prev = tabs
+        end
+        text += "#{line}\n"
+      end
+    end
+    text += EOC if code
+    (prev - offset).times { text += EOB }
+    text
+  end
+
+private
+  def TequilaPreprocessor.replace(source)
+    text = ''
+    while (i = (/(^ *)(&|include(\ )+)(.*$)/ =~ source)) do
+      text += source[0...i]
+      source = $'
+      spaces = $1.size
+      filename = $4 + ".jazz"
+      text += include_file(filename, spaces)
+    end
+    text += source
+  end
+
+  def TequilaPreprocessor.include_file(filename, offset)
+    lines = ''
+    prefix = ' ' * offset
+    f = open(filename, 'r')
+    while (s = f.gets) do
+      lines << prefix + s
+    end
+    f.close
+    lines
+  end
+
+  def TequilaPreprocessor.spaces(line)
+    (/^ +/ =~ line) ? [$&.size, $'] : [0, line]
+  end
+end
+

data/lib/tequila.treetop

@@ -0,0 +1,266 @@
+grammar Tequila
+
+  rule program
+    allow_space configuration:configuration_line* expression allow_space {
+      def eval(binding)
+        tree = Tequila::Tree.new
+        configuration.elements.each {|cl| cl.eval(tree)}
+        expression.eval(tree, tree.root, binding)
+      end
+    }
+  end
+
+  rule configuration_line
+    allow_space '#!' key:term allow_space value:term? {
+      def eval(tree)
+        if value.text_value.blank?
+          tree.config.send(key.text_value.intern)
+        else
+          tree.config.send(key.text_value.intern, value.text_value)
+        end
+      end
+    }
+  end
+
+  rule expression
+    source_keyword var_type:('@'/'@@'/'$')? object {
+      def eval(tree, parent, binding)
+        object.eval(tree, parent, binding, :variable, {:var_type => var_type.text_value})
+      end
+    }
+  end
+
+  rule source_keyword
+   '-' allow_space
+   / 'source' must_space
+  end
+
+  rule object
+    data_mark? object_name:term suppress_label:'~'? label:label_decl? atd:attributes_decl? mtd:methods_decl? std:statics_decl? cbd:code_decl* asd:association_decl* gld:gluing_decl* eob {
+
+      def name
+        object_name.text_value
+      end
+
+      def eval(tree, parent, binding, type, params ={})
+
+        node = Tequila::Node.new((:variable == type) ? params[:var_type] + name : name, type).eval(binding)
+
+        unless suppress_label.empty?
+          node.suppress_label = true
+        end
+
+        if label.elements
+          node.label = label.term.text_value
+        end
+
+        if atd.elements
+          atd.update_node(node)
+        end
+
+        if std.elements
+          std.update_node(node)
+        end
+
+        if mtd.elements
+          mtd.update_node(node)
+        end
+
+        if cbd.elements
+          cbd.elements.each {|cb| cb.update_node(node)}
+        end
+
+        tree.add_child_to(parent, node)
+
+        asd.elements.each {|e| e.eval(tree, node, binding) }
+        gld.elements.each {|e| e.eval(tree, node, binding) }
+
+        tree
+      end
+    }
+  end
+
+  rule association_decl
+    allow_space ('+' allow_space /'join' must_space) object {
+      def eval(tree, node, binding)
+        object.eval(tree, node, binding, :association)
+      end
+    }
+  end
+
+  rule gluing_decl
+    allow_space ('<' allow_space /'merge' must_space) object {
+      def eval(tree, node, binding)
+        object.eval(tree, node, binding, :bounded)
+      end
+    }
+  end
+
+  rule attributes_decl
+    allow_space ':'? (only_attributes_decl / except_attributes_decl) {
+      def update_node(node)
+        elements[2].update_node(node)
+      end
+    }
+  end
+
+  rule only_attributes_decl
+    (allow_space atd:pick_all_decl+
+    / ('only'/'pick') atd:only_attribute_decl+) {
+      def update_node(node)
+        if atd.elements
+          atd.elements.each {|x| x.update_node(node, :only)}
+        end
+      end
+    }
+  end
+
+  rule except_attributes_decl
+    (allow_space atd:drop_all_decl+
+    / ('except'/'drop') atd:except_attribute_decl+) {
+      def update_node(node)
+        if atd.elements
+          atd.elements.each {|x| x.update_node(node, :except)}
+        end
+      end
+    }
+  end
+
+  rule pick_all_decl
+   'pick' must_space 'all' {
+     def update_node(node, _)
+       node.all_attributes!
+     end
+   }
+  end
+
+  rule drop_all_decl
+   'drop' must_space 'all' {
+     def update_node(node, _)
+       node.no_attributes!
+     end
+   }
+  end
+
+
+  rule only_attribute_decl
+    allow_space '.' term label:label_decl? {
+      def update_node(node, key)
+        m = Tequila::Node::Attribute.new(term.text_value)
+        if label.elements
+          m.label = label.term.text_value
+        end
+        node.add_attribute(key, m)
+      end
+    }
+  end
+
+  rule except_attribute_decl
+    allow_space '.' term {
+      def update_node(node, key)
+        m = Tequila::Node::Attribute.new(term.text_value)
+        node.add_attribute(key, m)
+      end
+    }
+  end
+
+  rule attribute_decl
+    allow_space '.' term label:label_decl? {
+      def update_node(node, key)
+        m = Tequila::Node::Attribute.new(term.text_value)
+        if label.elements
+          m.label = label.term.text_value
+        end
+        node.add_attribute(key, m)
+      end
+    }
+  end
+
+  rule methods_decl
+    allow_space ':'? 'methods' mtd:(method_decl)+ {
+      def update_node(node)
+        mtd.elements.each {|x| x.update_node(node)}
+      end
+    }
+  end
+
+  rule method_decl
+    allow_space '.' term params:('(' allow_space first_param:(!(','/')') .)+ allow_space rest_params:(',' allow_space param:(!(','/')') .)+ allow_space)* ')')? label:label_decl? {
+      def update_node(node)
+        m = Tequila::Node::Method.new(term.text_value)
+
+        if params.elements
+          m.params = parameters
+        end
+
+        if label.elements
+          m.label = label.term.text_value
+        end
+        node.methods += [m]
+      end
+
+      def parameters
+        [params.first_param.text_value] + params.rest_params.elements.map{|p| p.param.text_value}
+      end
+
+    }
+  end
+
+  rule statics_decl
+    allow_space ':'? 'static' std:(static_decl)+ {
+      def update_node(node)
+        std.elements.each {|x| x.update_node(node)}
+      end
+    }
+  end
+
+  rule static_decl
+    allow_space label:term label_decl {
+      def update_node(node)
+        node.statics += [Tequila::Node::Static.new(label.text_value, label_decl.term.text_value)]
+      end
+    }
+  end
+
+  rule code_decl
+    allow_space ':'? 'code' label_decl code:(!eob . )* code_end {
+      def update_node(node)
+        node.code_blocks += [Tequila::Node::CodeBlock.new(label_decl.term.text_value, code.text_value)]
+      end
+    }
+  end
+
+  rule label_decl
+    allow_space ('=>'/'label') allow_space data_mark? term
+  end
+
+  rule code_end
+    eob
+  end
+
+  rule eob #end of block
+    allow_space 'end'
+  end
+
+  rule term
+    [a-zA-Z0-9_\?\!]+
+  end
+
+  rule must_space
+    white_space+
+  end
+
+  rule allow_space
+    white_space*
+  end
+
+  rule white_space
+    [ \n\r]
+  end
+
+  rule data_mark
+    "'"
+  end
+end
+
+