jsrb 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b2cff3db7ac17a89b029bc7782e8735b7f9959c4595804c39537af8d6232077
-  data.tar.gz: b7700dc452ea93b9ba17cbf381bb79acfd00747f6e653b309cf24174811598d3
+  metadata.gz: 364d2bd1fb5aa8359d2396ab0cba0063fc7679a41e7dfd476cce1cf431ff9c33
+  data.tar.gz: d4b4bc5e5ae5de748f87e431ddcd325386116cc3771a830d3eb688b0ff4a0e5c
 SHA512:
-  metadata.gz: 934089fa92db021a2d90e738286de40dbc094286a5f0f4ed281626bd6d666b66d25d643ac4f117289b616c3c4b8d173fac5dcb86d29a645df7cf415c8c4e4939
-  data.tar.gz: 9a1de7b3fd7a00e7facb9c633352e06a142ccb01680d819bba30d3f56c7be226682a00693098068ad85fee4a76ef83a3246377e2c85e5399553b6794adf6defb
+  metadata.gz: 8f1f633f7475c81868867379eee537c7bdd8ca84502a0849e86cc79dead234ef0a96147018b492b8da4e6fa5f60089809e56d9cb929ab055a705238540d74928
+  data.tar.gz: 8c61e38d356b3a64cf37cc4a6200756d234baaddc6c4df1b110c1510bc898bc0f537d866d79a15ded681ce543f1db196ae9963124b6668ac5e240540133c3790

data/.rubocop.yml

@@ -32,6 +32,9 @@ Style/LambdaCall:
   Exclude:
     - 'spec/**/*'
 
+Style/MethodMissingSuper:
+  Enabled: false
+
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/Gemfile

@@ -7,6 +7,8 @@ gemspec
 
 group :development, :test do
   gem 'pry-byebug'
+  gem 'redcarpet'
   gem 'rubocop', '~> 0.61.0'
   gem 'simplecov'
+  gem 'yard'
 end

data/README.md

@@ -6,7 +6,7 @@ Jsrb is a template engine to generate JavaScript code in simple Ruby DSL.
 
 # Getting Started
 
-Jsrb handler works in jsrb files, which contain `.js.jsrb` extension. 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 `jsrb` is provided in it. You can construct JavaScript code via `jsrb`.
 
 ```rb
 name = jsrb.var!(:name) { 'foo' }

data/jsrb.gemspec

@@ -25,6 +25,8 @@ Gem::Specification.new do |spec|
       'public gem pushes.'
   end
 
+  spec.metadata['yard.run'] = 'yri'
+
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end

data/lib/jsrb/base.rb

@@ -1,11 +1,21 @@
 # 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 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.
   class Base
     def initialize
       @context = JSStatementContext.new
     end
 
+    #
+    # Generates executable JavaScript code from current context.
+    #
+    # @return [String] generated executable JavaScript code
     def generate_code
       generator = self.class.code_generator_class.new
       generator.call type: 'Program',
@@ -13,6 +23,14 @@ module Jsrb
                      body: @context.stacks.first
     end
 
+    #
+    # Pushes a VariableDeclaration to the current context
+    # and returns an access to created identifier.
+    #
+    # @param optional [Symbol] name a name of identifier, autogenerated if not specified.
+    # @yield optional block for initializer
+    # @yieldreturn an initializer expression (optional)
+    # @return [Jsrb::ExprChain] the expression that represents constructed new identifier
     def var!(id = nil)
       id ||= @context.gen_var_name!
       if block_given?
@@ -25,28 +43,57 @@ module Jsrb
       expr.member!(id)
     end
 
+    #
+    # Constructs a new conditional chain that **pushes an IfStatement** to the current context
+    # after the chain ended.
+    #
+    # @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
     def if!(cond_expr, &block)
       CondChain.new(@context, false).elsif(cond_expr, &block)
     end
 
+    #
+    # Constructs a new conditional chain that **returns a conditional expression** after the chain ended.
+    #
+    # @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
     def if(cond_expr, &block)
       CondChain.new(@context, true).elsif(cond_expr, &block)
     end
 
+    #
+    # Constructs a new expression chain with a given JavaScript AST node.
+    #
+    # @param optional [convertible ruby values] object represents JavaScript expression AST node
+    # @return [Jsrb::ExprChain] chainable instance
     def expr(object = nil)
       @context.new_expression(object)
     end
 
     class << self
-      def code_generator_class
-        @code_generator_class ||= Object.const_get(code_generator)
-      end
-
+      #
+      # 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*.
+      #
       def code_generator
         @code_generator || 'Jsrb::NotFastGenerator'
       end
 
       attr_writer :code_generator
+
+      private
+
+      def code_generator_class
+        @code_generator_class ||= Object.const_get(code_generator)
+      end
     end
   end
 end

data/lib/jsrb/expr_chain.rb

@@ -1,15 +1,54 @@
 # frozen_string_literal: true
 
 module Jsrb
+  # ExprChain is a builder class that constructs JavaScript expressions
+  # in natural phrase by chain method.
   class ExprChain
     JS_LOGICAL_OPS = %w[&& ||].freeze
 
+    # Returns a new instance.
+    # @param [Jsrb::JSStatementContext] context statement context instance
+    # @param optional [Hash] object hash represents AST node
     def initialize(context, object = nil)
       @context = context
       @object = object
     end
 
-    # rubocop:disable Style/MethodMissingSuper
+    # Responds arbitrary method name
+    #
+    # ### `#...`, the last letter is neither `=` nor `?`, and no argument and no block
+    # constructs a **MemberExpression**
+    #
+    # ```rb
+    # obj = jsrb.expr['obj']
+    # obj.foo # represents `obj.foo`
+    # ```
+    #
+    # ### `#...`, the last letter is neither `=` nor `?`, at least one argument or block
+    # constructs a **CallExpression** of 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; })`
+    # ```
+    #
+    # ### `#...=`
+    # pushes **ExpressionStatement** of a member assignment expression
+    #
+    # ```rb
+    # obj = jsrb.expr['obj']
+    # obj.foo = 100 # pushes `obj.foo = 100;` in the current context
+    # ```
+    #
+    # ### `#...?`
+    # constructs **ConditionalExpression**
+    #
+    # ```rb
+    # obj = jsrb.expr['obj']
+    # obj.foo?(100, 200) # represents `obj.foo ? 100 : 200`
+    # ```
+    #
     def method_missing(name, *args, &block)
       if (matches = name.to_s.match(/\A(.+)\?\z/))
         member!(matches[1]).cond?(*args)
