lambdaisland/uri
A pure Clojure/ClojureScript URI library.
Key features
- 100% cross-platform
.cljc - RFC compliant joining of URIs
- relative URIs as first class citizens
Lambda Island Open Source
uri is part of a growing collection of quality Clojure libraries created and maintained by the fine folks at Gaiwan.
Pay it forward by becoming a backer on our Open Collective, so that we may continue to enjoy a thriving Clojure ecosystem.
You can find an overview of our projects at lambdaisland/open-source.
Rationale
There are a number of Clojure libraries for working with URI/URLs (see
Similar projects below). They all rely to some degree on
java.net.URI or java.net.URL. This lib provides a pure-Clojure/ClojureScript
alternative.
See the announcement blog post
Installation
To install, add the following dependency to your project or build file:
deps.edn:
lambdaisland/uri {:mvn/version "1.15.125"}project.clj
[lambdaisland/uri "1.15.125"]Usage
(require '[lambdaisland.uri :refer [uri join]])
;; uri :: String -> lambdaisland.uri.URI
(uri "//example.com/foo/bar")
;;=> #lambdaisland/uri "//example.com/foo/bar"
;; A URI is a record, use assoc to update specific parts
;; Use `str` if you want the URI back as a string
(str
(assoc (uri "//example.com/foo/bar")
:scheme "https"
:user "arne"
:password "supersecret"
:host "lambdaisland.com"
:port "3333"
:path "/hello/world"
:query "q=5"
:fragment "section1"))
;;=> "https://arne:[email protected]:3333/hello/world?q=5#section1"
;; RFC compliant joining of relative URIs
(join "//example.com/foo/bar" "./~arne/site/" "../foo.png")
;;=> #lambdaisland/uri "//example.com/foo/~arne/foo.png"
;; Arguments to `join` are coerced, you can pass strings, java.net.URI, or any x
;; for which `(str x)` returns a URI string.
(join (java.net.URI. "http://example.com/foo/bar") (uri "./~arne/site/") "../foo.png")
;;=> #lambdaisland/uri "http://example.com/foo/~arne/foo.png"
;; URI implements IFn for keyword based lookup, so it's fully
;; interface-compatible with Clojure maps.
(:path (uri "http://example.com/foo/bar"))
;; Provide custom ordering for query-map
;; clj -Sdeps '{:deps {org.flatland/ordered {:mvn/version "1.5.7"}}}'
(require '[lambdaisland.uri :refer [query-map]]
'[flatland.ordered.map :refer [ordered-map]])
(keys (query-map "http://example.com?a=1&b=2&c=3&d=4&e=5&f=6&g=7&h=8&i=9"
{:into (ordered-map)}))
=> (:a :b :c :d :e :f :g :h :i)
;; Instances of URI are printed with a #lambdaisland/uri reader tag. To read
;; them back from EDN, use the provided readers.
(require '[clojure.edn :as edn])
(edn/read-string
{:readers lambdaisland.uri/edn-readers}
"#lambdaisland/uri \"http://example.com/foo/~arne/foo.png\"")Babashka-specific caveats (also applies to SCI)
Instances of URI implement the toString method, so calling (str uri) gives
you the URI back as a string. They also implement the IFn interfaces so they
are callable the way maps are.
On babashka implementing interfaces or overriding Object methods is not
supported. As an alternative to clojure.core/str you can use
lambdaisland.uri/uri-str. As an alternative to using the URI as a function, use the keyword as a function, or use clojure.core/get
;; clojure / clojurescript
(str uri) ;; "https://example.com"
(uri :host) ;; "example.com"
;; bb
(str uri) ;; "{:scheme "https", :domain "example.com", :path ...}"
(uri :host) ;; nil
(uri/uri-str uri) ;; "https://example.com"
(:host uri) ;; "example.com"
(get uri :host) ;; "example.com"Similar projects
- exploding-fish I was not aware at the time of creating lambdaisland/uri of exploding fish. It is the most mature pure-Clojure URI lib out there. It does not provide ClojureScript support.
- cemerick/url
Cross platform (cljx), Clojure version uses
java.net.URL. - michaelklishin/urly
Based on
java.net.URI. - codonnell/uri
Based on
java.net.URI.
Further reading
RFC3986 Uniform Resource Identifier (URI): Generic Syntax
This library implements the algorithm specified in Section 5.2 of that RFC.
It has been tested against this list of test cases compiled by the W3C.
Contributing
Everyone has a right to submit patches to uri, and thus become a contributor.
Contributors MUST
- adhere to the LambdaIsland Clojure Style Guide
- write patches that solve a problem. Start by stating the problem, then supply a minimal solution.
* - agree to license their contributions as MPL 2.0.
- not break the contract with downstream consumers.
** - not break the tests.
Contributors SHOULD
- update the CHANGELOG and README.
- add tests for new functionality.
If you submit a pull request that adheres to these rules, then it will almost certainly be merged immediately. However some things may require more consideration. If you add new dependencies, or significantly increase the API surface, then we need to decide if these changes are in line with the project's goals. In this case you can start by writing a pitch, and collecting feedback on it.
* This goes for features too, a feature needs to solve a problem. State the problem it solves, then supply a minimal solution.
** As long as this project has not seen a public release (i.e. is not on Clojars)
we may still consider making breaking changes, if there is consensus that the
changes are justified.
License
Copyright © 2017-2021 Arne Brasseur and Contributors
Licensed under the term of the Mozilla Public License 2.0, see LICENSE.