.config/coc/extensions/node_modules/coc-prettier/node_modules/uri-js/README.md

   1 # URI.js
   2
   3 URI.js is an [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt) compliant, scheme extendable URI parsing/validating/resolving library for all JavaScript environments (browsers, Node.js, etc).
   4 It is also compliant with the IRI ([RFC 3987](http://www.ietf.org/rfc/rfc3987.txt)), IDNA ([RFC 5890](http://www.ietf.org/rfc/rfc5890.txt)), IPv6 Address ([RFC 5952](http://www.ietf.org/rfc/rfc5952.txt)), IPv6 Zone Identifier ([RFC 6874](http://www.ietf.org/rfc/rfc6874.txt)) specifications.
   5
   6 URI.js has an extensive test suite, and works in all (Node.js, web) environments. It weighs in at 6.2kb (gzipped, 16kb deflated).
   7
   8 ## API
   9
  10 ### Parsing
  11
  12         URI.parse("uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body");
  13         //returns:
  14         //{
  15         //  scheme : "uri",
  16         //  userinfo : "user:pass",
  17         //  host : "example.com",
  18         //  port : 123,
  19         //  path : "/one/two.three",
  20         //  query : "q1=a1&q2=a2",
  21         //  fragment : "body"
  22         //}
  23
  24 ### Serializing
  25
  26         URI.serialize({scheme : "http", host : "example.com", fragment : "footer"}) === "http://example.com/#footer"
  27
  28 ### Resolving
  29
  30         URI.resolve("uri://a/b/c/d?q", "../../g") === "uri://a/g"
  31
  32 ### Normalizing
  33
  34         URI.normalize("HTTP://ABC.com:80/%7Esmith/home.html") === "http://abc.com/~smith/home.html"
  35
  36 ### Comparison
  37
  38         URI.equal("example://a/b/c/%7Bfoo%7D", "eXAMPLE://a/./b/../b/%63/%7bfoo%7d") === true
  39
  40 ### IP Support
  41
  42         //IPv4 normalization
  43         URI.normalize("//192.068.001.000") === "//192.68.1.0"
  44
  45         //IPv6 normalization
  46         URI.normalize("//[2001:0:0DB8::0:0001]") === "//[2001:0:db8::1]"
  47
  48         //IPv6 zone identifier support
  49         URI.parse("//[2001:db8::7%25en1]");
  50         //returns:
  51         //{
  52         //  host : "2001:db8::7%en1"
  53         //}
  54
  55 ### IRI Support
  56
  57         //convert IRI to URI
  58         URI.serialize(URI.parse("http://examplé.org/rosé")) === "http://xn--exampl-gva.org/ros%C3%A9"
  59         //convert URI to IRI
  60         URI.serialize(URI.parse("http://xn--exampl-gva.org/ros%C3%A9"), {iri:true}) === "http://examplé.org/rosé"
  61
  62 ### Options
  63
  64 All of the above functions can accept an additional options argument that is an object that can contain one or more of the following properties:
  65
  66 *       `scheme` (string)
  67
  68         Indicates the scheme that the URI should be treated as, overriding the URI's normal scheme parsing behavior.
  69
  70 *       `reference` (string)
  71
  72         If set to `"suffix"`, it indicates that the URI is in the suffix format, and the validator will use the option's `scheme` property to determine the URI's scheme.
  73
  74 *       `tolerant` (boolean, false)
  75
  76         If set to `true`, the parser will relax URI resolving rules.
  77
  78 *       `absolutePath` (boolean, false)
  79
  80         If set to `true`, the serializer will not resolve a relative `path` component.
  81
  82 *       `iri` (boolean, false)
  83
  84         If set to `true`, the serializer will unescape non-ASCII characters as per [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt).
  85
  86 *       `unicodeSupport` (boolean, false)
  87
  88         If set to `true`, the parser will unescape non-ASCII characters in the parsed output as per [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt).
  89
  90 *       `domainHost` (boolean, false)
  91
  92         If set to `true`, the library will treat the `host` component as a domain name, and convert IDNs (International Domain Names) as per [RFC 5891](http://www.ietf.org/rfc/rfc5891.txt).
  93
  94 ## Scheme Extendable
  95
  96 URI.js supports inserting custom [scheme](http://en.wikipedia.org/wiki/URI_scheme) dependent processing rules. Currently, URI.js has built in support for the following schemes:
  97
  98 *       http \[[RFC 2616](http://www.ietf.org/rfc/rfc2616.txt)\]
  99 *       https \[[RFC 2818](http://www.ietf.org/rfc/rfc2818.txt)\]
 100 *       mailto \[[RFC 6068](http://www.ietf.org/rfc/rfc6068.txt)\]
 101 *       urn \[[RFC 2141](http://www.ietf.org/rfc/rfc2141.txt)\]
 102 *       urn:uuid \[[RFC 4122](http://www.ietf.org/rfc/rfc4122.txt)\]
 103
 104 ### HTTP Support
 105
 106         URI.equal("HTTP://ABC.COM:80", "http://abc.com/") === true
 107
 108 ### Mailto Support
 109
 110         URI.parse("mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&body=Sign%20me%20up!");
 111         //returns:
 112         //{
 113         //      scheme : "mailto",
 114         //      to : ["alpha@example.com", "bravo@example.com"],
 115         //      subject : "SUBSCRIBE",
 116         //      body : "Sign me up!"
 117         //}
 118
 119         URI.serialize({
 120                 scheme : "mailto",
 121                 to : ["alpha@example.com"],
 122                 subject : "REMOVE",
 123                 body : "Please remove me",
 124                 headers : {
 125                         cc : "charlie@example.com"
 126                 }
 127         }) === "mailto:alpha@example.com?cc=charlie@example.com&subject=REMOVE&body=Please%20remove%20me"
 128
 129 ### URN Support
 130
 131         URI.parse("urn:example:foo");
 132         //returns:
 133         //{
 134         //      scheme : "urn",
 135         //      nid : "example",
 136         //      nss : "foo",
 137         //}
 138
 139 #### URN UUID Support
 140
 141         URI.parse("urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6");
 142         //returns:
 143         //{
 144         //      scheme : "urn",
 145         //      nid : "example",
 146         //      uuid : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
 147         //}
 148
 149 ## Usage
 150
 151 To load in a browser, use the following tag:
 152
 153         <script type="text/javascript" src="uri-js/dist/es5/uri.all.min.js"></script>
 154
 155 To load in a CommonJS (Node.js) environment, first install with npm by running on the command line:
 156
 157         npm install uri-js
 158
 159 Then, in your code, load it using:
 160
 161         const URI = require("uri-js");
 162
 163 If you are writing your code in ES6+ (ESNEXT) or TypeScript, you would load it using:
 164
 165         import * as URI from "uri-js";
 166
 167 Or you can load just what you need using named exports:
 168
 169         import { parse, serialize, resolve, resolveComponents, normalize, equal, removeDotSegments, pctEncChar, pctDecChars, escapeComponent, unescapeComponent } from "uri-js";
 170
 171 ## Breaking changes
 172
 173 ### Breaking changes from 3.x
 174
 175 URN parsing has been completely changed to better align with the specification. Scheme is now always `urn`, but has two new properties: `nid` which contains the Namspace Identifier, and `nss` which contains the Namespace Specific String. The `nss` property will be removed by higher order scheme handlers, such as the UUID URN scheme handler.
 176
 177 The UUID of a URN can now be found in the `uuid` property.
 178
 179 ### Breaking changes from 2.x
 180
 181 URI validation has been removed as it was slow, exposed a vulnerabilty, and was generally not useful.
 182
 183 ### Breaking changes from 1.x
 184
 185 The `errors` array on parsed components is now an `error` string.
 186
 187 ## License ([Simplified BSD](http://en.wikipedia.org/wiki/BSD_licenses#2-clause))
 188
 189 Copyright 2011 Gary Court. All rights reserved.
 190
 191 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 192
 193 1.      Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 194
 195 2.      Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 196
 197 THIS SOFTWARE IS PROVIDED BY GARY COURT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GARY COURT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 198
 199 The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Gary Court.