diff options
Diffstat (limited to 'alarm/node_modules/url-parse/README.md')
| -rw-r--r-- | alarm/node_modules/url-parse/README.md | 153 |
1 files changed, 0 insertions, 153 deletions
diff --git a/alarm/node_modules/url-parse/README.md b/alarm/node_modules/url-parse/README.md deleted file mode 100644 index e5bf8d7..0000000 --- a/alarm/node_modules/url-parse/README.md +++ /dev/null @@ -1,153 +0,0 @@ -# url-parse - -[](https://www.npmjs.com/package/url-parse)[](https://github.com/unshiftio/url-parse/actions?query=workflow%3ACI+branch%3Amaster)[](https://coveralls.io/r/unshiftio/url-parse?branch=master) - -[](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) |