URL (URL v2.0.3)

Copy Markdown View Source

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.

The primary API is new/1, which returns a t/0 struct with the same shape as URI.t/0 plus a :parsed_path holding the parsed scheme-specific data (URL.Geo, URL.Data, URL.Tel, URL.Mailto or URL.UUID), or nil for any other scheme. new!/1 raises instead of returning an error tuple, to_string/1 reverses the parse and parse_query_string/1 decodes a query into a map. No function in this module raises on malformed input.

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

t()

@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()
}

uri_type()

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

Functions

new(url)

@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}}. exception is URI.Error when the URL is not syntactically valid, URL.Parser.ParseError when the scheme-specific path cannot be parsed and ArgumentError when url is not a binary.

Examples

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: \">\""}}

iex> URL.new(:not_a_url)
{:error, {ArgumentError, "expected a binary URL, got: :not_a_url"}}

new!(url)

@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

Examples

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
}

parse_query_string(query)

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

Parse and percent decode a URL query string.

Arguments

  • query is a query string, a URL.t/0 (or any map with a :query key) whose query is parsed, or an {:error, reason} tuple which is returned unchanged so this function can be piped after new/1.

Returns

  • Either a map of query params (an empty map when the query is nil) or

  • an {:error, {exception, 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"}

iex> URL.new!("geo:48.198634,-16.371648") |> URL.parse_query_string()
%{}

to_string(url)

@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"