See the documentation for modify() for an explanation of how markers work. That explanation mentions that arbitrary data can be associated with a marker as part of a call to the modify() function. To later query the data associated with a given marker, use this function.

Get the modified text for this source map. At construction time, this will be the same as the source text, but can change via calls to modify().

See the documentation for modifiedPosition(); this function behaves similarly, except that it takes as input a line number and column number in the source text, and returns a line number and column number in the modified text.

Unlike character indices, line and column numbers start counting at 1, so the first character in the text (at index 0) would be in line 1 and at column 1.

See the documentation for sourcePosition(); this function is (approximately) the inverse to that function. The only difference is, as documented in that function, we cannot map precisely each character within a section of modified text, and thus we map to the first charcter in the corresponding range. For example, in the source map mentioned at the top of this page, each character in the source text "5+9" would map to the first character in the modified text "14."

Source map objects contain both a source text and a modified text, which are equal at construction time. But through one or more calls to this function, the modified text can change, diverging from the source text. This function not only makes such modifications, but it records where they were made, and any data associated with them, so that queries can be made later about correspondences between the source and modified text, as documented at the top of this file.

The first three parameters are straightforward, as documented below. However, the fourth parameter (which is optional) requires additional explanation. When replacing a portion of the source text, it is sometimes convenient to replace it not with text, but with arbitrary data. We support this more advanced usage as follows.

• First, the newly inserted text cannot be arbitrary text, but should instead be a special marker that indicates the location where non-text data resides. To create such markers, use the nextMarker() function.
• Second, the fourth parameter (data) should be provided, and it can be any JavaScript object amenable to JSON encoding, which will be stored in this object for later querying.
• Later, when the client processes the modified text, upon encountering a marker (see isMarker()) and desiring to know what data it represents, the client can find out with a call to dataForMarker().

For example, let's say our source text was "Get me employee #16" and we wanted to replace "employee #16" with the full data for that employee, which is not text data, but rather something more complex, such as { name:'Henrietta', age:35, ... }. Assuming we have that data in an object obj, we could make a call like the following.

sourcemap.modify( 7, 12, sourcemap.nextMarker(), obj )

Notes:

1. When passing data as the optional fourth parameter, you must pass sourcemap.nextMarker() as the third parameter, because data is stored internally only associated with markers, and cannot be retrieved later otherwise.
2. The starting index documented below is in the modified text, not the source text, but if this is inconvenient for you, simply make use of the modifiedPosition() function to convert what you have to what you need.
3. Modifications must be made in increasing order of index in the modified text. For example, if you have a replacement to do on characters 5 through 10 and another to do on characters 50 through 70, you must do them in that order, not the reverse. This class does not support modifications in arbitrary order.

See the documentation for modify() for an explanation of how markers work. That explanation mentions that it is useful to have a sequence of markers, each of which is a unique snippet of text that does not appear anywhere in the original source text. This function can be used as a generator, returning a different string each time it is called, none of which appeared in the original source text. In that way it can be used to generate markers that can be passed as the replacement parameter to modfiy().

As discussed in the documentation for modify(), modifications must be made in increasing order of position in the modified text. Thus at any point, we have a minimum index at which the next modification could take place, so that it falls after all modifications made so far. This function returns that minimum index.

For example, in the source map described at the top of this file (in which "5+9" became "14" inside the source text), the next viable index in the modified text where a modification could be made is immediately after the text "14," that is, at index 16.

If no modifications have been made to the source text, this function will return zero.

Get the source text given at the time this source map was constructed. This class provides no API for altering the source text, so it should be the same any time this function is called.

See the documentation for sourcePosition(); this function behaves similarly, except that it takes as input a line number and column number in the modified text, and returns a line number and column number in the source text.

Unlike character indices, line and column numbers start counting at 1, so the first character in the text (at index 0) would be in line 1 and at column 1.

The major purpose of the SourceMap class is to track the correspondence of character positions between its source text and its modified text. This function can be used to do a lookup from the latter to the former; you provide a character position in the modified text and it returns the corresponding position in the source text.

If the character position sits inside a section of modified text, there may not be an exact correspondence of which character in the source text relates to it; for example, in the source map mentioned at the top of this documentation page, which characters in "5+9" correspond to each character in the text "14?" In such cases, the first character in the corresponding section is returned. So both characters in "14" would be said to correspond to the first character in "5+9."

If the character position sits inside a section of unmodified text, then there is an exact copy of that unmodified text in the source text, and thus the corresponding position with it will be returned.

If an invalid index is provided, undefined is returned. Indices into both the source and modified texts are zero-based, so the first valid index is 0 and the last is the length of the text minus 1.

A debugging routine useful when working with code in which you care about the specific character indices and/or line and column numbers. Call this routine to print the code to the console, with a line and character number added at the start of each line, using the format L_C_: with the blanks replaced by line and character numbers, respectively.

For example, "function ( x ) {\n\treturn 3;\n}" would be printed as follows. Note that these are not line and column numbers, but rather line numbers and character indices.

L1C0: function ( x ) {
L2C17:        return 3;
L3C27: }

See the documentation for modify() and nextMarker() for an explanation of how markers can be useful. This function is a predicate for testing whether an arbitrary string contains a marker.