Permalink
Browse files

Documentation

Adds comments to most of jsgreps exported functions.
  • Loading branch information...
1 parent ab21d53 commit 20f6c74f067d0f41fa43556aac66777f17ef383f Ryan Patterson committed Jan 22, 2012
Showing with 65 additions and 3 deletions.
  1. +65 −3 lib/jsgrep.js
View
68 lib/jsgrep.js
@@ -19,6 +19,11 @@ function Matcher(ast, options) {
}
exports.Matcher = Matcher;
+/**
+ * Convert a string pattern into an AST suitable for matching against. This
+ * methods caches patterns to speed up repeated uses of the same pattern (which
+ * will happen when placing patterns inside of matcher callbacks).
+ */
Matcher.compilePattern = function(pattern, filename, lineno) {
if (typeof pattern !== 'string') {
// It must already be compiled
@@ -34,6 +39,10 @@ Matcher.compilePattern = function(pattern, filename, lineno) {
return patternAst;
};
+/**
+ * Convert a string pattern into an AST suitable for matching against. This
+ * method bypasses the cache, which should never be necessary.
+ */
Matcher.compilePatternNoCache = function(pattern, filename, lineno) {
var patternAst = Narcissus.parser.parse(pattern, filename, lineno);
@@ -51,17 +60,29 @@ Matcher.compilePatternNoCache = function(pattern, filename, lineno) {
return patternAst;
};
+/**
+ * Returns true if the specified identifier should be treated as a metavariable.
+ */
Matcher.identifierIsMetavar = function(identifier) {
return /^[A-Z](_.*)?$/.test(identifier);
};
+/**
+ * Returns the original source code for the given AST node.
+ *
+ * @param {Narcissus.parser.Node} target
+ */
Matcher.getSourceForNode = function(target) {
var tokenizer = target.tokenizer;
var start = target.start + target.tokenizer.jsgrepDelta;
var end = target.end + target.tokenizer.jsgrepDelta;
return target.tokenizer.source.substring(start, end);
};
+/**
+ * Extracts the context lines and removed lines from the patch file and returns
+ * them.
+ */
Matcher.getPatternFromPatch = function(patch) {
var pattern = [];
var lines = patch.split('\n');
@@ -81,6 +102,13 @@ Matcher.getPatternFromPatch = function(patch) {
return pattern.join('\n');
};
+/**
+ * Attempt to find the given pattern in the AST rooted at this Matcher. For each
+ * match of the pattern, the callback will be called. If the callback does not
+ * return false, the node will be considered a match.
+ *
+ * @returns Array of AST nodes that match.
+ */
Matcher.prototype.find = function(pattern, callback, options) {
var ret = [ ];
var self = this;
@@ -92,23 +120,40 @@ Matcher.prototype.find = function(pattern, callback, options) {
return ret;
};
+/**
+ * Similar to Matcher.find, but finds matches strictly.
+ */
Matcher.prototype.findStrict = function(pattern, callback) {
return this.find(pattern, callback, { strictMatches: true });
};
+/**
+ * Determine if the AST rooted at this Matcher is a match to the given pattern.
+ * If a callback is provided, it additionally must not return false in order for
+ * this node to match.
+ */
Matcher.prototype.match = function(pattern, callback) {
var matchOptions = { };
return this._match(this.ast, pattern, callback, matchOptions);
};
+/**
+ * Similar to Matcher.match, but this node must match strictly.
+ */
Matcher.prototype.matchStrict = function(pattern, callback) {
var matchOptions = { strictMatches: true };
return this._match(this.ast, pattern, callback, matchOptions);
};
/**
- * Return the results of applying a single patch chunk to this matcher's node.
- * The matcher must strictly match the patch!
+ * Applies a patch to this matchers node, and returns the modified source code
+ * fragment. The matcher must strictly match the patch pattern!
+ *
+ * @param {String} patch The patch chunk to apply.
+ * @param {String} filename The filename corresponding to the patch file.
+ * @param {Number} line The first line number of the passed chunk relative to
+ * filename.
+ * @type String
*/
Matcher.prototype.getPatchedCode = function(patch, filename, line) {
const tokens = Narcissus.definitions.tokenIds;
@@ -350,6 +395,17 @@ function tokenString(tt) {
}
/**
+ * Calls 'eval' on the match script. Placed here as a global function to avoid
+ * accidentally creating a closure with the user script.
+ *
+ * @param {String} matchScript the contents of the match script
+ * @type Function
+ */
+function evalMatchScript(matchScript) {
+ return eval("(function custom_matcher(jsgrep) {" + matchScript + "})");
+}
+
+/**
* Match a set of jsgrep patterns against an AST. Options are:
*
* - source: AST or String. Source to match against.
@@ -386,7 +442,7 @@ var jsgrep = exports.jsgrep = function(options) {
};
}
- matchFn = eval("(function custom_matcher(jsgrep) {" + matchScript + "})");
+ matchFn = evalMatchScript(matchScript);
} else {
matchFn = options.matchScript;
}
@@ -832,6 +888,12 @@ var astIsEqual = exports.astIsEqual = function(node, pattern, config) {
}
}
+/**
+ * Recursively call the callback on each node in the AST.
+ *
+ * @param {Narcissus.parser.Node} node The root of the AST tree being traversed.
+ * @param {Function} callback Function to call on each child, recursively.
+ */
var forEachNode = exports.forEachNode = function(node, callback) {
const tokens = Narcissus.definitions.tokenIds;

0 comments on commit 20f6c74

Please sign in to comment.