opal 0.3.26 → 0.3.27

data/lib/opal/parser.rb

@@ -3,12 +3,52 @@ require 'opal/grammar'
 require 'opal/scope'
 
 module Opal
-
+  # This class is used to generate the javascript code from the given
+  # ruby code. First, this class will use an instance of `Opal::Grammar`
+  # to lex and then build up a tree of sexp statements. Once done, the
+  # top level sexp is passed into `#top` which recursively generates
+  # javascript for each sexp inside, and the result is returned as a
+  # string.
+  #
+  #     p = Opal::Parser.new
+  #     p.parse "puts 42"
+  #     # => "(function() { ... })()"
+  #
+  # ## Sexps
+  #
+  # A sexp, in opal, is an array where the first value is a symbol
+  # identifying the type of sexp. A simple ruby string "hello" would
+  # be represented by the sexp:
+  #
+  #     s(:str, "hello")
+  #
+  # Once that sexp is encounterd by the parser, it is handled by
+  # `#process` which removes the sexp type from the array, and checks
+  # for a method "process_str", which is used to handle specific sexps.
+  # Once found, that method is called with the sexp and level as
+  # arguments, and the returned string is the javascript to be used in
+  # the resulting file.
+  #
+  # ## Levels
+  #
+  # A level inside the parser is just a symbol representing what type
+  # of destination the code to be generated is for. For example, the
+  # main two levels are `:stmt` and `:expr`. Most sexps generate the
+  # same code for every level, but an `if` statement for example
+  # will change when written as an expression. Javascript cannot have
+  # if statements as expressions, so that sexp would wrap its result
+  # inside an anonymous function so the if statement can compile as
+  # expected.
   class Parser
+    # Generated code gets indented with two spaces on each scope
     INDENT = '  '
 
+    # Expressions are handled at diffferent levels. Some sexps
+    # need to know the js expression they are generating into.
     LEVEL = [:stmt, :stmt_closure, :list, :expr, :recv]
 
+    # All compare method nodes - used to optimize performance of
+    # math comparisons
     COMPARE = %w[< > <= >=]
 
     # Reserved javascript keywords - we cannot create variables with the
@@ -20,16 +60,32 @@ module Opal
       const
     )
 
+    # Statements which should not have ';' added to them.
     STATEMENTS = [:xstr, :dxstr]
 
+    # The grammar (tree of sexps) representing this compiled code
+    # @return [Opal::Grammar]
     attr_reader :grammar
 
+    # Holds an array of paths which this file "requires".
+    # @return [Array<String>]
     attr_reader :requires
 
+    # This does the actual parsing. The ruby code given is first
+    # run through a `Grammar` instance which returns a sexp to
+    # process. This is then handled recursively, resulting in a
+    # string of javascript being returned.
+    #
+    #     p = Opal::Parser.new
+    #     p.parse "puts 'hey'"
+    #     # => "(function() { .... })()"
+    #
+    # @param [String] source the ruby code to parse
+    # @param [String] file the filename representing this code
+    # @return [String] string of javascript code
     def parse(source, file = '(file)')
       @grammar  = Grammar.new
       @requires = []
-      @comments = false
       @file     = file
       @line     = 1
       @indent   = ''
@@ -43,24 +99,54 @@ module Opal
       top @grammar.parse(source, file)
     end
 
-    def warn(msg)
-      puts "#{msg} :#{@file}:#{@line}"
-    end
-
+    # This is called when a parsing/processing error occurs. This
+    # method simply appends the filename and curent line number onto
+    # the message and raises it.
+    #
+    #     parser.error "bad variable name"
+    #     # => raise "bad variable name :foo.rb:26"
+    #
+    # @param [String] msg error message to raise
     def error(msg)
       raise "#{msg} :#{@file}:#{@line}"
     end
 
+    # Instances of `Scope` can use this to determine the current
+    # scope indent. The indent is used to keep generated code easily
+    # readable.
+    #
+    # @return [String]
     def parser_indent
       @indent
     end
 
