module SourceMap::Generator

Attributes

generated_col[RW]
generated_line[RW]
generated_output[RW]

An object (responding to <<) that will be written to whenever {add_generated} is called.

@example

File.open("/var/www/a.js.min"){ |f|
  map = SourceMap.new(:generated_output => f)
  map.add_generated('function(a,b,c){minified=1}\n', :source => 'a.js')
  map.save('/var/www/a.js.map')
}
File.read('/var/www/a.js.min') == 'function(a,b,c){minified=1}\n'
name_ids[R]
source_ids[R]

Public Instance Methods

add_generated(text, opts={}) click to toggle source

Add the mapping for generated code to this source map.

The first parameter is the generated text that you're going to add to the output, if it contains multiple lines of code then it will be added to the source map as several mappings.

If present, the second parameter represents the original source of the generated fragment, and may contain:

:source => String, # The filename of the source fille that contains this fragment. :source_line => Integer, # The line in that file that contains this fragment :source_col => Integer, # The column in that line at which this fragment starts :name => String # The original name for this variable. :exact_position => Bool # Whether all lines in the generated fragment came from

the same position in the source.

The :source key is required to set :source_line, :source_col or :name.

If unset :source_line and :source_col default to 1,0 for the first line of the generated fragment.

Normally :source_line is incremented and :source_col reset at every line break in the generated code (because we assume that you're copying a verbatim fragment from the source into the generated code). If that is not the case, you can set :exact_position => true, and then all lines in the generated output will be given the same :source_line and :source_col.

The :name property is used if the fragment you are adding contains only a name that you have renamed in the source transformation.

If you'd like to ensure that the source map stays in sync with the generated source, consider calling {source_map.generated_output = StringIO.new} and then accessing your generated javascript with {source_map.generated_output.string}, otherwise be careful to always write to both.

NOTE: By long-standing convention, the first line of a file is numbered 1, not 0.

NOTE: when generating a source map, you should either use this method always, or use the {#add_mapping} method always.

# File lib/source_map/generator.rb, line 58
def add_generated(text, opts={})
  if !opts[:source] && (opts[:name] || opts[:source_line] || opts[:source_col])
    raise "mapping must have :source to have :source_line, :source_col or :name"
  elsif opts[:source_line] && opts[:source_line] < 1
    raise "files start on line 1 (got :source_line => #{opts[:source_line]})"
  elsif !(remain = opts.keys - [:source, :source_line, :source_col, :name, :exact_position]).empty?
    raise "mapping had unexpected keys: #{remain.inspect}"
  end

  source_line = opts[:source_line] || 1
  source_col = opts[:source_col] || 0
  self.generated_line ||= 1
  self.generated_col ||= 0

  text.split(/(\n)/).each do |line|
    if line == "\n"
      self.generated_line += 1
      self.generated_col = 0
      unless opts[:exact_position]
        source_line += 1
        source_col = 0
      end
    elsif line != ""
      mapping = {
        :generated_line => generated_line,
        :generated_col => generated_col,
      }
      if opts[:source]
        mapping[:source] = opts[:source]
        mapping[:source_line] = source_line
        mapping[:source_col] = source_col
        mapping[:name] = opts[:name] if opts[:name]
      end

      mappings << mapping

      self.generated_col += line.size
      source_col += line.size unless opts[:exact_position]
    end
  end

  generated_output << text if generated_output
end
add_mapping(map) click to toggle source

Add a mapping to the list for this object.

A mapping identifies a fragment of code that has been moved around during transformation from the source file to the generated file. The fragment should be contiguous and not contain any line breaks.

Mappings are Hashes with a valid subset of the following 6 keys:

:generated_line => Integer, # The line in the generated file that contains this fragment. :generated_col => Integer, # The column in the generated_line that this mapping starts on :source => String, # The filename of the source fille that contains this fragment. :source_line => Integer, # The line in that file that contains this fragment. :source_col => Integer, # The column in that line at which this fragment starts. :name => String # The original name for this variable (if applicable).

The only 3 valid subsets of keys are:

[:generated_line, :generated_col] To indicate that this is a fragment in the
output file that you don't have the source for.

[:generated_line, :generated_col, :source, :source_line, :source_col] To indicate
that this is a fragment in the output file that you do have the source for.

[:generated_line, :generated_col, :source, :source_line, :source_col, :name] To
indicate that this is a particular identifier at a particular location in the original.

Any other combination of keys would produce an invalid source map.

NOTE: By long-standing convention, the first line of a file is numbered 1, not 0.

NOTE: when generating a source map, you should either use this method always, or use the {#add_generated} method always.

# File lib/source_map/generator.rb, line 135
def add_mapping(map)
  if !map[:generated_line] || !map[:generated_col]
    raise "mapping must have :generated_line and :generated_col"
  elsif map[:source] && !(map[:source_line] && map[:source_col])
    raise "mapping must have :source_line and :source_col if it has :source"
  elsif !map[:source] && (map[:source_line] || map[:source_col])
    raise "mapping may not have a :source_line or :source_col without a :source"
  elsif map[:name] && !map[:source]
    raise "mapping may not have a :name without a :source"
  elsif map[:source_line] && map[:source_line] < 1
    raise "files start on line 1 (got :source_line => #{map[:source_line]})"
  elsif map[:generated_line] < 1
    raise "files start on line 1 (got :generated_line => #{map[:generated_line]})"
  elsif !(remain = map.keys - [:generated_line, :generated_col, :source, :source_line, :source_col, :name]).empty?
    raise "mapping had unexpected keys: #{remain.inspect}"
  end

  mappings << map
end
as_json() click to toggle source

Convert the map into an object suitable for direct serialisation.

# File lib/source_map/generator.rb, line 156
def as_json
  serialized_mappings = serialize_mappings!

  {
    'version' => version,
    'file' => file,
    'sourceRoot' => source_root,
    'sources' => sources,
    'names' => names,
    'mappings' => serialized_mappings
  }
end
save(file) click to toggle source

Write this map to a file.

# File lib/source_map/generator.rb, line 175
def save(file)
  File.open(file, "w"){ |f| f << to_s }
end
to_s() click to toggle source

Convert the map to a string.

# File lib/source_map/generator.rb, line 170
def to_s
  as_json.to_json
end

Protected Instance Methods

name_id(name) click to toggle source

Get the id for the given name. If we've not seen this name before, add it to the list.

# File lib/source_map/generator.rb, line 195
def name_id(name)
  name_ids[name] ||= (
    names << name
    names.size - 1
  )
end
serialize_mapping(map) click to toggle source
# File lib/source_map/generator.rb, line 236
def serialize_mapping(map)
  item = vlq(map[:generated_col], :generated_col)
  if map[:source]
    item << vlq(source_id(map[:source]), :source)
    item << vlq(map[:source_line] - 1, :source_line)
    item << vlq(map[:source_col], :source_col)
    item << vlq(name_id(map[:name]), :name) if map[:name]
  end
  item
end
serialize_mappings!() click to toggle source

Serialize the list of mappings into the string of base64 variable length quanities. As a side-effect, regenerate the sources and names arrays.

# File lib/source_map/generator.rb, line 212
def serialize_mappings!
  # clear all internals as we're about to re-generate them.
  @sources  = []
  @source_ids = {}
  @names    = []
  @name_ids = {}
  @previous_vlq = Hash.new{ 0 }

  return "" if mappings.empty?

  by_lines = mappings.group_by{ |x| x[:generated_line] }

  (1..by_lines.keys.max).map do |line|
    # reset the generated_col on each line as indicated by the VLQ spec.
    # (the other values continue to be relative)
    @previous_vlq[:generated_col] = 0

    fragments = (by_lines[line] || []).sort_by{ |x| x[:generated_col] }
    fragments.map do |map|
      serialize_mapping(map)
    end.join(",")
  end.join(";")
end
source_id(file) click to toggle source

Get the id for the given file. If we've not seen this file before, add it to the list.

# File lib/source_map/generator.rb, line 186
def source_id(file)
  source_ids[file] ||= (
    sources << file
    sources.size - 1
  )
end
vlq(num, type) click to toggle source

Encode a vlq. As each field in the output should be relative to the previous occurance of that field, we keep track of each one.

# File lib/source_map/generator.rb, line 204
def vlq(num, type)
  ret = num - @previous_vlq[type]
  @previous_vlq[type] = num
  VLQ.encode(ret)
end