org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/npm-package-arg/README.md

   1 # npm-package-arg
   2
   3 Parse package name and specifier passed to commands like `npm install` or
   4 `npm cache add`.  This just parses the text given-- it's worth noting that
   5 `npm` has further logic it applies by looking at your disk to figure out
   6 what ambiguous specifiers are.  If you want that logic, please see
   7 [realize-package-specifier].
   8
   9 [realize-package-specifier]: https://www.npmjs.org/package/realize-package-specifier
  10
  11 Arguments look like: `foo@1.2`, `@bar/foo@1.2`, `foo@user/foo`, `http://x.com/foo.tgz`,
  12 `git+https://github.com/user/foo`, `bitbucket:user/foo`, `foo.tar.gz` or `bar`
  13
  14 ## EXAMPLES
  15
  16 ```javascript
  17 var assert = require("assert")
  18 var npa = require("npm-package-arg")
  19
  20 // Pass in the descriptor, and it'll return an object
  21 var parsed = npa("@bar/foo@1.2")
  22
  23 // Returns an object like:
  24 {
  25   raw: '@bar/foo@1.2',   // what was passed in
  26   name: "@bar/foo",      // the name of the package
  27   scope: "@bar",         // the private scope of the package, or null
  28   type: "range",         // the type of specifier this is
  29   spec: ">=1.2.0 <1.3.0" // the expanded specifier
  30   rawSpec: "1.2"         // the specifier as passed in
  31  }
  32
  33 // Parsing urls pointing at hosted git services produces a variation:
  34 var parsed = npa("git+https://github.com/user/foo")
  35
  36 // Returns an object like:
  37 {
  38   raw: 'git+https://github.com/user/foo',
  39   scope: null,
  40   name: null,
  41   rawSpec: 'git+https://github.com/user/foo',
  42   spec: 'user/foo',
  43   type: 'hosted',
  44   hosted: {
  45     type: 'github',
  46     ssh: 'git@github.com:user/foo.git',
  47     sshurl: 'git+ssh://git@github.com/user/foo.git',
  48     https: 'https://github.com/user/foo.git',
  49     directUrl: 'https://raw.githubusercontent.com/user/foo/master/package.json'
  50   }
  51 }
  52
  53 // Completely unreasonable invalid garbage throws an error
  54 // Make sure you wrap this in a try/catch if you have not
  55 // already sanitized the inputs!
  56 assert.throws(function() {
  57   npa("this is not \0 a valid package name or url")
  58 })
  59 ```
  60
  61 ## USING
  62
  63 `var npa = require('npm-package-arg')`
  64
  65 * var result = npa(*arg*)
  66
  67 Parses *arg* and returns a result object detailing what *arg* is.
  68
  69 *arg* -- a package descriptor, like: `foo@1.2`, or `foo@user/foo`, or
  70 `http://x.com/foo.tgz`, or `git+https://github.com/user/foo`
  71
  72 ## RESULT OBJECT
  73
  74 The objects that are returned by npm-package-arg contain the following
  75 keys:
  76
  77 * `name` - If known, the `name` field expected in the resulting pkg.
  78 * `type` - One of the following strings:
  79   * `git` - A git repo
  80   * `hosted` - A hosted project, from github, bitbucket or gitlab. Originally
  81     either a full url pointing at one of these services or a shorthand like
  82     `user/project` or `github:user/project` for github or `bitbucket:user/project`
  83     for bitbucket.
  84   * `tag` - A tagged version, like `"foo@latest"`
  85   * `version` - A specific version number, like `"foo@1.2.3"`
  86   * `range` - A version range, like `"foo@2.x"`
  87   * `local` - A local file or folder path
  88   * `remote` - An http url (presumably to a tgz)
  89 * `spec` - The "thing".  URL, the range, git repo, etc.
  90 * `hosted` - If type=hosted this will be an object with the following keys:
  91   * `type` - github, bitbucket or gitlab
  92   * `ssh` - The ssh path for this git repo
  93   * `sshUrl` - The ssh URL for this git repo
  94   * `httpsUrl` - The HTTPS URL for this git repo
  95   * `directUrl` - The URL for the package.json in this git repo
  96 * `raw` - The original un-modified string that was provided.
  97 * `rawSpec` - The part after the `name@...`, as it was originally
  98   provided.
  99 * `scope` - If a name is something like `@org/module` then the `scope`
 100   field will be set to `org`.  If it doesn't have a scoped name, then
 101   scope is `null`.
 102
 103 If you only include a name and no specifier part, eg, `foo` or `foo@` then
 104 a default of `latest` will be used (as of 4.1.0). This is contrast with
 105 previous behavior where `*` was used.