+    # Create a new sexp using the given parts. Even though this just
+    # returns an array, it must be used incase the internal structure
+    # of sexps does change.
+    #
+    #     s(:str, "hello there")
+    #     # => [:str, "hello there"]
+    #
+    # @result [Array]
     def s(*parts)
       sexp = Sexp.new(parts)
       sexp.line = @line
       sexp
     end
 
+    # Converts a ruby method name into its javascript equivalent for
+    # a method/function call. All ruby method names get prefixed with
+    # a '$', and if the name is a valid javascript identifier, it will
+    # have a '.' prefix (for dot-calling), otherwise it will be
+    # wrapped in brackets to use reference notation calling.
+    #
+    #     mid_to_jsid('foo')      # => ".$foo"
+    #     mid_to_jsid('class')    # => ".$class"
+    #     mid_to_jsid('==')       # => "['$==']"
+    #     mid_to_jsid('name=')    # => "['$name=']"
+    #
+    # @param [String] mid ruby method id
+    # @return [String]
     def mid_to_jsid(mid)
       if /\=|\+|\-|\*|\/|\!|\?|\<|\>|\&|\||\^|\%|\~|\[/ =~ mid.to_s
         "['$#{mid}']"
@@ -69,11 +155,21 @@ module Opal
       end
     end
 
-    # guaranteed unique id per file..
+    # Used to generate a unique id name per file. These are used
+    # mainly to name method bodies for methods that use blocks.
+    #
+    # @return [String]
     def unique_temp
       "TMP_#{@unique += 1}"
     end
 
+    # Generate the code for the top level sexp, i.e. the root sexp
+    # for a file. This is used directly by `#parse`. It pushes a
+    # ":top" scope onto the stack and handles the passed in sexp.
+    # The result is a string of javascript representing the sexp.
+    #
+    # @param [Array] sexp the sexp to process
+    # @return [String]
     def top(sexp, options = {})
       code = nil
       vars = []
@@ -93,9 +189,29 @@ module Opal
         code = "#{INDENT}var #{vars.join ', '};\n" + INDENT + @scope.to_vars + "\n" + code
       end
 
-      "function() {\n#{ code }\n}"
+      "(function() {\n#{ code }\n})();"
     end
 
+    # Every time the parser enters a new scope, this is called with
+    # the scope type as an argument. Valid types are `:top` for the
+    # top level/file scope; `:class`, `:module` and `:sclass` for the
+    # obvious ruby classes/modules; `:def` and `:iter` for methods
+    # and blocks respectively.
+    #
+    # This method just pushes a new instance of `Opal::Scope` onto the
+    # stack, sets the new scope as the `@scope` variable, and yields
+    # the given block. Once the block returns, the old scope is put
+    # back on top of the stack.
+    #
+    #     in_scope(:class) do
+    #       # generate class body in here
+    #       body = "..."
+    #     end
+    #
+    #     # use body result..
+    #
+    # @param [Symbol] type the type of scope
+    # @return [nil]
     def in_scope(type)
       return unless block_given?
 
@@ -106,6 +222,15 @@ module Opal
       @scope = parent
     end
 
+    # To keep code blocks nicely indented, this will yield a block after
+    # adding an extra layer of indent, and then returning the resulting
+    # code after reverting the indent.
+    #
+    #   indented_code = indent do
+    #     "foo"
+    #   end
+    #
+    # @result [String]
     def indent(&block)
       indent = @indent
       @indent += INDENT
@@ -116,6 +241,17 @@ module Opal
       res
     end
 
+    # Temporary varibales will be needed from time to time in the
+    # generated code, and this method will assign (or reuse) on
+    # while the block is yielding, and queue it back up once it is
+    # finished. Variables are queued once finished with to save the
+    # numbers of variables needed at runtime.
+    #
+    #     with_temp do |tmp|
+    #       "tmp = 'value';"
+    #     end
+    #
+    # @return [String] generated code withing block
     def with_temp(&block)
       tmp = @scope.new_temp
       res = yield tmp
@@ -123,12 +259,6 @@ module Opal
       res
     end
 
-    # Should be overriden in custom parsers to handle a require
-    # statement.
-    def handle_require(arglist)
-      "/* require statement removed */"
-    end
-
     # Used when we enter a while statement. This pushes onto the current
     # scope's while stack so we know how to handle break, next etc.
     #
@@ -146,10 +276,28 @@ module Opal
       result
     end
 
+    # Returns true if the parser is curently handling a while sexp,
+    # false otherwise.
+    #
+    # @return [Boolean]
     def in_while?
       @scope.in_while?
     end
 
+    # Processes a given sexp. This will send a method to the receiver
+    # of the format "process_<sexp_name>". Any sexp handler should
+    # return a string of content.
+    #
+    # For example, calling `process` with `s(:lit, 42)` will call the
+    # method `#process_lit`. If a method with that name cannot be
+    # found, then an error is raised.
+    #
+    #     process(s(:lit, 42), :stmt)
+    #     # => "42"
+    #
+    # @param [Array] sexp the sexp to process
+    # @param [Symbol] level the level to process (see `LEVEL`)
+    # @return [String]
     def process(sexp, level)
       type = sexp.shift
       meth = "process_#{type}"
@@ -160,6 +308,27 @@ module Opal
       __send__ meth, sexp, level
     end
 
+    # The last sexps in method bodies, for example, need to be returned
+    # in the compiled javascript. Due to syntax differences between
+    # javascript any ruby, some sexps need to be handled specially. For
+    # example, `if` statemented cannot be returned in javascript, so
+    # instead the "truthy" and "falsy" parts of the if statement both
+    # need to be returned instead.
+    #
+    # Sexps that need to be returned are passed to this method, and the
+    # alterned/new sexps are returned and should be used instead. Most
+    # sexps can just be added into a s(:return) sexp, so that is the
+    # default action if no special case is required.
+    #
+    #     sexp = s(:str, "hey")
+    #     parser.returns(sexp)
+    #     # => s(:js_return, s(:str, "hey"))
+    #
+    # `s(:js_return)` is just a special sexp used to return the result
+    # of processing its arguments.
+    #
+    # @param [Array] sexp the sexp to alter
+    # @return [Array] altered sexp
     def returns(sexp)
       return returns s(:nil) unless sexp
 
@@ -206,10 +375,28 @@ module Opal
       end
     end
 
+    # Returns true if the given sexp is an expression. All expressions
+    # will get ';' appended to their result, except for the statement
+    # sexps. See `STATEMENTS` for a list of sexp names that are
+    # statements.
+    #
+    # @param [Array] sexp the sexp to check
+    # @return [Boolean]
     def expression?(sexp)
       !STATEMENTS.include?(sexp.first)
     end
 
+    # More than one expression in a row will be grouped by the grammar
+    # into a block sexp. A block sexp just holds any number of other 
+    # sexps.
+    #
+    #     s(:block, s(:str, "hey"), s(:lit, 42))
+    #
+    # A block can actually be empty. As opal requires real values to
+    # be returned (to appease javascript values), a nil sexp 
+    # s(:nil) will be generated if the block is empty.
+    #
+    # @return [String]
     def process_block(sexp, level)
       result = []
       sexp << s(:nil) if sexp.empty?
@@ -231,6 +418,27 @@ module Opal
       result.join(@scope.class_scope? ? "\n\n#@indent" : "\n#@indent")
     end
 
+    # When a block sexp gets generated, any inline yields (i.e. yield
+    # statements that are not direct members of the block) need to be
+    # generated as a top level member. This is because if a yield
+    # is returned by a break statement, then the method must return.
+    #
+    # As inline expressions in javascript cannot return, the block 
+    # must be rewritten.
+    #
+    # For example, a yield inside an array:
+    #
+    #     [1, 2, 3, yield(4)]
+    #
+    # Must be rewitten into:
+    #
+    #     tmp = yield 4
+    #     [1, 2, 3, tmp]
+    #
+    # This rewriting happens on sexps directly.
+    #
+    # @param [Sexp] stmt sexps to (maybe) rewrite
+    # @return [Sexp]
     def find_inline_yield(stmt)
       found = nil
       case stmt.first
@@ -415,12 +623,12 @@ module Opal
       args ||= s(:masgn, s(:array))
       args = args.first == :lasgn ? s(:array, args) : args[1]
 
-      if args.last[0] == :block_pass
+      if args.last.is_a?(Array) and args.last[0] == :block_pass
         block_arg = args.pop
         block_arg = block_arg[1][1].to_sym
       end
 
-      if args.last[0] == :splat
+      if args.last.is_a?(Array) and args.last[0] == :splat
         splat = args.last[1][1]
         args.pop
         len = args.length
@@ -509,7 +717,7 @@ module Opal
     # @param [Symbol] meth :attr_{reader,writer,accessor}
     # @param [Array<Sexp>] attrs array of s(:lit) or s(:str)
     # @return [String] precompiled attr methods
-    def attr_optimize(meth, attrs)
+    def handle_attr_optimize(meth, attrs)
       out = []
 
       attrs.each do |attr|
@@ -555,16 +763,12 @@ module Opal
 
       case meth
       when :attr_reader, :attr_writer, :attr_accessor
-        attrs = arglist[1..-1]
-        if @scope.class_scope? && attrs.all? { |a| [:lit, :str].include? a.first }
-          return attr_optimize meth, attrs
-        end
+        return handle_attr_optimize(meth, arglist[1..-1])
       when :block_given?
         return js_block_given(sexp, level)
       when :alias_native
         return handle_alias_native(sexp) if @scope.class_scope?
       when :require
-        # return handle_require(arglist)
         path = arglist[1]
 
         if path and path[0] == :str
@@ -699,7 +903,7 @@ module Opal
       spacer  = "\n#{@indent}#{INDENT}"
       cls     = "function #{name}() {};"
       boot    = "#{name} = __klass(__base, __super, #{name.inspect}, #{name});"
-      comment = "#{spacer}// line #{ sexp.line }, #{ @file }, class #{ name }" if @comment
+      comment = "#{spacer}// line #{ sexp.line }, #{ @file }, class #{ name }"
 
       "(function(__base, __super){#{comment}#{spacer}#{cls}#{spacer}#{boot}\n#{code}\n#{@indent}})(#{base}, #{sup})"
     end
@@ -753,7 +957,7 @@ module Opal
       spacer  = "\n#{@indent}#{INDENT}"
       cls     = "function #{name}() {};"
       boot    = "#{name} = __module(__base, #{name.inspect}, #{name});"
-      comment = "#{spacer}// line #{ sexp.line }, #{ @file }, module #{ name }" if @comment
+      comment = "#{spacer}// line #{ sexp.line }, #{ @file }, module #{ name }"
 
       "(function(__base){#{comment}#{spacer}#{cls}#{spacer}#{boot}\n#{code}\n#{@indent}})(#{base})"
     end
@@ -808,7 +1012,7 @@ module Opal
 
       # block name &block
       if args.last.to_s.start_with? '&'
-        block_name = args.pop[1..-1].to_sym
+        block_name = args.pop.to_s[1..-1].to_sym
       end
 
       # splat args *splat
@@ -874,7 +1078,6 @@ module Opal
       end
 
       comment += "\n#{@indent}"
-      comment = nil unless @comments
 
       if recvr
         if smethod

data/lib/opal/rake_task.rb

@@ -15,7 +15,7 @@ module Opal
       @dir          = @project_dir
       @build_dir    = 'build'
       @specs_dir    = 'spec'
-      @files        = Dir['lib/**/*.{rb,js,erb}']
+      @files        = Dir['lib/**/*.rb']
       @dependencies = []
 
       yield self if block_given?
@@ -67,9 +67,9 @@ module Opal
         @dependencies.each { |dep| build_gem dep }
       end
 
-      desc "Run tests through phantomjs"
+      desc "Run specs in spec/index.html"
       task 'opal:test' do
-        runner = File.join(Opal.core_dir, 'opal-spec', 'runner.js')
+        runner = File.join Opal.core_dir, 'test_runner', 'runner.js'
         sh "phantomjs #{runner} spec/index.html"
       end
 

data/lib/opal/version.rb

@@ -1,3 +1,3 @@
 module Opal
-  VERSION = '0.3.26'
+  VERSION = '0.3.27'
 end