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 collapse

INDENT =

Generated code gets indented with two spaces on each scope

'  '
COMPARE =

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

%w[< > <= >=].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of Compiler.



220
221
222
223
224
225
226
227
228
229
 
# File 'opal/lib/opal/compiler.rb', line 220

def initialize(source, options = {})
  @source = source
  @indent = ''
  @unique = 0
  @options = options
  @comments = Hash.new([])
  @case_stmt = nil
  @option_values = {}
  @magic_comments = {}
end

Instance Attribute Details

#case_stmt ⇒ Object (readonly)

Current case_stmt



209
210
211
 
# File 'opal/lib/opal/compiler.rb', line 209

def case_stmt
  @case_stmt
end

#comments ⇒ Object (readonly)

Comments from the source code



215
216
217
 
# File 'opal/lib/opal/compiler.rb', line 215

def comments
  @comments
end

#eof_content ⇒ Object (readonly)

Any content in END special construct



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

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



203
204
205
 
# File 'opal/lib/opal/compiler.rb', line 203

def fragments
  @fragments
end

#magic_comments ⇒ Object (readonly)

Magic comment flags extracted from the leading comments



218
219
220
 
# File 'opal/lib/opal/compiler.rb', line 218

def magic_comments
  @magic_comments
end

#result ⇒ String (readonly)

Returns The compiled ruby code.

Returns:

  • (String) —

    The compiled ruby code



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

def result
  @result
end

#scope ⇒ Object

Current scope



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

def scope
  @scope
end

Class Method Details

.compiler_option(name, config = {}) ⇒ Object

Defines a compiler option.

Parameters:

  • as: (Hash) —

    a customizable set of options

  • default: (Hash) —

    a customizable set of options

  • magic_comment: (Hash) —

    a customizable set of options



65
66
67
68
 
# File 'opal/lib/opal/compiler.rb', line 65

def self.compiler_option(name, config = {})
  method_name = config.fetch(:as, name)
  define_method(method_name) { option_value(name, config) }
end

.module_name(path) ⇒ Object 



56
57
58
59
 
# File 'opal/lib/opal/compiler.rb', line 56

def self.module_name(path)
  path = File.join(File.dirname(path), File.basename(path).split('.').first)
  Pathname(path).cleanpath.to_s
end

Instance Method Details

#arity_check? ⇒ Boolean

adds an arity check to every method definition

Returns:

  • (Boolean) 


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

compiler_option :arity_check, default: false, as: :arity_check?

#async_await ⇒ Object

Enable async/await support and optionally enable auto-await.

Use either true, false, an Array of Symbols, a String containing names to auto-await separated by a comma or a Regexp.

Auto-await awaits provided methods by default as if .await was added to them automatically.

By default, the support is disabled (set to false).

If the config value is not set to false, any calls to #await will be translated to ES8 await keyword which makes the scope return a Promise and a containing scope will be async (instead of a value, it will return a Promise).

If the config value is an array, or a String separated by a comma, auto-await is also enabled.

A member of this collection can contain a wildcard character * in which case all methods containing a given substring will be awaited.

It can be used as a magic comment, examples:

# await: true
# await: *await*
# await: *await*, sleep, gets



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

compiler_option :await, default: false, as: :async_await, magic_comment: true

#async_await_before_typecasting ⇒ Object

Enable async/await support and optionally enable auto-await.

Use either true, false, an Array of Symbols, a String containing names to auto-await separated by a comma or a Regexp.

Auto-await awaits provided methods by default as if .await was added to them automatically.

By default, the support is disabled (set to false).

If the config value is not set to false, any calls to #await will be translated to ES8 await keyword which makes the scope return a Promise and a containing scope will be async (instead of a value, it will return a Promise).

If the config value is an array, or a String separated by a comma, auto-await is also enabled.

A member of this collection can contain a wildcard character * in which case all methods containing a given substring will be awaited.

It can be used as a magic comment, examples:

# await: true
# await: *await*
# await: *await*, sleep, gets



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

compiler_option :await, default: false, as: :async_await, magic_comment: true

#async_await_set_to_regexp(set) ⇒ Object 



