jsrb 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 364d2bd1fb5aa8359d2396ab0cba0063fc7679a41e7dfd476cce1cf431ff9c33
-  data.tar.gz: d4b4bc5e5ae5de748f87e431ddcd325386116cc3771a830d3eb688b0ff4a0e5c
+  metadata.gz: 648a40f61a953168044bacbdc32e18b5e634b10f7978e6856a0eb5704b7e5659
+  data.tar.gz: 6a65ed913dbfccc2dd6518d826e9ae430d66bf96774dc418a874180cb9252f0a
 SHA512:
-  metadata.gz: 8f1f633f7475c81868867379eee537c7bdd8ca84502a0849e86cc79dead234ef0a96147018b492b8da4e6fa5f60089809e56d9cb929ab055a705238540d74928
-  data.tar.gz: 8c61e38d356b3a64cf37cc4a6200756d234baaddc6c4df1b110c1510bc898bc0f537d866d79a15ded681ce543f1db196ae9963124b6668ac5e240540133c3790
+  metadata.gz: 077a2481fc02d3b1a50ef6d36a92402b8f170e30764c5db614a58dce4b073615d1bfb7cdd560c4868e3425319388e29cc6fd4517f8f3179b5b38463459713d8a
+  data.tar.gz: 02547dbba6d6554cfd37174de4cbba978bef8d0cbafeb43a2d24b698f5dcf7d0598d8050dbf86e71e0f59344f569428686d1f077988c8192f8d71ee2b79a0274

data/.rubocop.yml

@@ -8,7 +8,7 @@ Metrics/LineLength:
   Max: 130
 
 Metrics/MethodLength:
-  Max: 30
+  Max: 50
 
 Metrics/AbcSize:
   Max: 25
@@ -16,6 +16,11 @@ Metrics/AbcSize:
 Metrics/ClassLength:
   Max: 200
 
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - 'spec/**/*'
+
 Style/MissingRespondToMissing:
   Enabled: false
 
@@ -34,7 +39,3 @@ Style/LambdaCall:
 
 Style/MethodMissingSuper:
   Enabled: false
-
-Metrics/BlockLength:
-  Exclude:
-    - 'spec/**/*'

data/.yardopts

@@ -1,2 +1,5 @@
 --markup-provider=redcarpet
 --markup=markdown
+--no-private
+-
+README.md

data/README.md

@@ -6,28 +6,28 @@ Jsrb is a template engine to generate JavaScript code in simple Ruby DSL.
 
 # Getting Started
 
-Jsrb handler works in `.jsrb` view files. All ruby syntax is available and `jsrb` is provided in it. You can construct JavaScript code via `jsrb`.
+Jsrb handler works in `.jsrb` view files. All ruby syntax is available and `js` is provided in it. You can construct JavaScript code via `js`.
 
-```rb
-name = jsrb.var!(:name) { 'foo' }
-ary = jsrb.var! :ary
-obj = jsrb.var! :obj
-result = jsrb.var!
+```ruby
+name = js.var!(:name) { 'foo' }
+ary = js.var! :ary
+obj = js.var! :obj
+result = js.var!
 # var name = 'foo';
 # var ary;
 # var obj;
-# var _v1; <- auto generate variable name
+# var _v1; // auto generated
 
-ary.set!([1, 2, 3])
+js.set! ary, [1, 2, 3]
 # ary = [1, 2, 3];
 
-obj.set!(
+js.set! obj, {
   name: name,
   profile: {
     age: 20,
     sex: 'm'
   }
-)
+}
 # obj = {
 #   name: name,
 #   profile: {
