diff options
| -rw-r--r-- | doc/api/bin.md | 13 | ||||
| -rw-r--r-- | doc/api/commands.md | 54 | ||||
| -rw-r--r-- | doc/api/config.md | 51 | ||||
| -rw-r--r-- | doc/api/deprecate.md | 18 | ||||
| -rw-r--r-- | doc/api/npm.md | 105 | ||||
| -rw-r--r-- | doc/cli/npm.md | 1 | ||||
| -rwxr-xr-x | scripts/doc-build.sh | 1 |
7 files changed, 159 insertions, 84 deletions
diff --git a/doc/api/bin.md b/doc/api/bin.md index 78d147d80..e04b2f6cb 100644 --- a/doc/api/bin.md +++ b/doc/api/bin.md @@ -3,13 +3,18 @@ npm-bin(3) -- Display npm bin folder ## SYNOPSIS - npm.commands.bin(args, callback) + npm.commands.bin(args, cb) ## DESCRIPTION Print the folder where npm will install executables. -'args' is never used and callback is never called with data. -'args' must be present or things will break. +This function should not be used programmatically. The logic for +attaining the bin folder is quite simple. -This function is not useful programmatically. + var bin + if (npm.config.get("global")) { + bin = path.resolve(npm.prefix, "bin") + } else { + bin = path.resolve(npm.dir, ".bin") + } diff --git a/doc/api/commands.md b/doc/api/commands.md index 8f1115506..eb7545639 100644 --- a/doc/api/commands.md +++ b/doc/api/commands.md @@ -3,7 +3,7 @@ npm-commands(3) -- npm commands ## SYNOPSIS - npm.commands.<command>(args, callback) + npm.commands[<command>](args, callback) ## DESCRIPTION @@ -17,54 +17,6 @@ commands are special and take other optional arguments. All commands have their own man page. See `man npm-<command>` for command-line usage, or `man 3 npm-<command>` for programmatic usage. -## COMMANDS - -### install - -Install a package. - -* "install" -* "uninstall" - "cache" -* "config" -* "set" -* "get" -* "update" -* "outdated" -* "prune" -* "submodule" -* "pack" - -* "rebuild" -* "link" - -* "publish" -* "tag" - "adduser" -* "unpublish" -* "owner" -* "deprecate" - - "help" -* "help-search" -* "ls" -* "search" -* "view" -* "init" -* "version" -* "edit" -* "explore" -* "docs" - "faq" -* "root" -* "prefix" -* "bin" -* "whoami" - -* "test" -* "stop" -* "start" -* "restart" -* "run-script" - "completion" +## SEE ALSO +* npm-index(1) diff --git a/doc/api/config.md b/doc/api/config.md index c4218a845..7ae227428 100644 --- a/doc/api/config.md +++ b/doc/api/config.md @@ -1,26 +1,45 @@ -npm-config(3) -- Manage the npm configuration file -================================================== +npm-config(3) -- Manage the npm configuration files +=================================================== ## SYNOPSIS npm.commands.config(args, callback) + var val = npm.config.get(key) + npm.config.set(key, val) ## DESCRIPTION This function acts much the same way as the command-line version. The first element in the array tells config what to do. Possible values are: -* 'set': - Sets a config parameter. The second element in 'args' is interpreted as the - key, and the third element is interpreted as the value. -* 'get': - Gets the value of a config parameter. The second element in 'args' is the - key to get the value of. -* 'delete' ('rm' or 'del'): - Deletes a parameter from the config. The second element in 'args' is the - key to delete. -* 'list' ('ls'): - Show all configs that aren't secret. No parameters necessary. -* 'edit': - Opens the config file in the default editor. This command isn't very useful - programmatically, but it is made available. +* `set` + + Sets a config parameter. The second element in `args` is interpreted as the + key, and the third element is interpreted as the value. + +* `get` + + Gets the value of a config parameter. The second element in `args` is the + key to get the value of. + +* `delete` (`rm` or `del`) + + Deletes a parameter from the config. The second element in `args` is the + key to delete. + +* `list` (`ls`) + + Show all configs that aren't secret. No parameters necessary. + +* `edit`: + + Opens the config file in the default editor. This command isn't very useful + programmatically, but it is made available. + +To programmatically access npm configuration settings, or set them for +the duration of a program, use the `npm.config.set` and `npm.config.get` +functions instead. + +## SEE ALSO + +* npm(3) diff --git a/doc/api/deprecate.md b/doc/api/deprecate.md index 273e1452c..ac94fd7a9 100644 --- a/doc/api/deprecate.md +++ b/doc/api/deprecate.md @@ -12,9 +12,21 @@ a deprecation warning to all who attempt to install it. The 'args' parameter must have exactly two elements: -* package@version: - To specify a range, wrap the version in quotes (e.g. pkg@"< 1.2") -* message +* `package[@version]` + + The `version` portion is optional, and may be either a range, or a + specific version, or a tag. + +* `message` + + The warning message that will be printed whenever a user attempts to + install the package. Note that you must be the package owner to deprecate something. See the `owner` and `adduser` help topics. + +## SEE ALSO + +* npm-publish(3) +* npm-unpublish(3) +* npm-registry(1) diff --git a/doc/api/npm.md b/doc/api/npm.md index 22045fab4..a2f034c4b 100644 --- a/doc/api/npm.md +++ b/doc/api/npm.md @@ -6,25 +6,110 @@ npm(3) -- node package manager var npm = require("npm") npm.load(configObject, function (er, npm) { // use the npm object, now that it's loaded. + + npm.config.set(key, val) + val = npm.config.get(key) + + console.log("prefix = %s", npm.prefix) + + npm.commands.install(["package"], cb) }) +## VERSION + +@VERSION@ + ## DESCRIPTION -Since you're looking at this man page, you are probably wanting to integrate -npm into your program. To find documentation of the npm command line -client, then use `npm help npm` or `man npm`. +This is the API documentation for npm. +To find documentation of the command line +client, see `npm(1)`. + +Prior to using npm's commands, +`npm.load()` must be called with an object hash of +top-level configs. In the npm command line client, +this set of configs is parsed from the command line options. Additional +configuration params are loaded from two configuration files. See +`npm-config(1)` for more information. -Every time you use npm, you must call `npm.load()` with an object hash of -command-line configs. After that, each of the functions are accessible in the -commands object: `npm.commands.<cmd>` Check out `npm help config` or -for all available options. +After that, each of the functions are accessible in the +commands object: `npm.commands.<cmd>`. See `npm-index(1)` for a list of +all possible commands. All commands on the command object take an **array** of positional argument -**strings**. The last argument to any function is a callback. Some commands are -special and take other optional arguments. +**strings**. The last argument to any function is a callback. Some +commands take other optional arguments. Configs cannot currently be set on a per function basis, as each call to npm.config.set will change the value for *all* npm commands in that process. -To find API documentation for a specific command, try the man pages first. +To find API documentation for a specific command, run the `npm apihelp` +command. + +## METHODS AND PROPERTIES + +* `npm.load(configs, cb)` + + Load the configuration params, and call the `cb` function once the + globalconfig and userconfig files have been loaded as well, or on + nextTick if they've already been loaded. + +* `npm.config` + + An object for accessing npm configuration parameters. + + * `npm.config.get(key)` + * `npm.config.set(key, val)` + * `npm.config.del(key)` + +* `npm.dir` or `npm.root` + + The `node_modules` directory where npm will operate. + +* `npm.prefix` + + The prefix where npm is operating. (Most often the current working + directory.) + +* `npm.cache` + + The place where npm keeps JSON and tarballs it fetches from the + registry (or uploads to the registry). + +* `npm.tmp` + + npm's temporary working directory. + +* `npm.deref` + + Get the "real" name for a command that has either an alias or + abbreviation. + +## MAGIC + +For each of the methods in the `npm.commands` hash, a method is added to +the npm object, which takes a set of positional string arguments rather +than an array and a callback. + +If the last argument is a callback, then it will use the supplied +callback. However, if no callback is provided, then it will print out +the error or results. + +For example, this would work in a node repl: + + > npm = require("npm") + > npm.load() // wait a sec... + > npm.install("dnode", "express") + +Note that that *won't* work in a node program, since the `install` +method will get called before the configuration load is completed. + +## ABBREVS + +In order to support `npm ins foo` instead of `npm install foo`, the +`npm.commands` object has a set of abbreviations as well as the full +method names. Use the `npm.deref` method to find the real name. + +For example: + var cmd = npm.deref("unp") // cmd === "unpublish" diff --git a/doc/cli/npm.md b/doc/cli/npm.md index ac7e5e4c3..cd3360d7c 100644 --- a/doc/cli/npm.md +++ b/doc/cli/npm.md @@ -152,3 +152,4 @@ See npm-changelog(1) * npm-install(1) * npm-config(1) * npm-index(1) +* npm(3) diff --git a/scripts/doc-build.sh b/scripts/doc-build.sh index 9c8fbee64..2376ba05b 100755 --- a/scripts/doc-build.sh +++ b/scripts/doc-build.sh @@ -41,6 +41,7 @@ case $dest in | perl -pi -e 's/([^"-])npm-([^\(]+)\(1\)/\1<a href="..\/doc\/\2.html">\2<\/a>/g' \ | perl -pi -e 's/([^"-])npm-([^\(]+)\(3\)/\1<a href="..\/api\/\2.html">\2<\/a>/g' \ | perl -pi -e 's/([^"-])npm\(1\)/\1<a href="..\/doc\/npm.html">npm<\/a>/g' \ + | perl -pi -e 's/([^"-])npm\(3\)/\1<a href="..\/api\/npm.html">npm<\/a>/g' \ > $dest exit $? ;; |