opal 0.7.0.beta3 → 0.7.0.rc1

data/lib/opal/builder.rb

@@ -6,18 +6,21 @@ module Opal
   class Builder
     include BuilderProcessors
 
+    class MissingRequire < LoadError
+    end
+
     def initialize(options = nil)
       (options || {}).each_pair do |k,v|
         public_send("#{k}=", v)
       end
 
+      @stubs             ||= []
+      @preload           ||= []
+      @processors        ||= DEFAULT_PROCESSORS
+      @path_reader       ||= PathReader.new
+      @prerequired       ||= []
       @compiler_options  ||= {}
       @default_processor ||= RubyProcessor
-      @processors  ||= DEFAULT_PROCESSORS
-      @stubs       ||= []
-      @preload     ||= []
-      @prerequired ||= []
-      @path_reader ||= PathReader.new
 
       @processed = []
     end
@@ -38,6 +41,8 @@ module Opal
       requires.map { |r| process_require(r, options) }
       processed << asset
       self
+    rescue MissingRequire => error
+      raise error, "A file required by #{filename.inspect} wasn't found.\n#{error.message}"
     end
 
     def build_require(path, options = {})
@@ -92,7 +97,7 @@ module Opal
 
     def read(path)
       path_reader.read(path) or
-        raise ArgumentError, "can't find file: #{path.inspect} in #{path_reader.paths.inspect}"
+        raise MissingRequire, "can't find file: #{path.inspect} in #{path_reader.paths.inspect}"
     end
 
     def process_require(filename, options)
@@ -112,12 +117,14 @@ module Opal
 
       path = path_reader.expand(filename).to_s unless stub?(filename)
       asset = processor_for(source, filename, path, options.merge(requirable: true))
-      process_requires(asset.requires+tree_requires(asset, path), options)
+      process_requires(filename, asset.requires+tree_requires(asset, path), options)
       processed << asset
     end
 
-    def process_requires(requires, options)
+    def process_requires(source_filename, requires, options)
       requires.map { |r| process_require(r, options) }
+    rescue MissingRequire => error
+      raise error, "A file required by #{filename.inspect} wasn't found.\n#{error.message}"
     end
 
     def already_processed

data/lib/opal/compiler.rb

@@ -4,10 +4,42 @@ require 'opal/fragment'
 require 'opal/nodes'
 
 module Opal
+  # Compile a string of ruby code into javascript.
+  #
+  # @example
+  #
+  #     Opal.compile "ruby_code"
+  #     # => "string of javascript code"
+  #
+  # @see Opal::Compiler.new for compiler options
+  #
+  # @param source [String] ruby source
+  # @param options [Hash] compiler options
+  # @return [String] javascript code
+  #
   def self.compile(source, options = {})
     Compiler.new(source, options).compile
   end
 
+  # {Opal::Compiler} is the main class used to compile ruby to javascript code.
+  # This class uses {Opal::Parser} to gather the sexp syntax tree for the ruby
+  # code, and then uses {Opal::Node} to step through the sexp to generate valid
+  # javascript.
+  #
+  # @example
+  #   Opal::Compiler.new("ruby code").compile
+  #   # => "javascript code"
+  #
+  # @example Accessing result
+  #   compiler = Opal::Compiler.new("ruby_code")
+  #   compiler.compile
+  #   compiler.result # => "javascript code"
+  #
+  # @example Source Maps
+  #   compiler = Opal::Compiler.new("")
+  #   compiler.compile
+  #   compiler.source_map # => #<SourceMap:>
+  #
   class Compiler
     # Generated code gets indented with two spaces on each scope
     INDENT = '  '
@@ -27,28 +59,53 @@ module Opal
       end
     end
 
-    # used for __FILE__ directives as well as finding relative require()
+    # @!method file
+    #
+    # The filename to use for compiling this code. Used for __FILE__ directives
+    # as well as finding relative require()
+    #
+    # @return [String]
     compiler_option :file, '(file)'
 
+    # @!method method_missing?
+    #
     # adds method stubs for all used methods in file
+    #
+    # @return [Boolean]
     compiler_option :method_missing, true, :as => :method_missing?
 
+    # @!method arity_check?
+    #
     # adds an arity check to every method definition
+    #
+    # @return [Boolean]
     compiler_option :arity_check, false, :as => :arity_check?
 
+    # @!method irb?
+    #
     # compile top level local vars with support for irb style vars
     compiler_option :irb, false, :as => :irb?
 
+    # @!method dynamic_require_severity
+    #
     # how to handle dynamic requires (:error, :warning, :ignore)
     compiler_option :dynamic_require_severity, :error, :valid_values => [:error, :warning, :ignore]
 
+    # @!method requirable?
+    #
     # Prepare the code for future requires
     compiler_option :requirable, false, :as => :requirable?
 
+    # @!method inline_operators?
+    #
     # are operators compiled inline
     compiler_option :inline_operators, false, :as => :inline_operators?
 
-    attr_reader :result, :fragments
+    # @return [String] The compiled ruby code
+    attr_reader :result
+
+    # @return [Array] all [Opal::Fragment] used to produce result
+    attr_reader :fragments
 
     # Current scope
     attr_accessor :scope
@@ -67,6 +124,8 @@ module Opal
     end
 
     # Compile some ruby code to a string.
+    #
+    # @return [String] javascript code
     def compile
       @parser = Parser.new
 
@@ -76,13 +135,25 @@ module Opal
       @fragments = process(@sexp).flatten
 
       @result = @fragments.map(&:code).join('')
+    rescue => error
+      message = "An error occurred while compiling: #{self.file}\n#{error.message}"
+      raise error.class, message
     end
 
+    # Returns a source map that can be used in the browser to map back to
+    # original ruby code.
+    #
+    # @param source_file [String] optional source_file to reference ruby source
+    # @return [Opal::SourceMap]
     def source_map(source_file = nil)
       Opal::SourceMap.new(@fragments, source_file || self.file)
     end
 
-    # Any helpers required by this file
+    # Any helpers required by this file. Used by {Opal::Nodes::Top} to reference
+    # runtime helpers that are needed. These are used to minify resulting
+    # javascript by keeping a reference to helpers used.
+    #
+    # @return [Set<Symbol>]
     def helpers
       @helpers ||= Set.new([:breaker, :slice])
     end
@@ -226,7 +297,7 @@ module Opal
     #
     # 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
+    # sexps can just be added into a `s(:return) sexp`, so that is the
     # default action if no special case is required.
     def returns(sexp)
       return returns s(:nil) unless sexp

data/lib/opal/erb.rb

@@ -2,11 +2,33 @@ require 'opal/compiler'
 
 module Opal
   module ERB
+    # Compile ERB code into javascript.
+    #
+    # [Opal::ERB] can be used to compile [ERB] templates into javascript code.
+    # This module uses the [Opal::Compiler] internally.
+    #
+    # Compiled templates, when run in a javascript environment, will appear
+    # under the `Template` namespace, and can be accessed as:
+    #
+    #     Template['template_name'] # => template instance
+    #
+    # @example
+    #
+    #     source = "<div><%= @content %></div>"
+    #
+    #     Opal::ERB.compile source, "my_template.erb"
+    #
+    # @param source [String] erb content
+    # @param file_name [String] filename for reference in template
+    # @return [String] javascript code
+    #
     def self.compile(source, file_name = '(erb)')
       Compiler.new(source, file_name).compile
     end
 
     class Compiler
