77//
88import Foundation
99
10- /// Don't support extension fields ("x_|whatever|"): nobody seems to use them, even the one in the spec
11- /// seems unknown today, and it immensely complicates the JSON layer.
10+ /// A source map describing how each segment of a generated file corresponds to some original source file.
1211///
13- /// 1 - open a sourcemap, mess around with it a bit, rewrite it,
14- /// 2 - join multiple sourcemaps together
15- /// 3 - open a sourcemap and use it, doing location queries including source file locations
16- /// 4 - create a new sourcemap from scratch and write it to a file .
12+ /// The main use cases imagined are:
13+ /// 1. Read a source map `init(data:checkMappings:)` and query it `map(...)`.
14+ /// 2. Read a source map, make minor modifications, write it back `encode(...)`.
15+ /// 3. Create a new source map `init(version:)`, fill in fields, and write it .
1716///
17+ /// There are two representations of the actual mappings. The `mappings` property holds
18+ /// the compacted mapping string that looks like `AAAA;EACA`. These can be decoded into
19+ /// arrays of `Segment`s. These arrays can be very large and time-consuming to create, and
20+ /// so they are usually generated on-demand via `getSegments()`.
1821public final class SourceMap {
1922 /// Create an empty source map.
2023 public init ( version: Int = SourceMap . VERSION) {
@@ -37,31 +40,25 @@ public final class SourceMap {
3740 /// The name of the generated code file with which the source map is associated.
3841 public var file : String ?
3942
40- /// Value to prepend to each `sources` url before attempting their resolution.
43+ /// Value to prepend to each `sources` URL before attempting their resolution.
4144 public var sourceRoot : String ?
4245
4346 /// The location and content of an original source referred to from the source map.
4447 ///
4548 /// Use `getSourceURL(...)`to interpret source URLs incorporating `sourceRoot`.
46- public enum Source {
47- case remote( url: String )
48- case inline( url: String , content: String )
49-
49+ public struct Source {
5050 /// The URL recorded in the source map for this source.
51- /// - see: `SourceMap.getSourceURL(...)`.
52- public var url : String {
53- switch self {
54- case . remote( let url) ,
55- . inline( let url, _) : return url
56- }
57- }
51+ ///
52+ /// See: `SourceMap.getSourceURL(...)`.
53+ public let url : String
5854
5955 /// The content, if any, recorded in the source map for this source.
60- public var content : String ? {
61- switch self {
62- case . remote: return nil
63- case . inline( _, let content) : return content
64- }
56+ public let content : String ?
57+
58+ /// Initialize a new Source.
59+ public init ( url: String , content: String ? = nil ) {
60+ self . url = url
61+ self . content = content
6562 }
6663 }
6764
@@ -76,12 +73,12 @@ public final class SourceMap {
7673
7774 /// Get the URL of a source, incorporating the `sourceRoot` if set.
7875 ///
79- /// - parameter sourceIndex : The index into `sources` to look up.
76+ /// - parameter source : The index into `sources` to look up.
8077 /// - parameter sourceMapURL: The absolute URL of this source map -- relative source URLs
8178 /// are interpreted relative to this base.
82- public func getSourceURL( sourceIndex : Int , sourceMapURL: URL ) -> URL {
83- precondition ( sourceIndex < sources. count)
84- let sourceURLString = ( sourceRoot ?? " " ) + sources[ sourceIndex ] . url
79+ public func getSourceURL( source : Int , sourceMapURL: URL ) -> URL {
80+ precondition ( source < sources. count)
81+ let sourceURLString = ( sourceRoot ?? " " ) + sources[ source ] . url
8582 if let sourceURL = URL ( string: sourceURLString) ,
8683 sourceURL. scheme != nil {
8784 return sourceURL
@@ -104,7 +101,7 @@ public final class SourceMap {
104101 public let source : Int32
105102 /// 0-based line index into the original source file.
106103 public let line : Int32
107- /// 0-based column index into line `lineIndex `.
104+ /// 0-based column index into line `line `.
108105 public let column : Int32
109106 /// 0-based index into `SourceMap.names` of any name associated with
110107 /// the mapping segment, or `nil` if there is none.
@@ -136,7 +133,7 @@ public final class SourceMap {
136133 /// 0-based column in the generated code that ends the segment, or `nil`
137134 /// indicating 'until either the next segment or the end of the line'.
138135 ///
139- /// This field is optional and advisory - it's not stored in the sourcemap itself, rather
136+ /// This field is optional and advisory - it's not stored in the source map itself, rather
140137 /// calculated (guessed) from the next `firstColumn` value. Its value is not
141138 /// used in comparisons between two `Segment`s.
142139 public internal( set) var lastColumn : Int32 ?
@@ -170,20 +167,23 @@ public final class SourceMap {
170167 sourcePos: sourcePos)
171168 }
172169
173- /// Compare two segments. The `lastColumn` value is not included.
170+ /// Compare two segments. The `lastColumn` value is not included. :nodoc:
174171 public static func == ( lhs: Segment , rhs: Segment ) -> Bool {
175172 lhs. firstColumn == rhs. firstColumn &&
176173 lhs. sourcePos == rhs. sourcePos
177174 }
178175
179- /// Hash the segment.
176+ /// Hash the segment. :nodoc:
180177 public func hash( into hasher: inout Hasher ) {
181178 hasher. combine ( firstColumn)
182179 hasher. combine ( sourcePos)
183180 }
184181 }
185182
186- /// The mappings in their compacted format
183+ /// The mappings in their compacted format.
184+ ///
185+ /// If you use `setSegments(...)` to change the segments then this field is not updated to match
186+ /// until the next call to `encode(...)` so be careful reading it during this window.
187187 public internal( set) var mappings : String
188188
189189 /// Track consistency between `mappings` and `_mappingSegments`.
@@ -215,7 +215,7 @@ extension SourceMap.Segment: CustomStringConvertible {
215215extension SourceMap {
216216 /// A formatted multi-line string describing the mapping segments.
217217 ///
218- /// - throws: something if the mapping segments can't be decoded from the source .
218+ /// - throws: If the mapping segments can't be decoded.
219219 public func getSegmentsDescription( ) throws -> String {
220220 var line = 0
221221 var lines : [ String ] = [ ]
@@ -239,6 +239,7 @@ extension SourceMap {
239239}
240240
241241extension SourceMap : CustomStringConvertible {
242+ /// A short description of the source map.
242243 public var description : String {
243244 var str = " SourceMap(v= \( version) "
244245 if let file = file {
0 commit comments