Class: Opal::Compiler

Inherits:
Object
  • Object
show all
Defined in:
opal/lib/opal/compiler.rb

Overview

Compiler is the main class used to compile ruby to javascript code. This class uses Parser to gather the sexp syntax tree for the ruby code, and then uses Node to step through the sexp to generate valid javascript.

Examples:

Opal::Compiler.new("ruby code").compile
# => "javascript code"

Accessing result

compiler = Opal::Compiler.new("ruby_code")
compiler.compile
compiler.result # => "javascript code"

Source Maps

compiler = Opal::Compiler.new("")
compiler.compile
compiler.source_map # => #<SourceMap:>

Constant Summary

INDENT =

Generated code gets indented with two spaces on each scope

'  '
COMPARE =

All compare method nodes - used to optimize performance of math comparisons

%w[< > <= >=]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source, options = {}) ⇒ Compiler

Returns a new instance of Compiler



138
139
140
141
142
143
 
# File 'opal/lib/opal/compiler.rb', line 138

def initialize(source, options = {})
  @source = source
  @indent = ''
  @unique = 0
  @options = options
end

Instance Attribute Details

#case_stmt ⇒ Object (readonly)

Current case_stmt



133
134
135
 
# File 'opal/lib/opal/compiler.rb', line 133

def case_stmt
  @case_stmt
end

#eof_content ⇒ Object (readonly)

Any content in END special construct



136
137
138
 
# File 'opal/lib/opal/compiler.rb', line 136

def eof_content
  @eof_content
end

#fragments ⇒ Array (readonly)

Returns all [Opal::Fragment] used to produce result

Returns:

  • (Array) —

    all [Opal::Fragment] used to produce result



127
128
129
 
# File 'opal/lib/opal/compiler.rb', line 127

def fragments
  @fragments
end

#result ⇒ String (readonly)

Returns The compiled ruby code

Returns:

  • (String) —

    The compiled ruby code



124
125
126
 
# File 'opal/lib/opal/compiler.rb', line 124

def result
  @result
end

#scope ⇒ Object

Current scope



130
131
132
 
# File 'opal/lib/opal/compiler.rb', line 130

def scope
  @scope
end

Class Method Details

.compiler_option(name, default_value, options = {}) ⇒ Object

defines a compiler option, also creating method of form 'name?'



52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'opal/lib/opal/compiler.rb', line 52

def self.compiler_option(name, default_value, options = {})
  mid          = options[:as]
  valid_values = options[:valid_values]
  define_method(mid || name) do
    value = @options.fetch(name) { default_value }
    if valid_values and not(valid_values.include?(value))
      raise ArgumentError, "invalid value #{value.inspect} for option #{name.inspect} "+
                            "(valid values: #{valid_values.inspect})"
    end
    value
  end
end

Instance Method Details

#arity_check? ⇒ Boolean

adds an arity check to every method definition

Returns:

  • (Boolean) 


85
 
# File 'opal/lib/opal/compiler.rb', line 85

compiler_option :arity_check, false, :as => :arity_check?

#compile ⇒ String

Compile some ruby code to a string.

Returns:

  • (String) —

    javascript code



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'opal/lib/opal/compiler.rb', line 148

def compile
  @parser = Parser.new

  parsed = begin
    @parser.parse(@source, self.file)
  rescue => error
    raise SyntaxError, error.message, error.backtrace
  end

  @sexp = s(:top, parsed || s(:nil))
  @eof_content = @parser.lexer.eof_content

  @fragments = process(@sexp).flatten

  @result = @fragments.map(&:code).join('')
rescue Exception => error
  message = "An error occurred while compiling: #{self.file}\n#{error.message}"
  raise error.class, message, error.backtrace
end

#dynamic_require_severity ⇒ Object

how to handle dynamic requires (:error, :warning, :ignore)



109
 
# File 'opal/lib/opal/compiler.rb', line 109

compiler_option :dynamic_require_severity, :warning, :valid_values => [:error, :warning, :ignore]

#error(msg, line = nil) ⇒ Object

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.

Raises:

  • (SyntaxError) 


199
200
201
 
# File 'opal/lib/opal/compiler.rb', line 199

def error(msg, line = nil)
  raise SyntaxError, "#{msg} :#{file}:#{line}"
end

#file ⇒ String

The filename to use for compiling this code. Used for FILE directives as well as finding relative require()

Returns:

  • (String) 


71
 
# File 'opal/lib/opal/compiler.rb', line 71

compiler_option :file, '(file)'

#fragment(str, scope, sexp = nil) ⇒ Object 



224
225
226
 
# File 'opal/lib/opal/compiler.rb', line 224

def fragment(str, scope, sexp = nil)
  Fragment.new(str, scope, sexp)
end

#freezing? ⇒ Boolean

Deprecated.

stubs out #freeze and #frozen?

Returns:

  • (Boolean) 


93
 
# File 'opal/lib/opal/compiler.rb', line 93