@@ -23,22 +62,50 @@ module Jsrb
         member!(name.to_s).call(*args, &block)
       end
     end
-    # rubocop:enable Style/MethodMissingSuper
 
+    #
+    # Constructs a **MemberExpression**
+    #
+    # ```rb
+    # x = jsrb.var! :x
+    # obj = jsrb.expr['someObj']
+    # x.set! obj['field']
+    # ```
+    #
+    # will be
+    #
+    # ```js
+    # x = someObj['field'];
+    # ```
+    #
+    # @param [String, Symbol] value name of member
+    # @return [Jsrb::ExprChain] a chain represents **MemberExpression**
     def [](value)
       member!(value)
     end
 
-    %i[** + - * / % >> << & ^ | <= < > >= == === != !].each do |operator|
-      define_method(operator) do |*args|
-        op!(operator, *args)
-      end
-    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
 
@@ -49,6 +116,27 @@ module Jsrb
       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(
@@ -78,6 +166,20 @@ module Jsrb
       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',
@@ -85,6 +187,23 @@ module Jsrb
       )
     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',
@@ -97,6 +216,25 @@ module Jsrb
       end
     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;
+    # ```
+    #
+    # @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
 
@@ -106,10 +244,47 @@ 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');
+    # ```
+    #
+    # @param [Jsrb::ExprChain, convertible ruby values] args arguments
+    # @yield optional block represents final argument
+    # @return [Jsrb::ExprChain] a chain represents **CallExpression**
     def call(*args, &block)
       raise ArgumentError, "Can't chain call on empty context" unless @object
 
@@ -122,6 +297,22 @@ module Jsrb
                                arguments: js_args
     end
 
+    #
+    # Constructs a **NewExpression**.
+    #
+    # ```rb
+    # x = jsrb.var! :x
+    # x.set! jsrb.expr['Date'].new!
+    # ```
+    #
+    # will be
+    #
+    # ```js
+    # x = new Date;
+    # ```
+    #
+    # @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
 
@@ -133,6 +324,26 @@ module Jsrb
                                arguments: arguments
     end
 
+    #
+    # Constructs a **UnaryExpression**, **BinaryExpression** or **LogicalExpression**.
+    #
+    # 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;
+    # ```
+    #
+    # @param [String, Symbol] operator operator
+    # @param optional [Jsrb::ExprChain, convertible ruby values] args arguments contains RHS value
+    # @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
 
@@ -146,6 +357,12 @@ module Jsrb
       end
     end
 
+    %i[** + - * / % >> << & ^ | <= < > >= == === != !].each do |operator|
+      define_method(operator) do |*args|
+        op!(operator, *args)
+      end
+    end
+
     private def _binary_op!(opstr, arg)
       if JS_LOGICAL_OPS.include? opstr
         self.class.new @context, type: 'LogicalExpression',
@@ -167,6 +384,23 @@ module Jsrb
                                prefix: true
     end
 
+    #
+    # 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';
+    # ```
+    #
+    # @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**
     def cond?(consequent, alternate)
       raise ArgumentError, "Can't chain cond? on empty context" unless @object
 
@@ -176,12 +410,33 @@ module Jsrb
                                alternate: @context.ruby_to_js_ast(alternate)
     end
 
+    #
+    # 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; };
+    # ```
+    #
+    # @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
 
       self.class.new @context, type: 'FunctionExpression',
                                id: nil,
-                               params: args.map { |arg| @context.ruby_to_js_ast(arg) },
+                               params: args.map { |arg|
+                                 {
+                                   type: 'Identifier',
+                                   name: arg.to_s
+                                 }
+                               },
                                body: {
                                  type: 'BlockStatement',
                                  body: [
@@ -207,11 +462,31 @@ module Jsrb
     end
 
     class << self
+      #
+      # 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']);
+      # ```
+      #
+      # @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)
         @_custom_chains ||= {}
         @_custom_chains[chain_method_name] = function_name
       end
 
+      #
+      # Show custom chains.
+      #
       def custom_chains
         @_custom_chains || {}
       end

data/lib/jsrb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jsrb
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsrb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Shun MIZUKAMI
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-10 00:00:00.000000000 Z
+date: 2019-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: execjs
@@ -120,6 +120,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -139,6 +140,7 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
+  yard.run: yri
 post_install_message: 
 rdoc_options: []
 require_paths: