source: trip-planner-front/node_modules/url-parse/README.md@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 6.1 KB
Line 
1# url-parse
2
3[![Made by unshift](https://img.shields.io/badge/made%20by-unshift-00ffcc.svg?style=flat-square)](http://unshift.io)[![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)[![Dependencies](https://img.shields.io/david/unshiftio/url-parse.svg?style=flat-square)](https://david-dm.org/unshiftio/url-parse)[![Coverage Status](https://img.shields.io/coveralls/unshiftio/url-parse/master.svg?style=flat-square)](https://coveralls.io/r/unshiftio/url-parse?branch=master)[![IRC channel](https://img.shields.io/badge/IRC-irc.freenode.net%23unshift-00a8ff.svg?style=flat-square)](https://webchat.freenode.net/?channels=unshift)
4
5[![Sauce Test Status](https://saucelabs.com/browser-matrix/url-parse.svg)](https://saucelabs.com/u/url-parse)
6
7The `url-parse` method exposes two different API interfaces. The
8[`url`](https://nodejs.org/api/url.html) interface that you know from Node.js
9and the new [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL)
10interface that is available in the latest browsers.
11
12In version `0.1` we moved from a DOM based parsing solution, using the `<a>`
13element, to a full Regular Expression solution. The main reason for this was
14to make the URL parser available in different JavaScript environments as you
15don't always have access to the DOM. An example of such environment is the
16[`Worker`](https://developer.mozilla.org/en/docs/Web/API/Worker) interface.
17The RegExp based solution didn't work well as it required a lot of lookups
18causing major problems in FireFox. In version `1.0.0` we ditched the RegExp
19based solution in favor of a pure string parsing solution which chops up the
20URL into smaller pieces. This module still has a really small footprint as it
21has been designed to be used on the client side.
22
23In addition to URL parsing we also expose the bundled `querystringify` module.
24
25## Installation
26
27This module is designed to be used using either browserify or Node.js it's
28released in the public npm registry and can be installed using:
29
30```
31npm install url-parse
32```
33
34## Usage
35
36All examples assume that this library is bootstrapped using:
37
38```js
39'use strict';
40
41var Url = require('url-parse');
42```
43
44To parse an URL simply call the `URL` method with the URL that needs to be
45transformed into an object.
46
47```js
48var url = new Url('https://github.com/foo/bar');
49```
50
51The `new` keyword is optional but it will save you an extra function invocation.
52The constructor takes the following arguments:
53
54- `url` (`String`): A string representing an absolute or relative URL.
55- `baseURL` (`Object` | `String`): An object or string representing
56 the base URL to use in case `url` is a relative URL. This argument is
57 optional and defaults to [`location`](https://developer.mozilla.org/en-US/docs/Web/API/Location)
58 in the browser.
59- `parser` (`Boolean` | `Function`): This argument is optional and specifies
60 how to parse the query string. By default it is `false` so the query string
61 is not parsed. If you pass `true` the query string is parsed using the
62 embedded `querystringify` module. If you pass a function the query string
63 will be parsed using this function.
64
65As said above we also support the Node.js interface so you can also use the
66library in this way:
67
68```js
69'use strict';
70
71var parse = require('url-parse')
72 , url = parse('https://github.com/foo/bar', true);
73```
74
75The returned `url` instance contains the following properties:
76
77- `protocol`: The protocol scheme of the URL (e.g. `http:`).
78- `slashes`: A boolean which indicates whether the `protocol` is followed by two
79 forward slashes (`//`).
80- `auth`: Authentication information portion (e.g. `username:password`).
81- `username`: Username of basic authentication.
82- `password`: Password of basic authentication.
83- `host`: Host name with port number.
84- `hostname`: Host name without port number.
85- `port`: Optional port number.
86- `pathname`: URL path.
87- `query`: Parsed object containing query string, unless parsing is set to false.
88- `hash`: The "fragment" portion of the URL including the pound-sign (`#`).
89- `href`: The full URL.
90- `origin`: The origin of the URL.
91
92Note that when `url-parse` is used in a browser environment, it will default to
93using the browser's current window location as the base URL when parsing all
94inputs. To parse an input independently of the browser's current URL (e.g. for
95functionality parity with the library in a Node environment), pass an empty
96location object as the second parameter:
97
98```js
99var parse = require('url-parse');
100parse('hostname', {});
101```
102
103### Url.set(key, value)
104
105A simple helper function to change parts of the URL and propagating it through
106all properties. When you set a new `host` you want the same value to be applied
107to `port` if has a different port number, `hostname` so it has a correct name
108again and `href` so you have a complete URL.
109
110```js
111var parsed = parse('http://google.com/parse-things');
112
113parsed.set('hostname', 'yahoo.com');
114console.log(parsed.href); // http://yahoo.com/parse-things
115```
116
117It's aware of default ports so you cannot set a port 80 on an URL which has
118`http` as protocol.
119
120### Url.toString()
121
122The returned `url` object comes with a custom `toString` method which will
123generate a full URL again when called. The method accepts an extra function
124which will stringify the query string for you. If you don't supply a function we
125will use our default method.
126
127```js
128var location = url.toString(); // http://example.com/whatever/?qs=32
129```
130
131You would rarely need to use this method as the full URL is also available as
132`href` property. If you are using the `URL.set` method to make changes, this
133will automatically update.
134
135## Testing
136
137The testing of this module is done in 3 different ways:
138
1391. We have unit tests that run under Node.js. You can run these tests with the
140 `npm test` command.
1412. Code coverage can be run manually using `npm run coverage`.
1423. For browser testing we use Sauce Labs and `zuul`. You can run browser tests
143 using the `npm run test-browser` command.
144
145## License
146
147[MIT](LICENSE)
Note: See TracBrowser for help on using the repository browser.