compiler_option :freezing, true, :as => :freezing?

#handle_block_given_call(sexp) ⇒ Object 



434
435
436
437
438
439
440
441
442
443
 
# File 'opal/lib/opal/compiler.rb', line 434

def handle_block_given_call(sexp)
  @scope.uses_block!
  if @scope.block_name
    fragment("(#{@scope.block_name} !== nil)", scope, sexp)
  elsif scope = @scope.find_parent_def and scope.block_name
    fragment("(#{scope.block_name} !== nil)", scope, sexp)
  else
    fragment("false", scope, sexp)
  end
end

#handlers ⇒ Object 



338
339
340
 
# File 'opal/lib/opal/compiler.rb', line 338

def handlers
  @handlers ||= Opal::Nodes::Base.handlers
end

#has_break! ⇒ Object

Marks the current block has having detected a break, but only from inside a #has_break?(&block) block.



308
309
310
 
# File 'opal/lib/opal/compiler.rb', line 308

def has_break!
  @break_detected = true if @break_detected == false
end

#has_break? ⇒ Boolean

With a block will detect a break in the sexp processed from within the block (see BreakNode).

Without a block (but inside a #has_break?(&block) call) returns the current result.

Works in conjunction with #has_break!

Returns:

  • (Boolean) —

    whether a block has been detected



297
298
299
300
301
302
303
304
 
# File 'opal/lib/opal/compiler.rb', line 297

def has_break?
  return @break_detected unless block_given?
  @break_detected = false
  result = yield
  detected = @break_detected
  @break_detected = nil
  detected
end

#helper(name) ⇒ Object

Use the given helper



235
236
237
 
# File 'opal/lib/opal/compiler.rb', line 235

def helper(name)
  self.helpers << name
end

#helpers ⇒ Set<Symbol>

Any helpers required by this file. Used by Nodes::Top to reference runtime helpers that are needed. These are used to minify resulting javascript by keeping a reference to helpers used.

Returns:

  • (Set<Symbol>) 


182
183
184
 
# File 'opal/lib/opal/compiler.rb', line 182

def helpers
  @helpers ||= Set.new([:breaker, :slice])
end

#in_case ⇒ Object 



312
313
314
315
316
317
318
 
# File 'opal/lib/opal/compiler.rb', line 312

def in_case
  return unless block_given?
  old = @case_stmt
  @case_stmt = {}
  yield
  @case_stmt = old
end

#in_ensure ⇒ Object 



275
276
277
278
279
280
281
282
 
# File 'opal/lib/opal/compiler.rb', line 275

def in_ensure
  return unless block_given?
  @in_ensure = true
  result = yield
  @in_ensure = false

  result
end

#in_ensure? ⇒ Boolean

Returns:

  • (Boolean) 


284
285
286
 
# File 'opal/lib/opal/compiler.rb', line 284

def in_ensure?
  @in_ensure
end

#in_while ⇒ Object

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.



266
267
268
269
270
271
272
273
 
# File 'opal/lib/opal/compiler.rb', line 266

def in_while
  return unless block_given?
  @while_loop = @scope.push_while
  result = yield
  @scope.pop_while

  result
end

#in_while? ⇒ Boolean

Returns true if the parser is curently handling a while sexp, false otherwise.

Returns:

  • (Boolean) 


322
323
324
 
# File 'opal/lib/opal/compiler.rb', line 322

def in_while?
  @scope.in_while?
end

#indent(&block) ⇒ Object

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.



242
243
244
245
246
247
248
249
250
 
# File 'opal/lib/opal/compiler.rb', line 242

def indent(&block)
  indent = @indent
  @indent += INDENT
  @space = "\n#@indent"
  res = yield
  @indent = indent
  @space = "\n#@indent"
  res
end

#inline_operators? ⇒ Object

are operators compiled inline



119
 
# File 'opal/lib/opal/compiler.rb', line 119

compiler_option :inline_operators, true, :as => :inline_operators?

#irb? ⇒ Object

compile top level local vars with support for irb style vars



104
 
# File 'opal/lib/opal/compiler.rb', line 104

compiler_option :irb, false, :as => :irb?

#method_calls ⇒ Object

Method calls made in this file



192
193
194
 
# File 'opal/lib/opal/compiler.rb', line 192

def method_calls
  @method_calls ||= Set.new
end

#method_missing? ⇒ Boolean

adds method stubs for all used methods in file

Returns:

  • (Boolean) 


78
 
# File 'opal/lib/opal/compiler.rb', line 78

compiler_option :method_missing, true, :as => :method_missing?

#operator_helpers ⇒ Object

Operator helpers



187
188
189
 
# File 'opal/lib/opal/compiler.rb', line 187

def operator_helpers
  @operator_helpers ||= Set.new
end

#parser_indent ⇒ Object

Instances of Scope can use this to determine the current scope indent. The indent is used to keep generated code easily readable.



213
214
215
 
# File 'opal/lib/opal/compiler.rb', line 213

def parser_indent
  @indent
end

#process(sexp, level = :expr) ⇒ Object

Process the given sexp by creating a node instance, based on its type, and compiling it to fragments.



328
329
330
331
332
333
334
335
336
 
# File 'opal/lib/opal/compiler.rb', line 328

def process(sexp, level = :expr)
  return fragment('', scope) if sexp == nil

  if handler = handlers[sexp.type]
    return handler.new(sexp, level, self).compile_to_fragments
  else
    raise "Unsupported sexp: #{sexp.type}"
  end
end

#requirable? ⇒ Object

Prepare the code for future requires



114
 
# File 'opal/lib/opal/compiler.rb', line 114

compiler_option :requirable, false, :as => :requirable?

#required_trees ⇒ Object

An array of trees required in this file (typically by calling #require_tree)



349
350
351
 
# File 'opal/lib/opal/compiler.rb', line 349

def required_trees
  @required_trees ||= []
end

#requires ⇒ Object

An array of requires used in this file



343
344
345
 
# File 'opal/lib/opal/compiler.rb', line 343

def requires
  @requires ||= []
end

#returns(sexp) ⇒ Object

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.



364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
 
# File 'opal/lib/opal/compiler.rb', line 364

def returns(sexp)
  return returns s(:nil) unless sexp

  case sexp.type
  # Undefs go from 1 ruby undef a,b,c to multiple JS Opal.udef() calls, so need to treat them as individual statements
  # and put the return on the last one
  when :undef
    last = sexp.pop
    sexp << returns(last)
  when :break, :next, :redo
    sexp
  when :yield
    sexp[0] = :returnable_yield
    sexp
  when :scope
    sexp[1] = returns sexp[1]
    sexp
  when :block
    if sexp.length > 1
      sexp[-1] = returns sexp[-1]
    else
      sexp << returns(s(:nil))
    end
    sexp
  when :when
    sexp[2] = returns(sexp[2])
    sexp
  when :rescue
    sexp[1] = returns sexp[1]

    if sexp[2] and sexp[2][0] == :resbody
      if sexp[2][2]
        sexp[2][2] = returns sexp[2][2]
      else
        sexp[2][2] = returns s(:nil)
      end
    end
    sexp
  when :ensure
    sexp[1] = returns sexp[1]
    sexp
  when :begin
    sexp[1] = returns sexp[1]
    sexp
  when :rescue_mod
    sexp[1] = returns sexp[1]
    sexp[2] = returns sexp[2]
    sexp
  when :while
    # sexp[2] = returns(sexp[2])
    sexp
  when :return, :js_return
    sexp
  when :xstr
    sexp[1] = "return #{sexp[1]};" unless /return|;/ =~ sexp[1]
    sexp
  when :dxstr
    sexp[1] = "return #{sexp[1]}" unless /return|;|\n/ =~ sexp[1]
    sexp
  when :if
    sexp[2] = returns(sexp[2] || s(:nil))
    sexp[3] = returns(sexp[3] || s(:nil))
    sexp
  else
    return_sexp = s(:js_return, sexp)
    return_sexp.source = sexp.source
    return_sexp
  end
end

#s(*parts) ⇒ Object

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.



220
221
222
 
# File 'opal/lib/opal/compiler.rb', line 220

def s(*parts)
  Sexp.new(parts)
end

#source_map(source_file = nil) ⇒ Opal::SourceMap

Returns a source map that can be used in the browser to map back to original ruby code.

Parameters:

  • source_file (String) (defaults to: nil) —

    optional source_file to reference ruby source

Returns:



173
174
175
 
# File 'opal/lib/opal/compiler.rb', line 173

def source_map(source_file = nil)
  Opal::SourceMap.new(@fragments, source_file || self.file)
end

#tainting? ⇒ Object

Deprecated.

stubs out #taint, #untaint and #tainted?



99
 
# File 'opal/lib/opal/compiler.rb', line 99

compiler_option :tainting, true, :as => :tainting?

#unique_temp ⇒ Object

Used to generate a unique id name per file. These are used mainly to name method bodies for methods that use blocks.



230
231
232
 
# File 'opal/lib/opal/compiler.rb', line 230

def unique_temp
  "TMP_#{@unique += 1}"
end

#warning(msg, line = nil) ⇒ Object

This is called when a parsing/processing warning occurs. This method simply appends the filename and curent line number onto the message and issues a warning.



206
207
208
 
# File 'opal/lib/opal/compiler.rb', line 206

def warning(msg, line = nil)
  warn "WARNING: #{msg} -- #{file}:#{line}"
end

#with_temp(&block) ⇒ Object

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.



257
258
259
260
261
262
 
# File 'opal/lib/opal/compiler.rb', line 257

def with_temp(&block)
  tmp = @scope.new_temp
  res = yield tmp
  @scope.queue_temp tmp
  res
end