URL
v2.0.0

View Source URL (URL v2.0.0)

Functions for parsing URLs.

This module provides functions for parsing URLs. It is modelled on Elixir's URI module but will also parse scheme-specific URIs such as geo, data tel, mailto, and uuid.

Summary

Types

t()
uri_type()

Functions

new(url)

Parses a string url and returns a URL.t/0 struct that has the same shape as Elixir's URI.t/0 with the addition of the parsed_path key.

new!(url)

Parses a string url and returns a URL.t/0 struct that has the same shape as Elixir's URI.t/0 with the addition of the parsed_path key, or raises an exception.

parse_query_string(query)

Parse and percent decode a URL query string.

to_string(url)

Returns the string representation of the given URL struct (t:t/0).

Types

Link to this type

t()

View Source 
@type t() :: %URL{
  authority: nil | binary(),
  fragment: nil | binary(),
  host: nil | binary(),
  parsed_path: uri_type(),
  path: nil | binary(),
  port: nil | :inet.port_number(),
  query: nil | binary(),
  scheme: nil | binary(),
  userinfo: nil | binary()
}
Link to this type

uri_type()

View Source 
@type uri_type() ::
  nil | URL.Data.t() | URL.Geo.t() | URL.Tel.t() | URL.UUID.t() | URL.Mailto.t()

Functions

Link to this function

new(url)

View Source 
@spec new(url :: binary()) :: {:ok, t()} | {:error, {module(), String.t()}}

Parses a string url and returns a URL.t/0 struct that has the same shape as Elixir's URI.t/0 with the addition of the parsed_path key.

Arguments

  • url is a binary representation of a URL.

Returns

  • {:ok, URL.t()} or

  • {:error, {exception, reason}}.

Example 

iex> URL.new("geo:48.198634,-16.371648,3.4;crs=wgs84;u=40.0")
{:ok,
  %URL{
    authority: nil,
    fragment: nil,
    host: nil,
    parsed_path: %URL.Geo{
      alt: 3.4,
      lat: 48.198634,
      lng: -16.371648,
      params: %{"crs" => "wgs84", "u" => 40.0}
    },
    path: "48.198634,-16.371648,3.4;crs=wgs84;u=40.0",
    port: nil,
    query: nil,
    scheme: "geo",
    userinfo: nil
  }
}

iex> URL.new("geo:48.198634,--16.371648,3.4;crs=wgs84;u=40.0")
{:error,
 {URL.Parser.ParseError,
  "expected an string of digits while processing lat inside alt inside geo data. Detected on line 1 at \"-16.371648,3.4;crs=w\" <> ..."}}

iex> URL.new "/invalid_greater_than_in_path/>"
{:error,
 {URI.Error,
  "cannot parse due to reason invalid_uri: \">\""}}
Link to this function

new!(url)

View Source 
@spec new!(url :: binary()) :: t() | no_return()

Parses a string url and returns a URL.t/0 struct that has the same shape as Elixir's URI.t/0 with the addition of the parsed_path key, or raises an exception.

Arguments

  • url is a binary representation of a URL.

Returns

Example 

iex> URL.new!("geo:48.198634,-16.371648,3.4;crs=wgs84;u=40.0")
%URL{
  authority: nil,
  fragment: nil,
  host: nil,
  parsed_path: %URL.Geo{
    alt: 3.4,
    lat: 48.198634,
    lng: -16.371648,
    params: %{"crs" => "wgs84", "u" => 40.0}
  },
  path: "48.198634,-16.371648,3.4;crs=wgs84;u=40.0",
  port: nil,
  query: nil,
  scheme: "geo",
  userinfo: nil
}
Link to this function

parse_query_string(query)

View Source 
@spec parse_query_string(String.t() | map()) :: map() | {:error, {module(), binary()}}

Parse and percent decode a URL query string.

Returns

  • Either a map of query params or

  • an {:error, {URL.Parser.ParseError, reason}} tuple.

Examples 

iex> URL.parse_query_string("url=http%3a%2f%2ffonzi.com%2f&name=Fonzi&mood=happy&coat=leather")
%{
  "coat" => "leather",
  "mood" => "happy",
  "name" => "Fonzi",
  "url" => "http://fonzi.com/"
}

iex> mailto = "mailto:user@%E7%B4%8D%E8%B1%86.example.org?subject=Test&body=NATTO"
iex> URL.new!(mailto) |> URL.parse_query_string()
%{"body" => "NATTO", "subject" => "Test"}
Link to this function

to_string(url)

View Source 
@spec to_string(t()) :: String.t()

Returns the string representation of the given URL struct (t:t/0).

This function delegates to URI.to_string/1.

Arguments

Returns

  • a string representation of the URL.

Examples 

iex> {:ok, geo_url} = URL.new("geo:48.198634,-16.371648,3.4;crs=wgs84;u=40.0")
iex> URL.to_string(geo_url)
"geo:48.198634,-16.371648,3.4;crs=wgs84;u=40.0"