diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 000000000..106d3b725 --- /dev/null +++ b/README.md @@ -0,0 +1,244 @@ +# URI.js # + +* [About](http://medialize.github.io/URI.js/) +* [Understanding URIs](http://medialize.github.io/URI.js/about-uris.html) +* [Documentation](http://medialize.github.io/URI.js/docs.html) +* [jQuery URI Plugin](http://medialize.github.io/URI.js/jquery-uri-plugin.html) +* [Author](http://rodneyrehm.de/en/) +* [Changelog](./CHANGELOG.md) + +--- + +> **NOTE:** The npm package name changed to `urijs` + +--- + +I always want to shoot myself in the head when looking at code like the following: + +```javascript +var url = "http://example.org/foo?bar=baz"; +var separator = url.indexOf('?') > -1 ? '&' : '?'; + +url += separator + encodeURIComponent("foo") + "=" + encodeURIComponent("bar"); +``` + +Things are looking up with [URL](https://developer.mozilla.org/en/docs/Web/API/URL) and the [URL spec](http://url.spec.whatwg.org/) but until we can safely rely on that API, have a look at URI.js for a clean and simple API for mutating URIs: + +```javascript +var url = new URI("http://example.org/foo?bar=baz"); +url.addQuery("foo", "bar"); +``` + +URI.js is here to help with that. + + +## API Example ## + +```javascript +// mutating URLs +URI("http://example.org/foo.html?hello=world") + .username("rodneyrehm") + // -> http://rodneyrehm@example.org/foo.html?hello=world + .username("") + // -> http://example.org/foo.html?hello=world + .directory("bar") + // -> http://example.org/bar/foo.html?hello=world + .suffix("xml") + // -> http://example.org/bar/foo.xml?hello=world + .query("") + // -> http://example.org/bar/foo.xml + .tld("com") + // -> http://example.com/bar/foo.xml + .query({ foo: "bar", hello: ["world", "mars"] }); + // -> http://example.com/bar/foo.xml?foo=bar&hello=world&hello=mars + +// cleaning things up +URI("?&foo=bar&&foo=bar&foo=baz&") + .normalizeQuery(); + // -> ?foo=bar&foo=baz + +// working with relative paths +URI("/foo/bar/baz.html") + .relativeTo("/foo/bar/world.html"); + // -> ./baz.html + +URI("/foo/bar/baz.html") + .relativeTo("/foo/bar/sub/world.html") + // -> ../baz.html + .absoluteTo("/foo/bar/sub/world.html"); + // -> /foo/bar/baz.html + +// URI Templates +URI.expand("/foo/{dir}/{file}", { + dir: "bar", + file: "world.html" +}); +// -> /foo/bar/world.html +``` + +See the [About Page](http://medialize.github.io/URI.js/) and [API Docs](http://medialize.github.io/URI.js/docs.html) for more stuff. + +## Using URI.js ## + +URI.js (without plugins) has a gzipped weight of about 7KB - if you include all extensions you end up at about 13KB. So unless you *need* second level domain support and use URI templates, we suggest you don't include them in your build. If you don't need a full featured URI mangler, it may be worth looking into the much smaller parser-only alternatives [listed below](#alternatives). + +URI.js is available through [npm](https://www.npmjs.com/package/urijs), [bower](http://bower.io/search/?q=urijs), [bowercdn](http://bowercdn.net/package/urijs), [cdnjs](https://cdnjs.com/libraries/URI.js) and manually from the [build page](http://medialize.github.io/URI.js/build.html): + +```bash +# using bower +bower install uri.js + +# using npm +npm install urijs +``` + +### Browser ### + +I guess you'll manage to use the [build tool](http://medialize.github.io/URI.js/build.html) or follow the [instructions below](#minify) to combine and minify the various files into URI.min.js - and I'm fairly certain you know how to `<script src=".../URI.min.js"></script>` that sucker, too. + +### Node.js and NPM ### + +Install with `npm install urijs` or add `"urijs"` to the dependencies in your `package.json`. + +```javascript +// load URI.js +var URI = require('urijs'); +// load an optional module (e.g. URITemplate) +var URITemplate = require('urijs/src/URITemplate'); + +URI("/foo/bar/baz.html") + .relativeTo("/foo/bar/sub/world.html") + // -> ../baz.html +``` + +### RequireJS ### + +Clone the URI.js repository or use a package manager to get URI.js into your project. + +```javascript +require.config({ + paths: { + urijs: 'where-you-put-uri.js/src' + } +}); + +require(['urijs/URI'], function(URI) { + console.log("URI.js and dependencies: ", URI("//amazon.co.uk").is('sld') ? 'loaded' : 'failed'); +}); +require(['urijs/URITemplate'], function(URITemplate) { + console.log("URITemplate.js and dependencies: ", URITemplate._cache ? 'loaded' : 'failed'); +}); +``` + +## Minify ## + +See the [build tool](http://medialize.github.io/URI.js/build.html) or use [Google Closure Compiler](http://closure-compiler.appspot.com/home): + +``` +// ==ClosureCompiler== +// @compilation_level SIMPLE_OPTIMIZATIONS +// @output_file_name URI.min.js +// @code_url http://medialize.github.io/URI.js/src/IPv6.js +// @code_url http://medialize.github.io/URI.js/src/punycode.js +// @code_url http://medialize.github.io/URI.js/src/SecondLevelDomains.js +// @code_url http://medialize.github.io/URI.js/src/URI.js +// @code_url http://medialize.github.io/URI.js/src/URITemplate.js +// ==/ClosureCompiler== +``` + + +## Resources ## + +Documents specifying how URLs work: + +* [URL - Living Standard](http://url.spec.whatwg.org/) +* [RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax](http://tools.ietf.org/html/rfc3986) +* [RFC 3987 - Internationalized Resource Identifiers (IRI)](http://tools.ietf.org/html/rfc3987) +* [RFC 2732 - Format for Literal IPv6 Addresses in URL's](http://tools.ietf.org/html/rfc2732) +* [RFC 2368 - The `mailto:` URL Scheme](https://www.ietf.org/rfc/rfc2368.txt) +* [RFC 2141 - URN Syntax](https://www.ietf.org/rfc/rfc2141.txt) +* [IANA URN Namespace Registry](http://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml) +* [Punycode: A Bootstring encoding of Unicode for Internationalized Domain Names in Applications (IDNA)](http://tools.ietf.org/html/rfc3492) +* [application/x-www-form-urlencoded](http://www.w3.org/TR/REC-html40/interact/forms.html#form-content-type) (Query String Parameters) and [application/x-www-form-urlencoded encoding algorithm](http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#application/x-www-form-urlencoded-encoding-algorithm) +* [What every web developer must know about URL encoding](http://blog.lunatech.com/2009/02/03/what-every-web-developer-must-know-about-url-encoding) + +Informal stuff + +* [Parsing URLs for Fun and Profit](http://tools.ietf.org/html/draft-abarth-url-01) +* [Naming URL components](http://tantek.com/2011/238/b1/many-ways-slice-url-name-pieces) + +How other environments do things + +* [Java URI Class](http://docs.oracle.com/javase/7/docs/api/java/net/URI.html) +* [Java Inet6Address Class](http://docs.oracle.com/javase/1.5.0/docs/api/java/net/Inet6Address.html) +* [Node.js URL API](http://nodejs.org/docs/latest/api/url.html) + +[Discussion on Hacker News](https://news.ycombinator.com/item?id=3398837) + +### Forks / Code-borrow ### + +* [node-dom-urls](https://github.com/passy/node-dom-urls) passy's partial implementation of the W3C URL Spec Draft for Node +* [urlutils](https://github.com/cofounders/urlutils) cofounders' `window.URL` constructor for Node + +### Alternatives ### + +If you don't like URI.js, you may like one of the following libraries. (If yours is not listed, drop me a line…) + +#### Polyfill #### + +* [DOM-URL-Polyfill](https://github.com/arv/DOM-URL-Polyfill/) arv's polyfill of the [DOM URL spec](https://dvcs.w3.org/hg/url/raw-file/tip/Overview.html#interface-urlutils) for browsers +* [inexorabletash](https://github.com/inexorabletash/polyfill/#whatwg-url-api) inexorabletash's [WHATWG URL API](http://url.spec.whatwg.org/) + +#### URL Manipulation #### + +* [The simple <a> URL Mutation "Hack"](http://jsfiddle.net/rodneyrehm/KkGUJ/) ([jsPerf comparison](http://jsperf.com/idl-attributes-vs-uri-js)) +* [URL.js](https://github.com/ericf/urljs) +* [furl (Python)](https://github.com/gruns/furl) +* [mediawiki Uri](https://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/resources/mediawiki/mediawiki.Uri.js?view=markup) (needs mw and jQuery) +* [jurlp](https://github.com/tombonner/jurlp) +* [jsUri](https://github.com/derek-watson/jsUri) + +#### URL Parsers #### + +* [The simple <a> URL Mutation "Hack"](http://jsfiddle.net/rodneyrehm/KkGUJ/) ([jsPerf comparison](http://jsperf.com/idl-attributes-vs-uri-js)) +* [URI Parser](http://blog.stevenlevithan.com/archives/parseuri) +* [jQuery-URL-Parser](https://github.com/allmarkedup/jQuery-URL-Parser) +* [Google Closure Uri](https://google.github.io/closure-library/api/class_goog_Uri.html) +* [URI.js by Gary Court](https://github.com/garycourt/uri-js) + +#### URI Template #### + +* [uri-template](https://github.com/rezigned/uri-template.js) (supporting extraction as well) by Rezigne +* [uri-templates](https://github.com/geraintluff/uri-templates) (supporting extraction as well) by Geraint Luff +* [uri-templates](https://github.com/marc-portier/uri-templates) by Marc Portier +* [uri-templates](https://github.com/geraintluff/uri-templates) by Geraint Luff (including reverse operation) +* [URI Template JS](https://github.com/fxa/uritemplate-js) by Franz Antesberger +* [Temple](https://github.com/brettstimmerman/temple) by Brett Stimmerman +* ([jsperf comparison](http://jsperf.com/uri-templates/2)) + +#### Various #### + +* [TLD.js](https://github.com/oncletom/tld.js) - second level domain names +* [Public Suffix](http://mxr.mozilla.org/mozilla-central/source/netwerk/dns/effective_tld_names.dat?raw=1) - second level domain names +* [uri-collection](https://github.com/scivey/uri-collection) - underscore based utility for working with many URIs + +## Authors ## + +* [Rodney Rehm](https://github.com/rodneyrehm) +* [Various Contributors](https://github.com/medialize/URI.js/graphs/contributors) + + +## Contains Code From ## + +* [punycode.js](http://mths.be/punycode) - Mathias Bynens +* [IPv6.js](http://intermapper.com/support/tools/IPV6-Validator.aspx) - Rich Brown - (rewrite of the original) + + +## License ## + +URI.js is published under the [MIT license](http://www.opensource.org/licenses/mit-license). Until version 1.13.2 URI.js was also published under the [GPL v3](http://opensource.org/licenses/GPL-3.0) license - but as this dual-licensing causes more questions than helps anyone, it was dropped with version 1.14.0. + + +## Changelog ## + +moved to [Changelog](./CHANGELOG.md) |