317
318
319
320
321
 
# File 'opal/lib/opal/compiler.rb', line 317

def async_await_set_to_regexp(set)
  set = set.map { |name| Regexp.escape(name.to_s).gsub('\*', '.*?') }
  set = set.join('|')
  /^(#{set})$/
end

#autoloads ⇒ Object

An array of things (requires, trees) which don't need to success in loading compile-time.



482
483
484
 
# File 'opal/lib/opal/compiler.rb', line 482

def autoloads
  @autoloads ||= []
end

#compile ⇒ String

Compile some ruby code to a string.

Returns:

  • (String) —

    javascript code



234
235
236
237
238
239
240
241
 
# File 'opal/lib/opal/compiler.rb', line 234

def compile
  parse

  @fragments = re_raise_with_location { process(@sexp).flatten }
  @fragments << fragment("\n", nil, s(:newline)) unless @fragments.last.code.end_with?("\n")

  @result = @fragments.map(&:code).join('')
end

#dynamic_require_severity ⇒ Object

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



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

compiler_option :dynamic_require_severity, default: :ignore, valid_values: %i[error warning ignore]

#enable_source_location? ⇒ Object

Adds source_location for every method definition



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

compiler_option :enable_source_location, default: false, as: :enable_source_location?

#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.



326
327
328
329
330
 
# File 'opal/lib/opal/compiler.rb', line 326

def error(msg, line = nil)
  error = ::Opal::SyntaxError.new(msg)
  error.location = Opal::OpalBacktraceLocation.new(file, line)
  raise error
end

#esm? ⇒ Object

Wrap compiler result as self contained ES6 module



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

compiler_option :esm, default: false, as: :esm?

#file ⇒ String

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

Returns:

  • (String) 


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

compiler_option :file, default: '(file)'

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



365
366
367
 
# File 'opal/lib/opal/compiler.rb', line 365

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

#freezing? ⇒ Boolean

Deprecated.

stubs out #freeze and #frozen?

Returns:

  • (Boolean) 


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

compiler_option :freezing, default: true, as: :freezing?

#handle_block_given_call(sexp) ⇒ Object 



567
568
569
570
571
572
573
574
575
576
 
# File 'opal/lib/opal/compiler.rb', line 567

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) && scope.block_name
    fragment("(#{scope.block_name} !== nil)", scope, sexp)
  else
    fragment('false', scope, sexp)
  end
end

#handlers ⇒ Object 



465
466
467
 
# File 'opal/lib/opal/compiler.rb', line 465

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

#helper(name) ⇒ Object

Use the given helper



400
401
402
 
# File 'opal/lib/opal/compiler.rb', line 400

def helper(name)
  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>) 


281
282
283
284
285
 
# File 'opal/lib/opal/compiler.rb', line 281

def helpers
  @helpers ||= Set.new(
    magic_comments[:helpers].to_s.split(',').map { |h| h.strip.to_sym }
  )
end

#in_case ⇒ Object 



439
440
441
442
443
444
445
 
# File 'opal/lib/opal/compiler.rb', line 439

def in_case
  return unless block_given?
  old = @case_stmt
  @case_stmt = {}
  yield
  @case_stmt = old
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.



431
432
433
434
435
436
437
 
# File 'opal/lib/opal/compiler.rb', line 431

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) 


449
450
451
 
# File 'opal/lib/opal/compiler.rb', line 449

def in_while?
  @scope.in_while?
end

#indent ⇒ 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.



407
408
409
410
411
412
413
414
415
 
# File 'opal/lib/opal/compiler.rb', line 407

def indent
  indent = @indent
  @indent += INDENT
  @space = "\n#{@indent}"
  res = yield
  @indent = indent
  @space = "\n#{@indent}"
  res
end

#inline_operators? ⇒ Object

are operators compiled inline



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

compiler_option :inline_operators, default: true, as: :inline_operators?

#irb? ⇒ Object

compile top level local vars with support for irb style vars



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

compiler_option :irb, default: false, as: :irb?

#marshal_dump ⇒ Object

Marshalling for cache shortpath



579
580
581
582
583
 
# File 'opal/lib/opal/compiler.rb', line 579

