Atex.AtURI (atex v0.2.0)

View Source

Struct and helper functions for manipulating at:// URIs, which identify specific records within the AT Protocol.

ATProto spec: https://atproto.com/specs/at-uri-scheme

This module only supports the restricted URI syntax used for the Lexicon at-uri type, with no support for query strings or fragments. If/when the full syntax gets widespread use, this module will expand to accomodate them.

Both URIs using DIDs and handles ("example.com") are supported.

Summary

Functions

Check if a string is a valid at:// URI.

Create a new AtURI struct from a string by matching it against the regex.

The same as new/1 but raises an ArgumentError if an invalid string is given.

Format an Atex.AtURI to the canonical string representation.

Types

t()

@type t() :: %Atex.AtURI{
  authority: String.t(),
  collection: (String.t() | nil) | nil,
  rkey: (String.t() | nil) | nil
}

Functions

match?(string)

@spec match?(String.t()) :: boolean()

Check if a string is a valid at:// URI.

Examples

iex> Atex.AtURI.match?("at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3jwdwj2ctlk26")
true

iex> Atex.AtURI.match?("at://did:web:comet.sh")
true

iex> Atex.AtURI.match?("at://ovyerus.com/sh.comet.v0.feed.track")
true

iex> Atex.AtURI.match?("gobbledy gook")
false

new(string)

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

Create a new AtURI struct from a string by matching it against the regex.

Returns {:ok, aturi} if a valid at:// URI is given, otherwise it will return :error.

Examples

iex> Atex.AtURI.new("at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3jwdwj2ctlk26")
{:ok, %Atex.AtURI{
  rkey: "3jwdwj2ctlk26",
  collection: "app.bsky.feed.post",
  authority: "did:plc:44ybard66vv44zksje25o7dz"
}}

iex> Atex.AtURI.new("at:invalid/malformed")
:error

Partial URIs pointing to a collection without a record key, or even just a given authority, are also supported:

iex> Atex.AtURI.new("at://ovyerus.com/sh.comet.v0.feed.track")
{:ok, %Atex.AtURI{
  rkey: nil,
  collection: "sh.comet.v0.feed.track",
  authority: "ovyerus.com"
}}

iex> Atex.AtURI.new("at://did:web:comet.sh")
{:ok, %Atex.AtURI{
  rkey: nil,
  collection: nil,
  authority: "did:web:comet.sh"
}}

new!(string)

@spec new!(String.t()) :: t()

The same as new/1 but raises an ArgumentError if an invalid string is given.

Examples

iex> Atex.AtURI.new!("at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3jwdwj2ctlk26")
%Atex.AtURI{
  rkey: "3jwdwj2ctlk26",
  collection: "app.bsky.feed.post",
  authority: "did:plc:44ybard66vv44zksje25o7dz"
}

iex> Atex.AtURI.new!("at:invalid/malformed")
** (ArgumentError) Malformed at:// URI

to_string(uri)

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

Format an Atex.AtURI to the canonical string representation.

Also available via the String.Chars protocol.

Examples

iex> aturi = %Atex.AtURI{
...>   rkey: "3jwdwj2ctlk26",
...>   collection: "app.bsky.feed.post",
...>   authority: "did:plc:44ybard66vv44zksje25o7dz"
...> }
iex> Atex.AtURI.to_string(aturi)
"at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3jwdwj2ctlk26"

iex> aturi = %Atex.AtURI{authority: "did:web:comet.sh"}
iex> to_string(aturi)
"at://did:web:comet.sh"