jsrb 0.2.1 → 0.3.0

data/lib/jsrb/cond_chain.rb

@@ -20,7 +20,6 @@ module Jsrb
     def end
       finalize(nil)
     end
-    alias end! end
 
     private
 
@@ -39,7 +38,7 @@ module Jsrb
       else
         @context.push(
           type: 'ExpressionStatement',
-          expression: if_value.unwrap!
+          expression: if_value.object
         )
       end
     end
@@ -47,20 +46,26 @@ module Jsrb
     def create_proc(block)
       lambda do
         final_alternate_stmt = block && @context.new_block do
-          @context.new_expression(
-            type: 'CallExpression',
-            callee: @context.ruby_to_js_ast(block),
-            arguments: []
-          ).as_return!
+          @context.push(
+            type: 'ReturnStatement',
+            argument: {
+              type: 'CallExpression',
+              callee: @context.ruby_to_js_ast(block),
+              arguments: []
+            }
+          )
         end
         if_stmt = @stack.reverse.reduce(final_alternate_stmt) do |alternate_stmt, cond_block|
           condition_expr, cond_block = cond_block
           consequent_stmt = @context.new_block do
-            @context.new_expression(
-              type: 'CallExpression',
-              callee: @context.ruby_to_js_ast(cond_block),
-              arguments: []
-            ).as_return!
+            @context.push(
+              type: 'ReturnStatement',
+              argument: {
+                type: 'CallExpression',
+                callee: @context.ruby_to_js_ast(cond_block),
+                arguments: []
+              }
+            )
           end
           stmt_ast = {
             type: 'IfStatement',

data/lib/jsrb/expr_chain.rb

@@ -2,209 +2,86 @@
 
 module Jsrb
   # ExprChain is a builder class that constructs JavaScript expressions
-  # in natural phrase by chain method.
+  # in natural phrase by chaining methods.
+  #
+  # Note that ExprChain does NOT add any statement to be rendered.
+  # If you want to add the expression as an **ExpressionStatement**,
+  # use `Jsrb::Base#do!`:
+  #
+  # ```ruby
+  # js.do!(obj.foo = 100) # pushes a statement `obj.foo = 100;`.
+  # # where `obj.foo = 100` is still a chainable ExprChain instance,
+  # # so that we have to explicitly push it as statement with `js.do!`.
+  # ```
   class ExprChain
     JS_LOGICAL_OPS = %w[&& ||].freeze
 
+    #
+    # Gets a current wrapped AST node.
+    # @private
+    # @return [Hash, nil] current abstract syntax tree
+    attr_reader :object
+
     # Returns a new instance.
+    # @private
     # @param [Jsrb::JSStatementContext] context statement context instance
-    # @param optional [Hash] object hash represents AST node
+    # @param [Hash, nil] object hash represents AST node
     def initialize(context, object = nil)
       @context = context
       @object = object
     end
 
-    # Responds arbitrary method name
     #
-    # ### `#...`, the last letter is neither `=` nor `?`, and no argument and no block
-    # constructs a **MemberExpression**
+    # Responds to arbitrary method names
     #
-    # ```rb
-    # obj = jsrb.expr['obj']
-    # obj.foo # represents `obj.foo`
-    # ```
+    # @example
+    #   obj = js.expr[:obj]
     #
-    # ### `#...`, the last letter is neither `=` nor `?`, at least one argument or block
-    # constructs a **CallExpression** of MemberExpression
+    #   # If the last character of the method name is neither `=` nor `?`,
+    #   # and no argument and no block given,
+    #   # it constructs a **MemberExpression**.
     #
-    # ```rb
-    # obj = jsrb.expr['obj']
-    # obj.foo(100) # represents `obj.foo(100)`
-    # obj.foo { |x| x + 1 } # represents `obj.foo(function (x) { return x; })`
-    # ```
+    #   obj.foo # => ExprChain `obj.foo`
     #
-    # ### `#...=`
-    # pushes **ExpressionStatement** of a member assignment expression
+    #   # If the last character of the method name is neither `=` nor `?`,
+    #   # at least one argument or block given,
+    #   # it constructs a **CallExpression** of MemberExpression.
     #
-    # ```rb
-    # obj = jsrb.expr['obj']
-    # obj.foo = 100 # pushes `obj.foo = 100;` in the current context
-    # ```
+    #   obj.foo(100) # => ExprChain `obj.foo(100)`
+    #   obj.foo { |x| x + 1 } # ExprChain `obj.foo(function (x) { return x; })`
     #
-    # ### `#...?`
-    # constructs **ConditionalExpression**
+    #   # If the last character of the method name is `=`,
+    #   # it constructs **AssignmentExpression** of a member assignment expression.
     #
-    # ```rb
-    # obj = jsrb.expr['obj']
-    # obj.foo?(100, 200) # represents `obj.foo ? 100 : 200`
-    # ```
+    #   (obj.foo = 100) # ExprChain `obj.foo = 100`
     #
+    #   # If the last character of the method name is `?`,
+    #   # it constructs **ConditionalExpression**.
+    #
+    #   obj.foo?(100, 200) # => ExprChain `obj.foo ? 100 : 200`
     def method_missing(name, *args, &block)
       if (matches = name.to_s.match(/\A(.+)\?\z/))
-        member!(matches[1]).cond?(*args)
+        self[matches[1]].cond?(*args)
       elsif (matches = name.to_s.match(/\A(.+)=\z/))
-        member!(matches[1]).set!(*args)
+        self[matches[1]].set(*args)
       elsif (function_name = self.class.custom_chains[name.to_sym])
-        bind_chain!(function_name, *args, &block)
+        _bind_chain!(function_name, *args, &block)
       elsif args.empty? && !block
-        member!(name.to_s)
+        self[name.to_s]
       else
-        member!(name.to_s).call(*args, &block)
+        self[name.to_s].call(*args, &block)
       end
     end
 
     #
     # Constructs a **MemberExpression**
     #
-    # ```rb
-    # x = jsrb.var! :x
-    # obj = jsrb.expr['someObj']
-    # x.set! obj['field']
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # x = someObj['field'];
-    # ```
-    #
+    # @example
+    #   obj = js.expr[:someObj]
+    #   obj[:field] # => ExprChain `someObj['field']`
     # @param [String, Symbol] value name of member
     # @return [Jsrb::ExprChain] a chain represents **MemberExpression**
     def [](value)
-      member!(value)
-    end
-
-    #
-    # Gets current wrapped AST node.
-    #
-    # @return [Hash, nil] current abstract syntax tree
-    def unwrap!
-      @object
-    end
-
-    #
-    # pushes the current expression as a **ExpressionStatement** into the context.
-    #
-    # ```rb
-    # jsrb.expr['console'].log('hello').as_statement!
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # console.log('hello');
-    # ```
-    #
-    # @return [nil]
-    def as_statement!
-      raise ArgumentError, "Can't chain as_statement! on empty context" unless @object
-
-      @context.push(
-        type: 'ExpressionStatement',
-        expression: @object
-      )
-      nil # chain ends
-    end
-
-    #
-    # pushes a **VariableDeclaration** whose initializer is the current expression into the context.
-    #
-    # ```rb
-    # name = jsrb.var!(:name) { 'foo' }
-    # ary = jsrb.var! :ary
-    # obj = jsrb.var! :obj
-    # result = jsrb.var!
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # var name = 'foo';
-    # var ary;
-    # var obj;
-    # var _v1; //<- auto generate variable name
-    # ```
-    #
-    # @param [String, Symbol] id variable name
-    # @return [nil]
-    def as_variable_declaration!(id)
-      if @object
-        @context.push(
-          type: 'VariableDeclaration',
-          declarations: [{
-            type: 'VariableDeclarator',
-            id: {
-              type: 'Identifier',
-              name: id.to_s
-            },
-            init: @object
-          }],
-          kind: 'var'
-        )
-      else
-        @context.push(
-          type: 'VariableDeclaration',
-          declarations: [{
-            type: 'VariableDeclarator',
-            id: {
-              type: 'Identifier',
-              name: id.to_s
-            }
-          }],
-          kind: 'var'
-        )
-      end
-    end
-
-    #
-    # pushes a **ReturnStatement** whose argument is the current expression into the context.
-    #
-    # ```rb
-    # jsrb.expr['getItems'].().as_return!
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # return getItems();
-    # ```
-    #
-    # @return [nil]
-    def as_return!
-      @context.push(
-        type: 'ReturnStatement',
-        argument: @object
-      )
-    end
-
-    #
-    # Constructs a **MemberExpression**
-    #
-    # ```rb
-    # x = jsrb.var! :x
-    # obj = jsrb.expr['someObj']
-    # x.set! obj.member! 'field'
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # x = someObj['field'];
-    # ```
-    #
-    # @param [String, Symbol] value name of member
-    # @return [Jsrb::ExprChain] a chain represents **MemberExpression**
-    def member!(value)
       if @object
         self.class.new @context, type: 'MemberExpression',
                                  computed: true,
@@ -217,26 +94,16 @@ module Jsrb
     end
 
     #
-    # Constructs a **AssignmentExpression** whose left is current expression.
-    #
-    # ```rb
-    # x = jsrb.var! :x
-    # y = jsrb.var! :y
-    # y.assign!(x.assign! 100).as_statement!
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # var x;
-    # var y;
-    # y = x = 100;
-    # ```
+    # Constructs a **AssignmentExpression** whose RHS is the current expression.
     #
+    # @example
+    #   x = js.expr[:x]
+    #   y = js.expr[:y]
+    #   y.set(x.set 100) # => ExprChain `x = y = 100`
     # @param [Jsrb::ExprChain, convertible ruby values] value RHS value of assignment
     # @return [Jsrb::ExprChain] a chain represents **AssignmentExpression**
-    def assign!(value)
-      raise ArgumentError, "Can't chain assign! on empty context" unless @object
+    def set(value)
+      raise ArgumentError, "Can't chain set on empty context" unless @object
 
       self.class.new @context, type: 'AssignmentExpression',
                                operator: '=',
@@ -244,46 +111,15 @@ module Jsrb
                                right: @context.ruby_to_js_ast(value)
     end
 
-    #
-    # Pushes an **ExpressionStatement** of the assignment expression.
-    #
-    # ```rb
-    # x = jsrb.var! :x
-    # x.set! 100
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # var x;
-    # x = 100;
-    # ```
-    #
-    # @param [Jsrb::ExprChain, convertible ruby values] value RHS value of assignment
-    # @return [nil]
-    def set!(value)
-      assign!(value).as_statement!
-    end
-
     #
     # Constructs a **CallExpression**.
     #
-    # ```rb
-    # x = jsrb.var! :x
-    # console = jsrb.expr['console']
-    # console.log.('foo').as_statement!
-    # console.log.call('bar').as_statement!
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # console.log('foo');
-    # console.log('bar');
-    # ```
-    #
+    # @example
+    #   console = js.expr[:console]
+    #   console.log.('foo') # => ExprChain `console.log('foo')`
+    #   console.log.call('bar') # => ExprChain `console.log('foo')`
     # @param [Jsrb::ExprChain, convertible ruby values] args arguments
-    # @yield optional block represents final argument
+    # @yield optional block as a final function argument
     # @return [Jsrb::ExprChain] a chain represents **CallExpression**
     def call(*args, &block)
       raise ArgumentError, "Can't chain call on empty context" unless @object
@@ -300,21 +136,13 @@ module Jsrb
     #
     # Constructs a **NewExpression**.
     #
-    # ```rb
-    # x = jsrb.var! :x
-    # x.set! jsrb.expr['Date'].new!
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # x = new Date;
-    # ```
-    #
+    # @example
+    #   js.expr[:Date].new # => ExprChain `new Date`
+    #   js.expr[:Date].new(2020, 1, 1) # => ExprChain `new Date(2020, 1, 1)`
     # @param [Jsrb::ExprChain, convertible ruby values] args arguments
     # @return [Jsrb::ExprChain] a chain represents **NewExpression**
-    def new!(*args)
-      raise ArgumentError, "Can't chain new! on empty context" unless @object
+    def new(*args)
+      raise ArgumentError, "Can't chain new on empty context" unless @object
 
       arguments = args.map do |arg|
         @context.ruby_to_js_ast(arg)
@@ -329,29 +157,21 @@ module Jsrb
     #
     # All ruby-overridable operators can also be used:
     # `** + - * / % >> << & ^ | <= < > >= == === != ! && ||`
-    #
-    # ```rb
-    # x = jsrb.var! :x
-    # x.set!(jsrb.expr['a'] < 100)
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # x = a < 100;
-    # ```
-    #
+    # @example
+    #   (js.expr[:n] < 100) # => ExprChain `n < 100`
+    #   !(js.expr[:b]) # => ExprChain `!b`
+    #   js.expr[:a].op('||', 'default') # => ExprChain `a || 'default'`
     # @param [String, Symbol] operator operator
-    # @param optional [Jsrb::ExprChain, convertible ruby values] args arguments contains RHS value
+    # @param [Jsrb::ExprChain, convertible ruby values] args RHS value for binary operators
     # @return [Jsrb::ExprChain] a chain represents **UnaryExpression**, **BinaryExpression** or **LogicalExpression**
-    def op!(operator, *args)
-      raise ArgumentError, "Can't chain op! on empty context" unless @object
+    def op(operator, *args)
+      raise ArgumentError, "Can't chain op on empty context" unless @object
 
       opstr = operator.to_s
       if args.size == 1
-        _binary_op!(opstr, *args)
+        _binary_op(opstr, *args)
       elsif args.empty?
-        _unary_op!(opstr)
+        _unary_op(opstr)
       else
         raise ArgumentError, "#{opstr} is not a valid operator"
       end
@@ -359,11 +179,11 @@ module Jsrb
 
     %i[** + - * / % >> << & ^ | <= < > >= == === != !].each do |operator|
       define_method(operator) do |*args|
-        op!(operator, *args)
+        op(operator, *args)
       end
     end
 
-    private def _binary_op!(opstr, arg)
+    private def _binary_op(opstr, arg)
       if JS_LOGICAL_OPS.include? opstr
         self.class.new @context, type: 'LogicalExpression',
                                  operator: opstr,
@@ -377,7 +197,7 @@ module Jsrb
       end
     end
 
-    private def _unary_op!(opstr)
+    private def _unary_op(opstr)
       self.class.new @context, type: 'UnaryExpression',
                                operator: opstr,
                                argument: @object,
@@ -387,17 +207,8 @@ module Jsrb
     #
     # Constructs a **ConditionalExpression** whose test expression is the current expression.
     #
-    # ```rb
-    # x = jsrb.var! :x
-    # x.set! (jsrb.expr['height'] < 300).cond?('lo', 'hi')
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # x = (height < 300) ? 'lo' : 'hi';
-    # ```
-    #
+    # @example
+    #   (js.expr[:height] < 300).cond?('lo', 'hi') # => ExprChain `(height < 300) ? 'lo' : 'hi'`
     # @param [Jsrb::ExprChain, convertible ruby values] consequent expression used in consequent
     # @param [Jsrb::ExprChain, convertible ruby values] alternate expression used in alternate
     # @return [Jsrb::ExprChain] a chain represents **ConditionalExpression**
@@ -413,21 +224,12 @@ module Jsrb
     #
     # Constructs a **FunctionExpression** whose returned body is the current context.
     #
-    # ```rb
-    # f = jsrb.var! :f
-    # f.set! (jsrb.expr['x'] * 2).for_all(:x)
-    # ```
-    #
-    # will be
-    #
-    # ```js
-    # f = function (x) { return x * 2; };
-    # ```
-    #
+    # @example
+    #   (js.expr[:x] * 2).forall(:x) # => ExprChain `function (x) { return x * 2; }`
     # @param [String, Symbol] args argument identifiers
     # @return [Jsrb::ExprChain] a chain represents **FunctionExpression**
-    def for_all!(*args)
-      raise ArgumentError, "Can't chain for_all! on empty context" unless @object
+    def forall(*args)
+      raise ArgumentError, "Can't chain forall on empty context" unless @object
 
       self.class.new @context, type: 'FunctionExpression',
                                id: nil,
@@ -448,8 +250,10 @@ module Jsrb
                                }
     end
 
