# 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.URIType
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"). For all other components, you need to manually percent encode them before passing them to the URI constructor. Note that multiple values for a single query key can provided like Dict("key"=>["value1", "value2"]), in which case the constructor will percent encode only the values you pass in as the query part.

When constructing a URI from a String, you need to ensure that the string is correctly percent encoded already.

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.

Note that you manually need to percent decode the content of the individual component fields before you further use their content, as they are returned in percent-encoded form.

source
URIs.queryparamsFunction
queryparams(::URI) -> Dict
queryparams(query_str::AbstractString) -> Dict

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

Note that duplicate query param values are not supported; if needed, use queryparampairs.

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

source
URIs.queryparampairsFunction
queryparampairs(::URI) -> Vector{Pair{String, String}}
queryparampairs(query_str::AbstractString) -> Vector{Pair{String, String}}

Identical to queryparams, but returns a Vector{Pair{String, String}} 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.

source
URIs.absuriFunction
absuri(uri::Union{URI,AbstractString}, context::Union{URI,AbstractString}) -> URI

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

source
URIs.escapepathFunction
escapepath(path)

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

source
URIs.resolvereferenceFunction
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")
source
URIs.splitpathFunction
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"
source