|
|
- # url-parse
-
- [](http://unshift.io)[](https://www.npmjs.com/package/url-parse)[](https://travis-ci.org/unshiftio/url-parse)[](https://david-dm.org/unshiftio/url-parse)[](https://coveralls.io/r/unshiftio/url-parse?branch=master)[](https://webchat.freenode.net/?channels=unshift)
-
- [](https://saucelabs.com/u/url-parse)
-
- 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.
- - `hostname`: Host name without port number.
- - `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)
|
