mirror of
https://github.com/jsdoc/jsdoc.git
synced 2025-12-08 19:46:11 +00:00
fd5ca944d2
JSDoc has a few requirements that are somewhat unusual for a Node.js app:
1. We need `require('jsdoc/foo')` to work from any module.
2. We need `require('jsdoc/foo')` to work from external code, such as templates and plugins.
Prior to this commit, JSDoc did two separate things to meet these requirements:
1. Use an npm post-install script to create a symlink from `lib/jsdoc` to `node_modules/jsdoc`.
2. When a user runs JSDoc, copy templates and plugins into the JSDoc directory.
These fixes worked, sort of. But they also caused numerous issues with file permissions, especially on Windows.
We now use the Requizzle module, which hacks the Node.js module system to support JSDoc's use cases. There's no longer a post-install script, and there's no need for a symlink in `node_modules`.
47 lines
6.6 KiB
JSON
47 lines
6.6 KiB
JSON
{
|
|
"name": "requizzle",
|
|
"version": "0.1.0",
|
|
"description": "Swizzle a little something into your require() calls.",
|
|
"main": "index.js",
|
|
"scripts": {
|
|
"test": "gulp test"
|
|
},
|
|
"repository": {
|
|
"type": "git",
|
|
"url": "git://github.com/hegemonic/requizzle.git"
|
|
},
|
|
"keywords": [
|
|
"module",
|
|
"modules",
|
|
"require",
|
|
"inject",
|
|
"dependency",
|
|
"swizzle"
|
|
],
|
|
"author": {
|
|
"name": "Jeff Williams",
|
|
"email": "jeffrey.l.williams@gmail.com"
|
|
},
|
|
"license": "MIT",
|
|
"bugs": {
|
|
"url": "https://github.com/hegemonic/requizzle/issues"
|
|
},
|
|
"homepage": "https://github.com/hegemonic/requizzle",
|
|
"devDependencies": {
|
|
"expectations": "~0.2.5",
|
|
"gulp": "~3.6.2",
|
|
"gulp-eslint": "~0.1.6",
|
|
"gulp-istanbul": "~0.2.0",
|
|
"gulp-istanbul-enforcer": "~1.0.2",
|
|
"gulp-mocha": "~0.4.1"
|
|
},
|
|
"dependencies": {
|
|
"underscore": "~1.6.0"
|
|
},
|
|
"readme": "# Requizzle #\n\nSwizzle a little something into your Node.js modules.\n\n\n## What's Requizzle? ##\n\nRequizzle provides a drop-in replacement for Node.js's `require()` function. This replacement\nallows you to change a module's source code at runtime.\n\nYou can use Requizzle in your test cases, or in production code if you like to live dangerously.\nRequizzle has been tested with Node.js 0.10 and 0.11.\n\nHere's what Requizzle can do:\n\n### Look for modules in new places ###\n\nWith Requizzle, you can add directories to the module lookup path, which forces Node.js to search\nthose directories for modules. This can be useful if:\n\n+ You're tired of writing code like `require('../../../../../lib/foo')`.\n+ You want to expose your app's modules to external plugins. (Without Requizzle, it can be tough to\ndo this if the plugin is located outside of your app directory.)\n\n### Add code before or after the module's source code ###\n\nTamper with modules to your heart's delight by adding arbitrary code before or after the module's\nown source code.\n\n### Mess with child modules ###\n\nWhen you use Requizzle to require a module, you can force each child module's `require` method to\ninherit your changes to the parent module. (By default, only the parent module is changed.)\n\n### Preserve strict-mode declarations ###\n\nIf a module starts with a strict-mode declaration, Requizzle keeps it in place. Your changes will\nappear after the strict-mode declaration.\n\n### Leave native modules alone ###\n\nIf you use one of Node.js's built-in modules, such as `fs` or `path`, Requizzle won't mess with it.\n\n\n## Installation ##\n\nWith npm:\n\n npm install requizzle\n\nWith git:\n\n git clone git://github.com/hegemonic/requizzle.git\n cd requizzle\n npm install\n\n\n## Usage ##\n\nThe Requizzle module exports a single function, which returns a drop-in replacement for\n`require()`.\n\nWhen you call the function, you must pass in an `options` object, which can include any of these\nproperties:\n\n+ `extras`: A pair of functions that return text to insert before or after the module's source code.\nEach function accepts two parameters: `targetPath`, the path to the required module, and\n`parentModule`, the `Module` object for the module's parent. Each function must return a string.\n + `extras.before`: A function that returns text to insert before the module's source code.\n + `extras.after`: A function that returns text to insert after the module's source code.\n+ `infect`: Determines whether child modules are infected with the same changes as the parent\nmodule. Set to `true` to force child modules to inherit your changes. Defaults to `false`.\n+ `requirePaths`: An array of additional paths to search for required modules. For example, if\n`requirePaths` is set to `['/usr/lib/junk/modules']`, and you save a JavaScript module at\n`/usr/lib/junk/modules/mymodule.js`, you can require the module as `mymodule`. By default, the\nrequire path is not changed.\n\n\n## Examples ##\n\n```js\nvar requizzle = require('requizzle');\n\n// Say hello and goodbye to each module.\nvar logRequire = requizzle({\n extras: {\n before: function(targetPath, parentModule) {\n return 'console.log(\"Hello %s!\", ' + targetPath + ');\\n';\n },\n after: function(targetPath, parentModule) {\n return 'console.log(\"Goodbye %s!\", ' + targetPath + ');\\n';\n }\n }\n});\n// Prints \"Hello /path/to/mymodule.js!\" and \"Goodbye /path/to/mymodule.js!\"\nvar myModule = logRequire('mymodule');\n\n// Look for modules in the current module's `lib` directory, and force child\n// modules to do the same.\nvar path = require('path');\nvar extraPathRequire = requizzle({\n infect: true,\n requirePaths: [path.join(__dirname, 'lib')]\n});\n// If `foo` needs to require a module in `./lib`, it can use `require('bar')`\n// instead of `require('./lib/bar')`.\nvar foo = extraPathRequire('./foo');\n```\n\n\n## Troubleshooting ##\n\nHere are some problems you may run into when you use Requizzle, along with solutions to each\nproblem. If you run into any problems that aren't addressed here, please file a new issue!\n\n### Requizzle slowed down my code! A lot! ###\n\nRequizzle adds minimal overhead to the module-loading process. In some cases, it may even be faster\nthan Node.js's built-in `require()` function.\n\nHowever, your code will run _much_ slower than usual if you do both of the following:\n\n+ Use Requizzle's `infect` option.\n+ Require modules that have a lot of `require()` calls within the scope of individual functions.\n\nTo fix this issue, find the module calls that are within function scope, and move them to each\nmodule's top-level scope. You can find the biggest offenders by using Node.js's built-in `--prof`\noption to profile your app, then running [node-tick](https://github.com/sidorares/node-tick) to\ncreate a report that shows the number of ticks per function.\n\n### Requizzle made my module do something weird! ###\n\nDo you have any [circular dependencies](http://nodejs.org/api/modules.html#modules_cycles) in the\nmodules that aren't working? Circular dependencies can cause unusual behavior with Requizzle, just\nas they can without Requizzle. Try breaking the circular dependency.\n\n### Requizzle violates the sacred Law of Demeter! It's an unnatural abomination! ###\n\nFair enough.\n\n\n## Acknowledgements ##\n\nRequizzle is very loosely adapted from Johannes Ewald's [rewire](https://github.com/jhnns/rewire)\nmodule, which is designed to modify a module's behavior for unit testing. If Requizzle doesn't meet\nyour needs, please take a look at rewire!\n\n\n## License ##\n\n[MIT license](LICENSE).\n",
|
|
"readmeFilename": "README.md",
|
|
"_id": "requizzle@0.1.0",
|
|
"_shasum": "f07a630ba62e188f64ccb7d408bff31787e83793",
|
|
"_from": "requizzle@~0.1.0"
|
|
}
|