+      BLOCK_EXPR = /\s+(do|\{)(\s*\|[^|]*\|)?\s*\Z/
+
       def initialize(source, file_name = '(erb)')
         @source, @file_name, @result = source, file_name, source
       end
@@ -31,8 +53,6 @@ module Opal
         result.gsub '"', '\\"'
       end
 
-      BLOCK_EXPR = /\s+(do|\{)(\s*\|[^|]*\|)?\s*\Z/
-
       def require_erb(result)
         'require "erb";'+result
       end

data/lib/opal/fragment.rb

@@ -4,16 +4,27 @@ module Opal
   # it was generated. Using this sexp, when writing fragments in order, a
   # mapping can be created of the original location => target location,
   # aka, source-maps!
+  #
+  # These are generated by nodes, so will not have to create directly.
   class Fragment
     # String of javascript this fragment holds
+    # @return [String]
     attr_reader :code
 
+    # Create fragment with javascript code and optional original [Opal::Sexp].
+    #
+    # @param code [String] javascript code
+    # @param sexp [Opal::Sexp] sexp used for creating fragment
     def initialize(code, sexp = nil)
       @code = code.to_s
       @sexp = sexp
     end
 
-    # In debug mode we may wish to include the original line as a comment
+    # In debug mode we may wish to include the original line and comment in
+    # a javascript comment.
+    #
+    # @deprecated
+    #
     def to_code
       if @sexp
         "/*:#{@sexp.line}:#{@sexp.column}*/#{@code}"
@@ -22,18 +33,19 @@ module Opal
       end
     end
 
-    # debug:
-    # alias code to_code
-
-    # inspect the contents of this fragment, f("fooo")
+    # Inspect the contents of this fragment, f("fooo")
     def inspect
       "f(#{@code.inspect})"
     end
 
+    # Original line this fragment was created from
+    # @return [Integer, nil]
     def line
       @sexp.line if @sexp
     end
 
+    # Original column this fragment was created from
+    # @return [Integer, nil]
     def column
       @sexp.column if @sexp
     end

data/lib/opal/nodes/def.rb

@@ -8,36 +8,47 @@ module Opal
 
       children :recvr, :mid, :args, :stmts
 
+      def opt_args
+        @opt_args ||= args[1..-1].select { |arg| arg.first == :optarg }
+      end
+
+      def rest_arg
+        @rest_arg ||= args[1..-1].find { |arg| arg.first == :restarg }
+      end
+
+      def keyword_args
+        @keyword_args ||= args[1..-1].select do |arg|
+          [:kwarg, :kwoptarg, :kwrestarg].include? arg.first
+        end
+      end
+
+      def block_arg
+        @block_arg ||= args[1..-1].find { |arg| arg.first == :blockarg }
+      end
+
+      def argc
+        return @argc if @argc
+
+        @argc = args.length - 1
+        @argc -= 1 if block_arg
+        @argc -= 1 if rest_arg
+        @argc -= keyword_args.size
+
+        @argc
+      end
+
       def compile
         jsid = mid_to_jsid mid.to_s
         params = nil
         scope_name = nil
 
-        # opt args if last arg is sexp
-        opt = args.pop if Sexp === args.last
-
-        argc = args.length - 1
-
         # block name (&block)
-        if args.last.to_s.start_with? '&'
-          block_name = variable(args.pop.to_s[1..-1]).to_sym
-          argc -= 1
-        end
-
-        # splat args *splat
-        if args.last.to_s.start_with? '*'
-          uses_splat = true
-          if args.last == :*
-            argc -= 1
-          else
-            splat = args[-1].to_s[1..-1].to_sym
-            args[-1] = splat
-            argc -= 1
-          end
+        if block_arg
+          block_name = variable(block_arg[1]).to_sym
         end
 
         if compiler.arity_check?
-          arity_code = arity_check(args, opt, uses_splat, block_name, mid)
+          arity_code = arity_check(args, opt_args, rest_arg, keyword_args, block_name, mid)
         end
 
         in_scope do
@@ -49,32 +60,21 @@ module Opal
             scope.add_arg block_name
           end
 
-          yielder = block_name || '$yield'
-          scope.block_name = yielder
+          scope.block_name = block_name || '$yield'
 
           params = process(args)
           stmt_code = stmt(compiler.returns(stmts))
 
           add_temp 'self = this'
 
-          line "#{variable(splat)} = $slice.call(arguments, #{argc});" if splat
-
-          opt[1..-1].each do |o|
-            next if o[2][2] == :undefined
-            line "if (#{variable(o[1])} == null) {"
-            line '  ', expr(o)
-            line "}"
-          end if opt
+          compile_rest_arg
+          compile_opt_args
+          compile_keyword_args
 
           # must do this after opt args incase opt arg uses yield
           scope_name = scope.identity
 
-          if scope.uses_block?
-            add_temp "$iter = #{scope_name}.$$p"
-            add_temp "#{yielder} = $iter || nil"
-
-            line "#{scope_name}.$$p = null;"
-          end
+          compile_block_arg
 
           unshift "\n#{current_indent}", scope.to_vars
           line stmt_code
@@ -99,14 +99,11 @@ module Opal
         if recvr
           unshift 'Opal.defs(', recv(recvr), ", '$#{mid}', "
           push ')'
-        elsif scope.class? and %w(Object BasicObject).include?(scope.name)
+        elsif uses_defn?(scope)
           wrap "Opal.defn(self, '$#{mid}', ", ')'
-        elsif scope.class_scope?
-          scope.methods << "$#{mid}"
+        elsif scope.class?
           unshift "#{scope.proto}#{jsid} = "
-        elsif scope.iter?
-          wrap "Opal.defn(self, '$#{mid}', ", ')'
-        elsif scope.type == :sclass
+        elsif scope.sclass?
           unshift "self.$$proto#{jsid} = "
         elsif scope.top?
           unshift "Opal.Object.$$proto#{jsid} = "
@@ -117,14 +114,126 @@ module Opal
         wrap '(', ", nil) && '#{mid}'" if expr?
       end
 
+      def compile_block_arg
+        if scope.uses_block?
+          scope_name  = scope.identity
+          yielder     = scope.block_name
+
+          add_temp "$iter = #{scope_name}.$$p"
+          add_temp "#{yielder} = $iter || nil"
+
+          line "#{scope_name}.$$p = null;"
+        end
+      end
+
+      def compile_rest_arg
+        if rest_arg and rest_arg[1]
+          splat = variable(rest_arg[1].to_sym)
+          line "#{splat} = $slice.call(arguments, #{argc});"
+        end
+      end
+
+      def compile_opt_args
+        opt_args.each do |arg|
+          next if arg[2][2] == :undefined
+          line "if (#{variable(arg[1])} == null) {"
+          line "  #{variable(arg[1])} = ", expr(arg[2])
+          line "}"
+        end
+      end
+
+      def compile_keyword_args
+        return if keyword_args.empty?
+        helper :hash2
+
+        if rest_arg
+          with_temp do |tmp|
+            rest_arg_name = variable(rest_arg[1].to_sym)
+            line "#{tmp} = #{rest_arg_name}[#{rest_arg_name}.length - 1];"
+            line "if (#{tmp} == null || !#{tmp}.$$is_hash) {"
+            line "  $kwargs = $hash2([], {});"
+            line "} else {"
+            line "  $kwargs = #{rest_arg_name}.pop();"
+            line "}"
+          end
+        elsif last_opt_arg = opt_args.last
+          opt_arg_name = variable(last_opt_arg[1])
+          line "if (#{opt_arg_name} == null) {"
+          line "  $kwargs = $hash2([], {});"
+          line "}"
+          line "else if (#{opt_arg_name}.$$is_hash) {"
+          line "  $kwargs = #{opt_arg_name};"
+          line "  #{opt_arg_name} = ", expr(last_opt_arg[2]), ";"
+          line "}"
+        else
+          line "if ($kwargs == null) {"
+          line "  $kwargs = $hash2([], {});"
+          line "}"
+        end
+
+        line "if (!$kwargs.$$is_hash) {"
+        line "  throw Opal.ArgumentError.$new('expecting keyword args');"
+        line "}"
+
+        keyword_args.each do |kwarg|
+          case kwarg.first
+          when :kwoptarg
+            arg_name = kwarg[1]
+            var_name = variable(arg_name.to_s)
+            line "if ((#{var_name} = $kwargs.smap['#{arg_name}']) == null) {"
+            line "  #{var_name} = ", expr(kwarg[2])
+            line "}"
+          when :kwarg
+            arg_name = kwarg[1]
+            var_name = variable(arg_name.to_s)
+            line "if ((#{var_name} = $kwargs.smap['#{arg_name}']) == null) {"
+            line "  throw new Error('expecting keyword arg: #{arg_name}')"
+            line "}"
+          when :kwrestarg
+            arg_name = kwarg[1]
+            var_name = variable(arg_name.to_s)
+
+            kwarg_names = keyword_args.select do |kw|
+              [:kwoptarg, :kwarg].include? kw.first
+            end.map { |kw| "#{kw[1].to_s.inspect}: true" }
+
+            used_args = "{#{kwarg_names.join ','}}"
+            line "#{var_name} = Opal.kwrestargs($kwargs, #{used_args});"
+          else
+            raise "unknown kwarg type #{kwarg.first}"
+          end
+        end
+      end
+
+      # Simple helper to check whether this method should be defined through
+      # `Opal.defn()` runtime helper.
+      #
+      # @param [Opal::Scope] scope
+      # @returns [Boolean]
+      #
+      def uses_defn?(scope)
+        if scope.iter? or scope.module?
+          true
+        elsif scope.class? and %w(Object BasicObject).include?(scope.name)
+          true
+        else
+          false
+        end
+      end
+
       # Returns code used in debug mode to check arity of method call
-      def arity_check(args, opt, splat, block_name, mid)
+      def arity_check(args, opt, splat, kwargs, block_name, mid)
         meth = mid.to_s.inspect
 
         arity = args.size - 1
-        arity -= (opt.size - 1) if opt
+        arity -= (opt.size)
+
         arity -= 1 if splat
-        arity = -arity - 1 if opt or splat
+
+        arity -= (kwargs.size)
+
+        arity -= 1 if block_name
+        arity = -arity - 1 if !opt.empty? or !kwargs.empty? or splat
 
         # $arity will point to our received arguments count
         aritycode = "var $arity = arguments.length;"
@@ -142,14 +251,26 @@ module Opal
       handle :args
 
       def compile
+        done_kwargs = false
         children.each_with_index do |child, idx|
-          next if child.to_s == '*'
-
-          child = child.to_sym
-          push ', ' unless idx == 0
-          child = variable(child)
-          scope.add_arg child.to_sym
-          push child.to_s
+          next if :blockarg == child.first
+          next if :restarg == child.first and child[1].nil?
+
+          case child.first
+          when :kwarg, :kwoptarg, :kwrestarg
+            unless done_kwargs
+              done_kwargs = true
+              push ', ' unless idx == 0
+              scope.add_arg '$kwargs'
+              push '$kwargs'
+            end
+          else
+            child = child[1].to_sym
+            push ', ' unless idx == 0
+            child = variable(child)
+            scope.add_arg child.to_sym
+            push child.to_s
+          end
         end
       end
     end