-    def bind_chain!(function_name, *args, &block)
-      raise ArgumentError, "Can't bind_chain! on empty context" unless @object
+    # Internal method for custom chains.
+    # @private
+    def _bind_chain!(function_name, *args, &block)
+      raise ArgumentError, "Can't _bind_chain! on empty context" unless @object
 
       arg_asts = [@object]
       args.each do |arg|
@@ -457,7 +261,7 @@ module Jsrb
       end
       arg_asts << @context.ruby_to_js_ast(block) if block_given?
       self.class.new @context, type: 'CallExpression',
-                               callee: self.class.new(@context).member!(function_name).unwrap!,
+                               callee: self.class.new(@context)[function_name].object,
                                arguments: arg_asts
     end
 
@@ -465,18 +269,10 @@ module Jsrb
       #
       # Adds a new chain method.
       #
-      # ```rb
-      # Jsrb::ExprChain.add_custom_chain('log_here', '__tap_log__')
-      #
-      # jsrb.expr['foo']['bar'].log_here.as_statement!
-      # ```
-      #
-      # will be
-      #
-      # ```js
-      # __tap_log__(foo['bar']);
-      # ```
+      # @example
+      #   Jsrb::ExprChain.add_custom_chain('log_here', '__tap_log__')
       #
+      #   js.expr[:foo][:bar].log_here # => ExprChain `__tap_log__(foo['bar'])`
       # @param [Symbol] chain_method_name name of a chain method
       # @param [Symbol] function_name name of wrapper function
       def add_custom_chain(chain_method_name, function_name)
@@ -484,9 +280,8 @@ module Jsrb
         @_custom_chains[chain_method_name] = function_name
       end
 
-      #
       # Show custom chains.
-      #
+      # @private
       def custom_chains
         @_custom_chains || {}
       end