diff options
author | Tobias Nießen <tniessen@tnie.de> | 2017-06-28 19:14:23 +0300 |
---|---|---|
committer | Anna Henningsen <anna@addaleax.net> | 2017-07-18 20:57:22 +0300 |
commit | e36561a8288f96e14e6eb844bcd7af187c8529c4 (patch) | |
tree | b159f24720c14f6cd91bdbefcb0e3547ca4d1256 /doc/api/globals.md | |
parent | f7383eb80e10747699323997c5440001eeb5dbc5 (diff) |
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 <vieuxtech@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Diffstat (limited to 'doc/api/globals.md')
-rw-r--r-- | doc/api/globals.md | 173 |
1 files changed, 19 insertions, 154 deletions
diff --git a/doc/api/globals.md b/doc/api/globals.md index c91acb32447..f3a2fc63779 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -2,8 +2,15 @@ <!-- type=misc --> -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 -<!-- YAML -added: v0.1.27 ---> - -<!-- type=var --> - -* {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 -<!-- YAML -added: v0.0.1 ---> - -<!-- type=var --> - -* {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) <!-- YAML @@ -122,19 +74,8 @@ added: v0.1.100 Used to print to stdout and stderr. See the [`console`][] section. ## exports -<!-- YAML -added: v0.1.12 ---> - -<!-- type=var --> - -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 <!-- YAML @@ -151,21 +92,8 @@ Node.js this is different. The top-level scope is not the global scope; `var something` inside a Node.js module will be local to that module. ## module -<!-- YAML -added: v0.1.16 ---> -<!-- type=var --> - -* {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 <!-- YAML @@ -179,71 +107,8 @@ added: v0.1.7 The process object. See the [`process` object][] section. ## require() -<!-- YAML -added: v0.1.13 ---> - -<!-- type=var --> - -* {Function} - -To require modules. See the [Modules][] section. `require` is not actually a -global but rather local to each module. - -### require.cache -<!-- YAML -added: v0.3.0 ---> - -* {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 -<!-- YAML -added: v0.3.0 -deprecated: v0.10.6 ---> - -> 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() -<!-- YAML -added: v0.3.0 ---> -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]) <!-- YAML @@ -272,20 +137,20 @@ added: v0.0.1 [`setTimeout`] is described in the [timers][] section. -[`__dirname`]: #globals_dirname -[`__filename`]: #globals_filename +[`__dirname`]: modules.html#modules_dirname +[`__filename`]: modules.html#modules_filename [`clearImmediate`]: timers.html#timers_clearimmediate_immediate [`clearInterval`]: timers.html#timers_clearinterval_timeout [`clearTimeout`]: timers.html#timers_cleartimeout_timeout [`console`]: console.html -[`path.dirname()`]: path.html#path_path_dirname_path +[`exports`]: modules.html#modules_exports +[`module`]: modules.html#modules_module [`process` object]: process.html#process_process +[`require()`]: modules.html#modules_require [`setImmediate`]: timers.html#timers_setimmediate_callback_args [`setInterval`]: timers.html#timers_setinterval_callback_delay_args [`setTimeout`]: timers.html#timers_settimeout_callback_delay_args -[Modules]: modules.html#modules_modules [buffer section]: buffer.html [built-in objects]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects [module system documentation]: modules.html -[native addons]: addons.html [timers]: timers.html |