From d11131927068a286764b8f21e418c782fbda41dc Mon Sep 17 00:00:00 2001 From: Tobias Nießen Date: Wed, 28 Jun 2017 18:14:23 +0200 Subject: doc: move module-specific "globals" to modules.md PR-URL: https://github.com/nodejs/node/pull/13962 Fixes: https://github.com/nodejs/node/issues/13953 Reviewed-By: Sam Roberts Reviewed-By: James M Snell Reviewed-By: Luigi Pinca --- doc/api/globals.md | 173 ++++++----------------------------------------------- 1 file changed, 19 insertions(+), 154 deletions(-) (limited to 'doc/api/globals.md') diff --git a/doc/api/globals.md b/doc/api/globals.md index c91acb3244..f3a2fc6377 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -2,8 +2,15 @@ -These objects are available in all modules. Some of these objects aren't -actually in the global scope but in the module scope - this will be noted. +These objects are available in all modules. The following variables may appear +to be global but are not. They exist only in the scope of modules, see the +[module system documentation][]: + +- [`__dirname`][] +- [`__filename`][] +- [`exports`][] +- [`module`][] +- [`require()`][] The objects listed here are specific to Node.js. There are a number of [built-in objects][] that are part of the JavaScript language itself, which are @@ -21,67 +28,12 @@ added: v0.1.103 Used to handle binary data. See the [buffer section][]. ## \_\_dirname - - - - -* {string} - -The directory name of the current module. This the same as the -[`path.dirname()`][] of the [`__filename`][]. - -`__dirname` is not actually a global but rather local to each module. -Example: running `node example.js` from `/Users/mjr` - -```js -console.log(__dirname); -// Prints: /Users/mjr -console.log(path.dirname(__filename)); -// Prints: /Users/mjr -``` +This variable may appear to be global but is not. See [`__dirname`]. ## \_\_filename - - - - -* {string} - -The file name of the current module. This is the resolved absolute path of the -current module file. - -For a main program this is not necessarily the same as the file name used in the -command line. -See [`__dirname`][] for the directory name of the current module. - -`__filename` is not actually a global but rather local to each module. - -Examples: - -Running `node example.js` from `/Users/mjr` - -```js -console.log(__filename); -// Prints: /Users/mjr/example.js -console.log(__dirname); -// Prints: /Users/mjr -``` - -Given two modules: `a` and `b`, where `b` is a dependency of -`a` and there is a directory structure of: - -* `/Users/mjr/app/a.js` -* `/Users/mjr/app/node_modules/b/b.js` - -References to `__filename` within `b.js` will return -`/Users/mjr/app/node_modules/b/b.js` while references to `__filename` within -`a.js` will return `/Users/mjr/app/a.js`. +This variable may appear to be global but is not. See [`__filename`]. ## clearImmediate(immediateObject) - - - -A reference to the `module.exports` that is shorter to type. -See [module system documentation][] for details on when to use `exports` and -when to use `module.exports`. - -`exports` is not actually a global but rather local to each module. -See the [module system documentation][] for more information. +This variable may appear to be global but is not. See [`exports`]. ## global - - -* {Object} - -A reference to the current module. In particular -`module.exports` is used for defining what a module exports and makes -available through `require()`. - -`module` is not actually a global but rather local to each module. - -See the [module system documentation][] for more information. +This variable may appear to be global but is not. See [`module`]. ## process - - - -* {Function} - -To require modules. See the [Modules][] section. `require` is not actually a -global but rather local to each module. - -### require.cache - - -* {Object} - -Modules are cached in this object when they are required. By deleting a key -value from this object, the next `require` will reload the module. Note that -this does not apply to [native addons][], for which reloading will result in an -Error. - -### require.extensions - - -> Stability: 0 - Deprecated - -* {Object} - -Instruct `require` on how to handle certain file extensions. - -Process files with the extension `.sjs` as `.js`: - -```js -require.extensions['.sjs'] = require.extensions['.js']; -``` - -**Deprecated** In the past, this list has been used to load -non-JavaScript modules into Node.js by compiling them on-demand. -However, in practice, there are much better ways to do this, such as -loading modules via some other Node.js program, or compiling them to -JavaScript ahead of time. - -Since the module system is locked, this feature will probably never go -away. However, it may have subtle bugs and complexities that are best -left untouched. - -Note that the number of file system operations that the module system -has to perform in order to resolve a `require(...)` statement to a -filename scales linearly with the number of registered extensions. - -In other words, adding extensions slows down the module loader and -should be discouraged. - -### require.resolve() - -Use the internal `require()` machinery to look up the location of a module, -but rather than loading the module, just return the resolved filename. +This variable may appear to be global but is not. See [`require()`]. ## setImmediate(callback[, ...args])