diff options
Diffstat (limited to 'deps/npm/node_modules/npm-package-arg/README.md')
-rw-r--r-- | deps/npm/node_modules/npm-package-arg/README.md | 117 |
1 files changed, 44 insertions, 73 deletions
diff --git a/deps/npm/node_modules/npm-package-arg/README.md b/deps/npm/node_modules/npm-package-arg/README.md index 9f4aee1c05..d45032dc74 100644 --- a/deps/npm/node_modules/npm-package-arg/README.md +++ b/deps/npm/node_modules/npm-package-arg/README.md @@ -1,15 +1,7 @@ # npm-package-arg -Parse package name and specifier passed to commands like `npm install` or -`npm cache add`. This just parses the text given-- it's worth noting that -`npm` has further logic it applies by looking at your disk to figure out -what ambiguous specifiers are. If you want that logic, please see -[realize-package-specifier]. - -[realize-package-specifier]: https://www.npmjs.org/package/realize-package-specifier - -Arguments look like: `foo@1.2`, `@bar/foo@1.2`, `foo@user/foo`, `http://x.com/foo.tgz`, -`git+https://github.com/user/foo`, `bitbucket:user/foo`, `foo.tar.gz` or `bar` +Parses package name and specifier passed to commands like `npm install` or +`npm cache add`, or as found in `package.json` dependency sections. ## EXAMPLES @@ -18,93 +10,72 @@ var assert = require("assert") var npa = require("npm-package-arg") // Pass in the descriptor, and it'll return an object -var parsed = npa("@bar/foo@1.2") - -// Returns an object like: -{ - raw: '@bar/foo@1.2', // what was passed in - name: '@bar/foo', // the name of the package - escapedName: '@bar%2ffoo', // the escaped name, for making requests against a registry - scope: '@bar', // the scope of the package, or null - type: 'range', // the type of specifier this is - spec: '>=1.2.0 <1.3.0', // the expanded specifier - rawSpec: '1.2' // the specifier as passed in - } - -// Parsing urls pointing at hosted git services produces a variation: -var parsed = npa("git+https://github.com/user/foo") - -// Returns an object like: -{ - raw: 'git+https://github.com/user/foo', - scope: null, - name: null, - escapedName: null, - rawSpec: 'git+https://github.com/user/foo', - spec: 'user/foo', - type: 'hosted', - hosted: { - type: 'github', - ssh: 'git@github.com:user/foo.git', - sshurl: 'git+ssh://git@github.com/user/foo.git', - https: 'https://github.com/user/foo.git', - directUrl: 'https://raw.githubusercontent.com/user/foo/master/package.json' - } +try { + var parsed = npa("@bar/foo@1.2") +} catch (ex) { + … } - -// Completely unreasonable invalid garbage throws an error -// Make sure you wrap this in a try/catch if you have not -// already sanitized the inputs! -assert.throws(function() { - npa("this is not \0 a valid package name or url") -}) ``` ## USING `var npa = require('npm-package-arg')` -* var result = npa(*arg*) +### var result = npa(*arg*[, *where*]) -Parses *arg* and returns a result object detailing what *arg* is. +* *arg* - a string that you might pass to `npm install`, like: +`foo@1.2`, `@bar/foo@1.2`, `foo@user/foo`, `http://x.com/foo.tgz`, +`git+https://github.com/user/foo`, `bitbucket:user/foo`, `foo.tar.gz`, +`../foo/bar/` or `bar`. If the *arg* you provide doesn't have a specifier +part, eg `foo` then the specifier will default to `latest`. +* *where* - Optionally the path to resolve file paths relative to. Defaults to `process.cwd()` -*arg* -- a package descriptor, like: `foo@1.2`, or `foo@user/foo`, or -`http://x.com/foo.tgz`, or `git+https://github.com/user/foo` +**Throws** if the package name is invalid, a dist-tag is invalid or a URL's protocol is not supported. + +### var result = npa.resolve(*name*, *spec*[, *where*]) + +* *name* - The name of the module you want to install. For example: `foo` or `@bar/foo`. +* *spec* - The specifier indicating where and how you can get this module. Something like: +`1.2`, `^1.7.17`, `http://x.com/foo.tgz`, `git+https://github.com/user/foo`, +`bitbucket:user/foo`, `file:foo.tar.gz` or `file:../foo/bar/`. If not +included then the default is `latest`. +* *where* - Optionally the path to resolve file paths relative to. Defaults to `process.cwd()` + +**Throws** if the package name is invalid, a dist-tag is invalid or a URL's protocol is not supported. ## RESULT OBJECT The objects that are returned by npm-package-arg contain the following keys: -* `name` - If known, the `name` field expected in the resulting pkg. * `type` - One of the following strings: * `git` - A git repo - * `hosted` - A hosted project, from github, bitbucket or gitlab. Originally - either a full url pointing at one of these services or a shorthand like - `user/project` or `github:user/project` for github or `bitbucket:user/project` - for bitbucket. * `tag` - A tagged version, like `"foo@latest"` * `version` - A specific version number, like `"foo@1.2.3"` * `range` - A version range, like `"foo@2.x"` - * `local` - A local file or folder path + * `file` - A local `.tar.gz`, `.tar` or `.tgz` file. + * `directory` - A local directory. * `remote` - An http url (presumably to a tgz) -* `spec` - The "thing". URL, the range, git repo, etc. -* `hosted` - If type=hosted this will be an object with the following keys: - * `type` - github, bitbucket or gitlab - * `ssh` - The ssh path for this git repo - * `sshUrl` - The ssh URL for this git repo - * `httpsUrl` - The HTTPS URL for this git repo - * `directUrl` - The URL for the package.json in this git repo -* `raw` - The original un-modified string that was provided. -* `rawSpec` - The part after the `name@...`, as it was originally - provided. +* `registry` - If true this specifier refers to a resource hosted on a + registry. This is true for `tag`, `version` and `range` types. +* `name` - If known, the `name` field expected in the resulting pkg. * `scope` - If a name is something like `@org/module` then the `scope` field will be set to `@org`. If it doesn't have a scoped name, then scope is `null`. * `escapedName` - A version of `name` escaped to match the npm scoped packages specification. Mostly used when making requests against a registry. When `name` is `null`, `escapedName` will also be `null`. - -If you only include a name and no specifier part, eg, `foo` or `foo@` then -a default of `latest` will be used (as of 4.1.0). This is contrast with -previous behavior where `*` was used. +* `rawSpec` - The specifier part that was parsed out in calls to `npa(arg)`, + or the value of `spec` in calls to `npa.resolve(name, spec). +* `saveSpec` - The normalized specifier, for saving to package.json files. + `null` for registry dependencies. +* `fetchSpec` - The version of the specifier to be used to fetch this + resource. `null` for shortcuts to hosted git dependencies as there isn't + just one URL to try with them. +* `gitRange` - If set, this is a semver specifier to match against git tags with +* `gitCommittish` - If set, this is the specific committish to use with a git dependency. +* `hosted` - If `from === 'hosted'` then this will be a `hosted-git-info` + object. This property is not included when serializing the object as + JSON. +* `raw` - The original un-modified string that was provided. If called as + `npa.resolve(name, spec)` then this will be `name + '@' + spec`. |