def marshal_dump
  [@options, @option_values, @source_map ||= source_map.cache,
   @magic_comments, @result,
   @required_trees, @requires, @autoloads]
end

#marshal_load(src) ⇒ Object 



585
586
587
588
589
 
# File 'opal/lib/opal/compiler.rb', line 585

def marshal_load(src)
  @options, @option_values, @source_map,
  @magic_comments, @result,
  @required_trees, @requires, @autoloads = src
end

#method_calls ⇒ Object

Method calls made in this file



293
294
295
 
# File 'opal/lib/opal/compiler.rb', line 293

def method_calls
  @method_calls ||= Set.new
end

#method_missing? ⇒ Boolean

adds method stubs for all used methods in file

Returns:

  • (Boolean) 


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

compiler_option :method_missing, default: true, as: :method_missing?

#operator_helpers ⇒ Object

Operator helpers



288
289
290
 
# File 'opal/lib/opal/compiler.rb', line 288

def operator_helpers
  @operator_helpers ||= Set.new
end

#option_value(name, config) ⇒ Object

Fetches and memoizes the value for an option.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'opal/lib/opal/compiler.rb', line 71

def option_value(name, config)
  return @option_values[name] if @option_values.key? name

  default_value = config[:default]
  valid_values  = config[:valid_values]
  magic_comment = config[:magic_comment]

  value = @options.fetch(name, default_value)

  if magic_comment && @magic_comments.key?(name)
    value = @magic_comments.fetch(name)
  end

  if valid_values && !valid_values.include?(value)
    raise(
      ArgumentError,
      "invalid value #{value.inspect} for option #{name.inspect} " \
      "(valid values: #{valid_values.inspect})"
    )
  end

  @option_values[name] = value
end

#parse ⇒ Object 



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'opal/lib/opal/compiler.rb', line 243

def parse
  @buffer = ::Opal::Parser::SourceBuffer.new(file, 1)
  @buffer.source = @source

  @parser = Opal::Parser.default_parser

  sexp, comments, tokens = re_raise_with_location { @parser.tokenize(@buffer) }

  kind = case
         when requirable?
           :require
         when eval?
           :eval
         else
           :main
         end

  @sexp = s(:top, sexp || s(:nil)).tap { |i| i.meta[:kind] = kind }
  @comments = ::Parser::Source::Comment.associate_locations(sexp, comments)
  @magic_comments = MagicComments.parse(sexp, comments)
  @eof_content = EofContent.new(tokens, @source).eof
end

#parse_comments? ⇒ Object

Adds comments for every method definition



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

compiler_option :parse_comments, default: false, as: :parse_comments?

#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.



354
355
356
 
# File 'opal/lib/opal/compiler.rb', line 354

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.



455
456
457
458
459
460
461
462
463
 
# File 'opal/lib/opal/compiler.rb', line 455

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
    error "Unsupported sexp: #{sexp.type}"
  end
end

#re_raise_with_location ⇒ Object 



332
333
334
335
336
337
338
339
340
341
342
 
# File 'opal/lib/opal/compiler.rb', line 332

def re_raise_with_location
  yield
rescue StandardError, ::Opal::SyntaxError => error
  opal_location = ::Opal.opal_location_from_error(error)
  opal_location.path = file
  opal_location.label ||= @source.lines[opal_location.line.to_i - 1].strip
  new_error = ::Opal::SyntaxError.new(error.message)
  new_error.set_backtrace error.backtrace
  ::Opal.add_opal_location_to_error(opal_location, new_error)
  raise new_error
end

#requirable? ⇒ Object

Prepare the code for future requires



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

compiler_option :requirable, default: false, as: :requirable?

#required_trees ⇒ Object

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



476
477
478
 
# File 'opal/lib/opal/compiler.rb', line 476

def required_trees
  @required_trees ||= []
end

#requires ⇒ Object

An array of requires used in this file



470
471
472
 
# File 'opal/lib/opal/compiler.rb', line 470

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.



497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
 
