summaryrefslogtreecommitdiff
path: root/alarm/node_modules/url-parse/README.md
diff options
context:
space:
mode:
authorMinteck <contact@minteck.org>2022-10-18 08:59:09 +0200
committerMinteck <contact@minteck.org>2022-10-18 08:59:09 +0200
commit2c4ae43e688a9873e86211ea0e7aeb9ba770dd77 (patch)
tree17848d95522dab25d3cdeb9c4a6450e2a234861f /alarm/node_modules/url-parse/README.md
parent108525534c28013cfe1897c30e4565f9893f3766 (diff)
downloadpluralconnect-2c4ae43e688a9873e86211ea0e7aeb9ba770dd77.tar.gz
pluralconnect-2c4ae43e688a9873e86211ea0e7aeb9ba770dd77.tar.bz2
pluralconnect-2c4ae43e688a9873e86211ea0e7aeb9ba770dd77.zip
Update
Diffstat (limited to 'alarm/node_modules/url-parse/README.md')
-rw-r--r--alarm/node_modules/url-parse/README.md153
1 files changed, 153 insertions, 0 deletions
diff --git a/alarm/node_modules/url-parse/README.md b/alarm/node_modules/url-parse/README.md
new file mode 100644
index 0000000..e5bf8d7
--- /dev/null
+++ b/alarm/node_modules/url-parse/README.md
@@ -0,0 +1,153 @@
+# url-parse
+
+[![Version npm](https://img.shields.io/npm/v/url-parse.svg?style=flat-square)](https://www.npmjs.com/package/url-parse)[![Build Status](https://img.shields.io/github/workflow/status/unshiftio/url-parse/CI/master?label=CI&style=flat-square)](https://github.com/unshiftio/url-parse/actions?query=workflow%3ACI+branch%3Amaster)[![Coverage Status](https://img.shields.io/coveralls/unshiftio/url-parse/master.svg?style=flat-square)](https://coveralls.io/r/unshiftio/url-parse?branch=master)
+
+[![Sauce Test Status](https://saucelabs.com/browser-matrix/url-parse.svg)](https://saucelabs.com/u/url-parse)
+
+**`url-parse` was created in 2014 when the WHATWG URL API was not available in
+Node.js and the `URL` interface was supported only in some browsers. Today this
+is no longer true. The `URL` interface is available in all supported Node.js
+release lines and basically all browsers. Consider using it for better security
+and accuracy.**
+
+The `url-parse` method exposes two different API interfaces. The
+[`url`](https://nodejs.org/api/url.html) interface that you know from Node.js
+and the new [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL)
+interface that is available in the latest browsers.
+
+In version `0.1` we moved from a DOM based parsing solution, using the `<a>`
+element, to a full Regular Expression solution. The main reason for this was
+to make the URL parser available in different JavaScript environments as you
+don't always have access to the DOM. An example of such environment is the
+[`Worker`](https://developer.mozilla.org/en/docs/Web/API/Worker) interface.
+The RegExp based solution didn't work well as it required a lot of lookups
+causing major problems in FireFox. In version `1.0.0` we ditched the RegExp
+based solution in favor of a pure string parsing solution which chops up the
+URL into smaller pieces. This module still has a really small footprint as it
+has been designed to be used on the client side.
+
+In addition to URL parsing we also expose the bundled `querystringify` module.
+
+## Installation
+
+This module is designed to be used using either browserify or Node.js it's
+released in the public npm registry and can be installed using:
+
+```
+npm install url-parse
+```
+
+## Usage
+
+All examples assume that this library is bootstrapped using:
+
+```js
+'use strict';
+
+var Url = require('url-parse');
+```
+
+To parse an URL simply call the `URL` method with the URL that needs to be
+transformed into an object.
+
+```js
+var url = new Url('https://github.com/foo/bar');
+```
+
+The `new` keyword is optional but it will save you an extra function invocation.
+The constructor takes the following arguments:
+
+- `url` (`String`): A string representing an absolute or relative URL.
+- `baseURL` (`Object` | `String`): An object or string representing
+ the base URL to use in case `url` is a relative URL. This argument is
+ optional and defaults to [`location`](https://developer.mozilla.org/en-US/docs/Web/API/Location)
+ in the browser.
+- `parser` (`Boolean` | `Function`): This argument is optional and specifies
+ how to parse the query string. By default it is `false` so the query string
+ is not parsed. If you pass `true` the query string is parsed using the
+ embedded `querystringify` module. If you pass a function the query string
+ will be parsed using this function.
+
+As said above we also support the Node.js interface so you can also use the
+library in this way:
+
+```js
+'use strict';
+
+var parse = require('url-parse')
+ , url = parse('https://github.com/foo/bar', true);
+```
+
+The returned `url` instance contains the following properties:
+
+- `protocol`: The protocol scheme of the URL (e.g. `http:`).
+- `slashes`: A boolean which indicates whether the `protocol` is followed by two
+ forward slashes (`//`).
+- `auth`: Authentication information portion (e.g. `username:password`).
+- `username`: Username of basic authentication.
+- `password`: Password of basic authentication.
+- `host`: Host name with port number. The hostname might be invalid.
+- `hostname`: Host name without port number. This might be an invalid hostname.
+- `port`: Optional port number.
+- `pathname`: URL path.
+- `query`: Parsed object containing query string, unless parsing is set to false.
+- `hash`: The "fragment" portion of the URL including the pound-sign (`#`).
+- `href`: The full URL.
+- `origin`: The origin of the URL.
+
+Note that when `url-parse` is used in a browser environment, it will default to
+using the browser's current window location as the base URL when parsing all
+inputs. To parse an input independently of the browser's current URL (e.g. for
+functionality parity with the library in a Node environment), pass an empty
+location object as the second parameter:
+
+```js
+var parse = require('url-parse');
+parse('hostname', {});
+```
+
+### Url.set(key, value)
+
+A simple helper function to change parts of the URL and propagating it through
+all properties. When you set a new `host` you want the same value to be applied
+to `port` if has a different port number, `hostname` so it has a correct name
+again and `href` so you have a complete URL.
+
+```js
+var parsed = parse('http://google.com/parse-things');
+
+parsed.set('hostname', 'yahoo.com');
+console.log(parsed.href); // http://yahoo.com/parse-things
+```
+
+It's aware of default ports so you cannot set a port 80 on an URL which has
+`http` as protocol.
+
+### Url.toString()
+
+The returned `url` object comes with a custom `toString` method which will
+generate a full URL again when called. The method accepts an extra function
+which will stringify the query string for you. If you don't supply a function we
+will use our default method.
+
+```js
+var location = url.toString(); // http://example.com/whatever/?qs=32
+```
+
+You would rarely need to use this method as the full URL is also available as
+`href` property. If you are using the `URL.set` method to make changes, this
+will automatically update.
+
+## Testing
+
+The testing of this module is done in 3 different ways:
+
+1. We have unit tests that run under Node.js. You can run these tests with the
+ `npm test` command.
+2. Code coverage can be run manually using `npm run coverage`.
+3. For browser testing we use Sauce Labs and `zuul`. You can run browser tests
+ using the `npm run test-browser` command.
+
+## License
+
+[MIT](LICENSE)