View Source URL (URL v1.5.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

Functions

Parses a url and returns a %URL{} struct that has the same shape as Elixir's %URI{} with the addition of the parsed_path key.

Parses a url and returns a %URL{} struct that has the same shape as Elixir's %URI{} with the addition of the parsed_path key.

parse(url) deprecated

Parses a url and returns a %URL{} struct that has the same shape as Elixir's %URI{} with the addition of the parsed_path key.

Parses the given binary as parse_query.

Parse a URL query string and percent decode.

Types

@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()
}
@type uri_type() ::
  nil | URL.Data.t() | URL.Geo.t() | URL.Tel.t() | URL.UUID.t() | URL.Mailto.t()

Functions

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

Parses a url and returns a %URL{} struct that has the same shape as Elixir's %URI{} with the addition of the parsed_path key.

Arguments

  • url is a binary representation of a URL

Returns

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

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

}

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

Parses a url and returns a %URL{} struct that has the same shape as Elixir's %URI{} with the addition of the parsed_path key.

Arguments

  • url is a binary representation of a URL

Returns

  • URL.t() or

  • raises an exception

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

}

This function is deprecated. Use new/1 instead.
@spec parse(url :: binary()) :: t()

Parses a url and returns a %URL{} struct that has the same shape as Elixir's %URI{} with the addition of the parsed_path key.

Arguments

  • url is a binary representation of a URL

Returns

  • URL.t() or

  • {:error, reason}

Example

iex> URL.parse("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(binary, opts \\ [])

View Source
@spec parse_query(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: pos_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as parse_query.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the parse_query (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

  • :byte_offset - the byte offset for the whole binary, defaults to 0
  • :line - the line and the byte offset into that line, defaults to {1, byte_offset}
  • :context - the initial context value. It will be converted to a map
Link to this function

parse_query_string(query)

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

Parse a URL query string and percent decode.

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

See URI.to_string/1.