# File 'opal/lib/opal/compiler.rb', line 497

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

  case sexp.type
  when :undef
    # undef :method_name always returns nil
    returns sexp.updated(:begin, [sexp, s(:nil)])
  when :break, :next, :redo, :retry
    sexp
  when :yield
    sexp.updated(:returnable_yield, nil)
  when :when
    *when_sexp, then_sexp = *sexp
    sexp.updated(nil, [*when_sexp, returns(then_sexp)])
  when :rescue
    body_sexp, *resbodies, else_sexp = *sexp

    resbodies = resbodies.map do |resbody|
      returns(resbody)
    end

    if else_sexp
      else_sexp = returns(else_sexp)
    end

    sexp.updated(
      nil, [
        returns(body_sexp),
        *resbodies,
        else_sexp
      ]
    )
  when :resbody
    klass, lvar, body = *sexp
    sexp.updated(nil, [klass, lvar, returns(body)])
  when :ensure
    rescue_sexp, ensure_body = *sexp
    sexp = sexp.updated(nil, [returns(rescue_sexp), ensure_body])
    sexp.updated(:js_return, [sexp])
  when :begin, :kwbegin
    # Wrapping last expression with s(:js_return, ...)
    *rest, last = *sexp
    sexp.updated(nil, [*rest, returns(last)])
  when :while, :until, :while_post, :until_post
    sexp
  when :return, :js_return, :returnable_yield
    sexp
  when :xstr
    sexp.updated(nil, [s(:js_return, *sexp.children)])
  when :if
    cond, true_body, false_body = *sexp
    sexp.updated(
      nil, [
        cond,
        returns(true_body),
        returns(false_body)
      ]
    )
  else
    if sexp.type == :send && sexp.children[1] == :debugger
      # debugger is a statement, so it doesn't return a value
      # and returning it is invalid. Therefore we update it
      # to do `debugger; return nil`.
      sexp.updated(:begin, [sexp, s(:js_return, s(:nil))])
    else
      sexp.updated(:js_return, [sexp])
    end
  end
end

#s(type, *children) ⇒ 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.



361
362
363
 
# File 'opal/lib/opal/compiler.rb', line 361

def s(type, *children)
  ::Opal::AST::Node.new(type, children)
end

#source_map ⇒ Opal::SourceMap

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

Parameters:

  • source_file (String) —

    optional source_file to reference ruby source

Returns:



271
272
273
274
 
# File 'opal/lib/opal/compiler.rb', line 271

def source_map
  # We only use @source_map if compiler is cached.
  @source_map || ::Opal::SourceMap::File.new(@fragments, file, @source, @result)
end

#unique_temp(name) ⇒ Object

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



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
 
# File 'opal/lib/opal/compiler.rb', line 371

def unique_temp(name)
  name = name.to_s
  if name && !name.empty?
    name = name
           .to_s
           .gsub('<=>', '$lt_eq_gt')
           .gsub('===', '$eq_eq_eq')
           .gsub('==', '$eq_eq')
           .gsub('=~', '$eq_tilde')
           .gsub('!~', '$excl_tilde')
           .gsub('!=', '$not_eq')
           .gsub('<=', '$lt_eq')
           .gsub('>=', '$gt_eq')
           .gsub('=', '$eq')
           .gsub('?', '$ques')
           .gsub('!', '$excl')
           .gsub('/', '$slash')
           .gsub('%', '$percent')
           .gsub('+', '$plus')
           .gsub('-', '$minus')
           .gsub('<', '$lt')
           .gsub('>', '$gt')
           .gsub(/[^\w\$]/, '$')
  end
  unique = (@unique += 1)
  "#{'$' unless name.start_with?('$')}#{name}$#{unique}"
end

#use_strict? ⇒ Object

Enables JavaScript's strict mode (i.e., adds 'use strict'; statement)



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

compiler_option :use_strict, default: false, as: :use_strict?, magic_comment: true

#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.



347
348
349
 
# File 'opal/lib/opal/compiler.rb', line 347

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

#with_temp ⇒ 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.



422
423
424
425
426
427
 
# File 'opal/lib/opal/compiler.rb', line 422

def with_temp
  tmp = @scope.new_temp
  res = yield tmp
  @scope.queue_temp tmp
  res
end