@@ -36,22 +36,23 @@ obj.set!(
 #   }
 # };
 
-result.set! (obj.name + "(" + obj.profile.age + ")")
+js.set! result, (obj.name + "(" + obj.profile.age + ")")
 # _v1 = obj.name + "(" + obj.profile.age + ")";
 
-ary.set! ary.map { |x| x * 2 }
+js.set! ary, ary.map { |x| x * 2 }
 # ary = ary.map(function(x) {
 #  return x * 2;
 # });
 
-jsrb.if!(ary[1] === 4) {
-  result.set! 'four'
+js.if!(ary[1] === 4) {
+  js.set! result, 'four'
 }.elsif(ary[1] === 2) {
-  result.set! 'two'
+  js.set! result, 'two'
 }.else {
-  result.set! 'other'
+  js.set! result, 'other'
 }
-# // the actual output doesn't looks like this, but will be better code in regard to variable scope.
+# // The actual output will have certain immediate functions
+# // that preserve variable scope for each case.
 # if (ary[1] === 4) {
 #   _v1 = 'four'
 # } else if (ary[1] === 2) {
@@ -60,51 +61,58 @@ jsrb.if!(ary[1] === 4) {
 #   _v1 = 'other'
 # }
 
-result.set! jsrb.expr.Date.new!
+js.set! result, js.expr.Date.new
 # _v1 = new Date;
 
-jsrb.expr.console.log('hello').as_statement!
+js.set! js.expr.console.log('hello')
 # console.log('hello');
 ```
 
 # Usage
 
+In contrast to Ruby, statements and expressions are
+specifically distinguished as different elements in JavaScript.
+And the program is composed of a list of statements.
+This means that the jsrb file will have a series of statement pushing expression in it.
+
+To make clear whether a method is pushing statement or not, jsrb adopted the rule that the name of method pushing statement should be `#..!`.
+
 ## Statements
 
 ### Variable declaration
 
-`jsrb.var!` pushes a **VariableDeclaration** into current context.
+`js.var!` pushes a **VariableDeclaration** into current context.
 
-```rb
+```ruby
 # with variable name and initializer
-jsrb.var!('varname') { 100 }
+js.var!('varname') { 100 }
 # var varname = 100;
 
 # without initializer
-jsrb.var!('varname')
+js.var!('varname')
 # var varname;
 
 # variable name is auto-generated if not specified
-jsrb.var!
+js.var!
 # var _v1;
 
 # var! returns Jsrb::ExprChain instance, so that you can
 # assign value with `.set!` method.
-a = jsrb.var!
-a.set! 100
+a = js.var!
+js.set! a, 100
 # var _v1;
 # v1 = 100;
 ```
 
 ### If statement, and conditional expression
 
-`jsrb.if!` pushes an **IfStatement** into current context, `jsrb.if` to build **a conditional expression**.
+`js.if!` pushes an **IfStatement** into current context, `js.if` to build **a conditional expression**.
 
-```rb
+```ruby
 # start with `#if!`
 # and chain `#elsif` to add next case.
 # Note that this is a statement, not expression.
-jsrb.if!(v === 1) {
+js.if!(v === 1) {
   # ..
 }.elsif(v === 2) {
   # ..
@@ -113,105 +121,110 @@ jsrb.if!(v === 1) {
 }
 
 # if you don't need else clause, close with `#end`
-jsrb.if!(v === 1) {
+js.if!(v === 1) {
   # ..
 }.end
 
 # if you want to regard this as an expression, use `#if` without exclamation.
-v.set! jsrb.if(v === 1) {
+js.set! v, js.if(v === 1) {
   # ..
 }.else {
   # ..
 }
 ```
 
-### Assignment statement
-
-`ExprChain#set!` pushes an **assignment statement** (ExpressionStatement of AssignmentExpression).
-
-```rb
-a = jsrb.var! :a
-a.set! 100
-# var a;
-# a = 100;
-```
-
 ### Expression statement
 
-`ExprChain#as_statement!` pushes an **ExpressionStatement** of the left hand side of chain.
+`js.do!` pushes an **ExpressionStatement** of a given expression.
 
-```rb
-get_elements = jsrb.expr['getElements']
-get_elements.('.foo').forEach { |n| n.delete.() }.as_statement!
+```ruby
+get_elements = js.expr[:getElements]
+js.do! get_elements.('.foo').forEach { |n| n.delete.() }
 # getElements('.foo').forEach(function(n) { return n.delete(); });
 ```
 
-## Expression chain
+## Expressions
 
 Expression chain (`ExprChain` class) is an utility class to construct JavaScript expressions.
 
-### Initialize with wrapping a ruby value
+### Initialize with wrapping ruby values
 
-`jsrb.expr` create a new `ExprChain` instance, taking an initial value optionally.
-Some methods in jsrb automatically convert ruby expression to ExprChain.
+`js.expr` create a new `ExprChain` instance, taking an initial value optionally.
+Some methods in `js` automatically convert ruby value to ExprChain.
 
-```rb
-x = jsrb.var! :x
+```ruby
+x = js.var! :x
 
-x.set! jsrb.expr(100)
+js.set! x, js.expr(100)
 # x = 100;
-# set! automatically wrap with ExprChain.
-x.set! 100
+# set! automatically wraps argument with ExprChain.
+js.set! x, 100
 # x = 100;
-# If you need to compare by operator with another ExprChain,
-# you have to wrap first.
-x.set!(jsrb.expr(100) < jsrb.expr.y)
-# x.set!(100 < jsrb.expr.y) will fail.
+#
+# Note that if you need to compare a ruby value by operator with another one,
+# you have to wrap it.
+js.set! x, (js.expr(100) < js.expr.y) # (100 < js.expr.y) will fail.
 ```
 
+See the conversion section to check mappings from ruby value to JavaScript one.
+
 ### Chains
 
 #### Member expression
 
-`ExprChain#[], #member!, #..` constructs **MemberExpression**.
+`ExprChain#[], #..` constructs **MemberExpression**.
 `#[]` and `#member!` is safe. `#..` can be used only if the name has no conflict.
 
-```rb
-x = jsrb.var! :x
+```ruby
+x = js.var! :x
 
-obj = jsrb.expr['someObj']
-# jsrb.expr with no argument constructs empty chain,
+obj = js.expr[:someObj]
+# js.expr with no argument constructs empty chain,
 # in which every member chain will be an identifier.
-x.set! obj.field
-# x = someObj['field'];
-x.set! obj['field']
+js.set! x, obj.field
 # x = someObj['field'];
-x.set! obj.member! 'field'
+js.set! x, obj[:field]
 # x = someObj['field'];
 
-x.set! obj.send # NOTE that this is interpreted as a ruby Object's method, and causes an error.
+js.set! x, obj.send # NOTE that this is interpreted as a ruby Object's method, and causes an error.
+```
+
+#### Assignment
+
+`ExprChain#set` constructs an **AssignmentExpression**.
+
+```ruby
+a = js.var! :a
+# var a;
+
+js.do! a.set 100
+# a = 100;
+
+# js.set!(a, b) is short hand of js.do!(a.set(b))
+js.set! a, 100
+# a = 100;
 ```
 
 #### Function Call
 
 `ExprChain#call, so #.(), #.. with argument or block` constructs **CallExpression**.
 
-```rb
-x = jsrb.var! :x
-console = jsrb.expr['console']
+```ruby
+console = js.expr[:console]
 
 # using call method
-console.log.('foo').as_statement!
+js.do! console.log.('foo')
 # console.log('foo')
-console.log.call('foo').as_statement!
+js.do! console.log.call('foo')
 # console.log('foo')
 
 # using dynamic method
 # if #..() has at least one argument or block, it will be a call expression.
-console.log('foo').as_statement!
+js.do! console.log('foo')
 # console.log('foo')
-x.map { |item| item.field }.as_statement!
-# x.map(function(item) { return item.field; });
+
+js.do! js.expr(:ary).forEach { |item| item.execute.() }
+# ary.forEach(function(item) { return item.execute(); });
 ```
 
 #### Operators
@@ -219,44 +232,44 @@ x.map { |item| item.field }.as_statement!
 Any ruby-overridable and JS-existing operators are overridden for chaining.
 Supported operators are: `** + - * / % >> << & ^ | <= < > >= == === != ! && ||`.
 
-```rb
-x = jsrb.var! :x
-a = jsrb.expr['a']
+```ruby
+x = js.var! :x
+a = js.expr[:a]
 
-x.set!(a === 1)
+js.set! x, (a === 1)
 # x = a === 1;
 
-x.set!(a * a)
+js.set! x, (a * a)
 # x = a * a;
 
-x.set!(3 * a) # raises an error because Fixnum does not accept ExprChain as RHS.
+js.set! x, (3 * a) # raises an error because the method :* of Fixnum does not accept ExprChain as RHS.
 ```
 
 #### New
 
-`ExprChain#new!` constructs **NewExpression**.
+`ExprChain#new` constructs **NewExpression**.
 
-```rb
-x = jsrb.var! :x
+```ruby
+x = js.var! :x
 
-x.set! jsrb.expr['Date'].new!
+js.set! x, js.expr[:Date].new
 # x = new Date;
 ```
 
 #### Function expression
 
-`ExprChain#for_all!` constructs **FunctionExpression**. You can also construct it from Proc directly or passing a block.
+`ExprChain#forall` constructs **FunctionExpression**. You can also construct it directly from Proc or passing a block.
 
-```rb
-ary = jsrb.var! :ary, [1, 2, 3]
+```ruby
+ary = js.var! :ary, [1, 2, 3]
 
-ary.map((jsrb.expr['x'] * 2).for_all!('x')).as_statement!
+js.do! ary.map((js.expr[:x] * 2).forall('x'))
 # ary.map(function(x) { return x * 2; });
 
-ary.map { |x| x * 2 }.as_statement!
+js.do! ary.map { |x| x * 2 }
 # ary.map(function(x) { return x * 2; });
 
-ary.map(->(x) { x * 2 }).as_statement!
+js.do! ary.map(->(x) { x * 2 })
 # ary.map(function(x) { return x * 2; });
 ```
 
@@ -283,10 +296,10 @@ Every Ruby's generic value will be converted to Javascript value by following ru
 
 You can add custom chain methods in `ExprChain` via `Jsrb::ExprChain.#add_custom_chain`.
 
-```rb
+```ruby
 Jsrb::ExprChain.add_custom_chain('log_here', '__tap_log__')
 
-jsrb.expr['foo']['bar'].log_here.as_statement!
+js.do! js.expr[:foo][:bar].log_here
 # __tap_log__(foo['bar']);
 ```
 

data/jsrb.gemspec

@@ -4,7 +4,6 @@ lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'jsrb/version'
 
-# rubocop:disable Metrics/BlockLength
 Gem::Specification.new do |spec|
   spec.name          = 'jsrb'
   spec.version       = Jsrb::VERSION
@@ -42,4 +41,3 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
 end
-# rubocop:enable Metrics/BlockLength

data/lib/jsrb/base.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 module Jsrb
-  # Base is a centralized class for Jsrb template.
-  # `jsrb`, accessed from views (i.e. `*.js.jsrb` files), is an instance of Jsrb::Base.
+  # `Jsrb::Base` is a centralized class for Jsrb template.
+  # `js`, accessed from views (i.e. `*.jsrb` files), is an instance of Jsrb::Base.
   #
-  # Jsrb::Base provides some utilities to push statements,
-  # construct expressions and generate the final JavaScript code,
-  # with preserving a statement context to build the abstract syntax tree.
+  # `Jsrb::Base` provides the interface for pushing statements,
+  # constructing expressions and generating JavaScript outputs
+  # with handling an internal statement context properly.
   class Base
+    # @private
     def initialize
       @context = JSStatementContext.new
     end
@@ -24,29 +25,136 @@ module Jsrb
     end
 
     #
-    # Pushes a VariableDeclaration to the current context
-    # and returns an access to created identifier.
+    # **Pushes** an ExpressionStatement to the current context
     #
-    # @param optional [Symbol] name a name of identifier, autogenerated if not specified.
+    # @example
+    #   js.do!(js.expr[:x].set(100))
+    #   # =>
+    #   #   x = 100;
+    # @param [Jsrb::ExprChain] expr target expression.
+    # @return [nil]
+    def do!(expr)
+      ast = expr.object
+      raise ArgumentError, 'Expression is empty' unless ast
+
+      @context.push(
+        type: 'ExpressionStatement',
+        expression: ast
+      )
+    end
+
+    #
+    # **Pushes** an assignment statement `lhs = rhs;`.
+    # This is a short hand of `js.do! lhs_expr.set(rhs_expr)`
+    #
+    # @example
+    #   a = js.var! :a
+    #   js.set!(a, 'dog')
+    #   # =>
+    #   #   var a;
+    #   #   a = 'dog';
+    #
+    #   # directly pass a symbol of identifier name
+    #   js.set!(:x, 100)
+    #   # =>
+    #   #   x = 100;
+    # @param [Jsrb::ExprChain, String, Symbol] expr target expression.
+    # @return [nil]
+    def set!(lhs, rhs)
+      lhs_expr = lhs.is_a?(ExprChain) ? lhs : expr(lhs)
+      do! lhs_expr.set(rhs)
+    end
+
+    #
+    # **Pushes** a VariableDeclaration to the current context
+    # and returns an access to the created identifier.
+    # @example
+    #   name = js.var!(:name) { 'foo' }
+    #   # var name = 'foo';
+    #
+    #   ary = js.var! :ary
+    #   # var ary;
+    #
+    #   obj = js.var! :obj
+    #   # var obj;
+    #
+    #   result = js.var!
+    #   # var _v1; //<- auto generate variable name
+    # @param [Symbol] name a name of identifier, autogenerated if not given
     # @yield optional block for initializer
-    # @yieldreturn an initializer expression (optional)
-    # @return [Jsrb::ExprChain] the expression that represents constructed new identifier
+    # @yieldreturn an initializer expression
+    # @return [Jsrb::ExprChain] the expression which represents a newly created identifier
     def var!(id = nil)
       id ||= @context.gen_var_name!
-      if block_given?
-        raw_expr = yield
-        val = raw_expr.is_a?(ExprChain) ? raw_expr : expr(@context.ruby_to_js_ast(raw_expr))
-        val.as_variable_declaration!(id)
+      val_ast =
+        if block_given?
+          raw_expr = yield
+          raw_expr.is_a?(ExprChain) ? raw_expr.unwrap : @context.ruby_to_js_ast(raw_expr)
+        end
+      if val_ast
+        @context.push(
+          type: 'VariableDeclaration',
+          declarations: [{
+            type: 'VariableDeclarator',
+            id: {
+              type: 'Identifier',
+              name: id.to_s
+            },
+            init: val_ast
+          }],
+          kind: 'var'
+        )
       else
-        expr.as_variable_declaration!(id)
+        @context.push(
+          type: 'VariableDeclaration',
+          declarations: [{
+            type: 'VariableDeclarator',
+            id: {
+              type: 'Identifier',
+              name: id.to_s
+            }
+          }],
+          kind: 'var'
+        )
       end
-      expr.member!(id)
+      expr[id]
     end
 
     #
-    # Constructs a new conditional chain that **pushes an IfStatement** to the current context
-    # after the chain ended.
+    # **Starts** a new conditional chain that pushes an IfStatement
+    # to the current context at end.
+    #
+    # @example
+    #   js.if!(expr1) {
+    #     # ..
+    #   }.elsif(expr2) {
+    #     # ..
+    #   }.else {
+    #     # ..
+    #   }
+    #   # =>
+    #   #   // The actual output will have certain immediate functions
+    #   #   // that preserve variable scope for each case.
+    #   #   if (..expr1..) {
+    #   #     // ..
+    #   #   } else if (..expr2..) {
+    #   #     // ..
+    #   #   } else {
+    #   #     // ..
+    #   #   }
     #
+    #   # If you don't have else clause, close with `#end`.
+    #   js.if!(expr1) {
+    #     # ..
+    #   }.elsif(expr2) {
+    #     # ..
+    #   }.end
+    #   # =>
+    #   #   if (..expr1..) {
+    #   #     // ..
+    #   #   } else if (..expr2..) {
+    #   #     // ..
+    #   #   }
     # @param [Jsrb::ExprChain, convertible ruby values] cond_expr an expression for the test
     # @yield new context block for the consequent case
     # @return [Jsrb::CondChain] condition chainable instance
@@ -55,8 +163,31 @@ module Jsrb
     end
 
     #
-    # Constructs a new conditional chain that **returns a conditional expression** after the chain ended.
+    # **Constructs** a new conditional chain that
+    # represents a conditional expression at end.
     #
+    # @example
+    #   result = var!
+    #   js.do! result, js.if(expr1) {
+    #     result_expr1
+    #   }.elsif(expr2) {
+    #     result_expr2
+    #   }.else {
+    #     result_expr3
+    #   }
+    #   # =>
+    #   #   // The actual output will have certain immediate functions
+    #   #   // that preserve variable scope for each case.
+    #   #   var _v1;
+    #   #   _v1 = (function() {
+    #   #     if (..expr1..) {
+    #   #       return ..result_expr1..;
+    #   #     } else if (..expr2..) {
+    #   #       return ..result_expr2..;
+    #   #     } else {
+    #   #       return ..result_expr3..;
+    #   #     }
+    #   #   })()
     # @param [Jsrb::ExprChain, convertible ruby values] cond_expr an expression for the test
     # @yield new context block for the consequent case
     # @return [Jsrb::CondChain] condition chainable instance
@@ -65,9 +196,9 @@ module Jsrb
     end
 
     #
-    # Constructs a new expression chain with a given JavaScript AST node.
+    # **Constructs** a new expression chain with a given JavaScript AST node.
     #
-    # @param optional [convertible ruby values] object represents JavaScript expression AST node
+    # @param [convertible ruby values] object represents JavaScript expression AST node
     # @return [Jsrb::ExprChain] chainable instance
     def expr(object = nil)
       @context.new_expression(object)
@@ -75,22 +206,22 @@ module Jsrb
 
     class << self
       #
-      # Shows JavaScript generator class name, 'Jsrb::NotFastGenerator' by default.
+      # Shows JavaScript generator class name, `'Jsrb::NotFastGenerator'` by default.
       #
       # ### **Help wanted!**
       #
       # *Jsrb::NotFastGenerator uses ExecJS and escodegen to generate JavaScript.
-      # It could be more efficient and get better error messages if you
-      # rewrite in Ruby*.
+      # It could be more efficient and get better error messages if we
+      # implement it in Ruby*.
       #
+      # @return [String] class name of a code generator
       def code_generator
         @code_generator || 'Jsrb::NotFastGenerator'
       end
 
       attr_writer :code_generator
 
-      private
-
+      # @private
       def code_generator_class
         @code_generator_class ||= Object.const_get(code_generator)
       end