URIs.jl

URIs is a Julia package for parsing and working with Uniform Resource Identifiers, as defined in RFC 3986.

Tutorial

Parsing URIs from a string can be done with the URI constructor:

julia> u = URI("http://example.com/some/path")
URI("http://example.com/some/path")

The components of the URI can then be accessed via the fields scheme, userinfo, host, port, path, query or fragment:

julia> u = URI("http://example.com/some/path")
URI("http://example.com/some/path")

julia> u.scheme
"http"

julia> u.host
"example.com"

julia> u.path
"/some/path"

To access the query part of a URI as a dictionary, the queryparams function is provided:

julia> u = URI("http://example.com/path?x=1&y=hi")
URI("http://example.com/path?x=1&y=hi")

julia> queryparams(u)
Dict{String,String} with 2 entries:
  "x" => "1"
  "y" => "hi"

Reference

URIs.URI — Type
URI(; scheme="", host="", port="", etc...)
URI(str) = parse(URI, str::String)

A type representing a URI (e.g. a URL). Can be constructed from distinct parts using the various supported keyword arguments, or from a string. The URI constructors will automatically escape any provided query arguments, typically provided as "key"=>"value"::Pair or Dict("key"=>"value"). Note that multiple values for a single query key can provided like Dict("key"=>["value1", "value2"]).

When constructing a URI from a String, you need to first unescape that string: URI( URIs.unescapeuri(str) ).

The URI struct stores the complete URI in the uri::String field and the component parts in the following SubString fields:

  • scheme, e.g. "http" or "https"
  • userinfo, e.g. "username:password"
  • host e.g. "julialang.org"
  • port e.g. "80" or ""
  • path e.g "/"
  • query e.g. "Foo=1&Bar=2"
  • fragment

The queryparams(::URI) function returns a Dict containing the query.

URIs.queryparams — Function
queryparams(::URI)
queryparams(query_str::AbstractString)

Returns a Dict containing the query parameter string parsed according to the key=value pair formatting convention.

Note that this is not part of the formal URI grammar, merely a common parsing convention — see RFC 3986.

URIs.absuri — Function
absuri(uri, context)

Construct an absolute URI, using uri.path and uri.query and filling in other components from context.

URIs.escapeuri — Function
escapeuri(x)

Apply URI percent-encoding to escape special characters in x.

URIs.unescapeuri — Function
unescapeuri(str)

Percent-decode a string according to the URI escaping rules.

URIs.escapepath — Function
escapepath(path)

Escape the path portion of a URI, given the string path containing embedded / characters which separate the path segments.

URIs.resolvereference — Function
resolvereference(base::Union{URI,AbstractString}, ref::Union{URI,AbstractString}) -> URI

Resolve a URI reference ref relative to the absolute base URI base, complying with RFC 3986 Section 5.2.

If ref is an absolute URI, return ref unchanged.

Examples

julia> u = resolvereference("http://example.org/foo/bar/", "/baz/")
URI("http://example.org/baz/")

julia> resolvereference(u, "./hello/world")
URI("http://example.org/baz/hello/world")

julia> resolvereference(u, "http://localhost:8000")
URI("http://localhost:8000")
URIs.splitpath — Function
URIs.splitpath(path|uri; rstrip_empty_segment=true)

Splits the path into component segments based on /, according to http://tools.ietf.org/html/rfc3986#section-3.3. Any fragment and query parts of the string are ignored if present.

A final empty path segment (trailing '/') is removed, if present. This is technically incompatible with the segment grammar of RFC3986, but it seems to be a common recommendation to make paths with and without a trailing slash equivalent. To preserve any final empty path segment, set rstrip_empty_segment=false.

Examples

julia> URIs.splitpath(URI("http://example.com/foo/bar?a=b&c=d"))
2-element Array{String,1}:
 "foo"
 "bar"

julia> URIs.splitpath("/foo/bar/")
2-element Array{String,1}:
 "foo"
 "bar"