update (3/8/2013)
External programs (specifically TiStudio) will be able to query Alloy's source maps by using the new "alloy debugger" command. These source maps are in [Mozilla's source-map format](
https://github.com/mozilla/source-map). The command take the following format (note, most of this information can be found by simple executing "alloy --help"):
alloy debugger -b <original|generated> <SOURCE_MAP_FILE> [options]
arguments and options
* - The "-b" must included to make sure Alloy's banner information is not printed, which will return with the source information in JSON format
* - After "debugger" you must type either "original" or "generated". This will indicate whether you are looking for the original or generated file and position
* - SOURCE_MAP_FILE, as you might imagine, is the path to the source map file that you wish to query for information. For more details on the location and filename format of Alloy source maps, check out ALOY-537.
* options
** - "-x, --column" is the column you wish to query from the source map. Default 1.
** - "-y, --line" is the line you wish to query from the source map. Default 1.
** - "-z, --source" when performing a "generated" query, this is the original source file from which we want to know the generated position. The file should be specified as a path relative to the project root. This will be explained more in the examples below.
returned data
* "original" queries
{
source: 'app/controllers/index.js', // the original file
line: 4,
column: 5,
name: null // unused, always null
}
* "generated" queries
{
line: 12,
column: 1
}
Examples
* Find the generated position of line 4, column 1 of "app/alloy.js"
alloy debugger generated ".map/Resources/app.js.map" --line 4 --column 1 --source "app/alloy.js"
#output
{
line: 10,
column 1
}
* Find the generated position of line 56, column 5 of "app/controllers/index.js"
alloy debugger generated ".map/Resources/alloy/controllers/index.js.map" --line 56 --column 5 --source "app/controllers/index.js"
output
{
line: 135,
column 9
}
* Find the original position of line 135, column 9 of "Resources/alloy/controllers/index.js"
alloy debugger original ".map/Resources/alloy/controllers/index.js.map" --line 135 --column 9
output
{
source: "app/controllers/index.js"
line: 56,
column 5,
name: null
}
* Find the original position of some line and column that was auto-generated by Alloy, not by the developer's controller code. It will point you back to the same runtime file, avoiding the confusion of it pointing back to the Alloy template file that it was based on.
alloy debugger original ".map/Resources/alloy/controllers/index.js.map" --line 3 --column 1
output
{
source: "Resources/alloy/controllers/index.js"
line: 3,
column 1,
name: null
}
Additional Notes
* - The lines and columns are 1-based
* - Whenever an "original" source map query does not refer back to a developer's controller code or app.js code, the same position in the same file will be returned back. This is shown in the final example above.
* - column number is very important when doing "original" queries, not so much for "generated". This means that when doing an "original" query, you'll want to include the column number that actually represents where the code starts, not just 1 or the whitespace before the code. Without a valid column number that refers to the actual location of the code you'll often get unexpected results.
original
Here is the proposed syntax for the API:
https://wiki.appcelerator.org/display/tools/Alloy+Debugging.
No comments