gumshoe
Version:
Project type detection library for Node.JS using declarative heuristic predicates
94 lines (66 loc) • 2.96 kB
Markdown
Gumshoe
=======
Project type detection library using declarative heuristic predicates.
Say you have a Git repo on disk, and you want to figure out what kind of
language it is written in, what framework it uses, etc. With simple heuristics
such as looking for a `package.json` file in the project root, this can be
easily deduced.
Gumshoe makes it easy to specify these heuristics declaritively using predicates:
```javascript
// Detect a node.js project
var rules = [
{filename:"package.json", exists:true, language:"node.js"}
]
```
More complicated example:
```javascript
// Detect a node.js project using connect, express or null frameworks
var rules = [
{filename:"package.json", grep:/express/i, language:"node.js", framework:"express"},
{filename:"package.json", grep:/connect/i, language:"node.js", framework:"connect"},
{filename:"package.json", exists:true, language:"node.js", framework:null}
]
```
Rule Structure
==============
As shown above, rules are merely objects with some properties. Gumshoe provides a set of special, reserved
property names which are evaluated as predicates:
- `filename`: This is the filename relative to the `baseDir` to look for. Each rule must have a `filename` property or Gumshoe will complain. Value may be a glob as supported by the [node-glob](https://github.com/isaacs/node-glob) library.
- `grep`: `filename` must exist and content must match the regular expression provided as value to `grep`
- `exists`: Boolean value. `true` means `filename` must exist, `false` means `filename` must not exist. This does not care what kind of file it is.
- `jsonKeyExists`: String value. This is the name of a key in the JSON data which must exist in `filename`. Nested keys can be specified using dot notation. For example, "foo.bar" would match `{"foo":{"bar":1}}`.
When a rule succeeds and is matched, it is copied with all properties except
for the reserved properties. Hence you are free to use any key names you wish
like `framework`, `language` or `foobar` - they will be handed back to you in
the result object.
Installation
============
Gumshoe is available in NPM. `npm install gumshoe`
Example
=======
```javascript
var gumshoe = require('gumshoe')
// Use current working dir
var baseDir = process.cwd()
// Detect a node.js project
var rules = [
{filename:"package.json", exists:true, language:"node.js"}
]
gumshoe.run(baseDir, rules, function(err, res) {
if (err) {
console.log("Detection error: %s", err)
process.exit(1)
}
console.log("Detected language: %s", res.language)
})
```
Tests
=====
Gumshoe comes with tests. To run, simply execute `npm test`.
License
=======
Gumshoe is released under a BSD license.
Credits
=======
Picture of Legoman gumshoe CC-BY David Anderson from http://www.flickr.com/photos/venndiagram/5328211162/