view release on metacpan or  search on metacpan

lib/At/Protocol/URI.pm  view on Meta::CPAN

    sub replace_param( $s, $name, @v ) {
        $s->delete_param($name);
        $name = uri_unescape $name;
        push @$s, [ $name, uri_unescape shift @v ] while @v;
        1;
    }

    sub reset($s) {
        !( @$s = () );
    }

    sub as_string( $s, $sep //= '&' ) {
        join $sep, map { join '=', uri_escape_utf8( $_->[0] ), uri_escape_utf8( $_->[1] ) } @$s;
    }
    };
1;
__END__
=pod

=encoding utf-8

=head1 NAME

At::Protocol::URI - AT Protocol URI Validation

=head1 SYNOPSIS

    use At::Protocol::URI qw[:all];
    try {
        ensureValidNSID( 'net.users.bob.ping' );
    }
    catch($err) {
        ...; # do something about it
    }

=head1 DESCRIPTION

The AT URI scheme (C<at://>) makes it easy to reference individual records in a specific repository, identified by
either DID or handle. AT URIs can also be used to reference a collection within a repository, or an entire repository
(aka, an identity).

This package aims to validate them.

=head1 Functions

You may import functions by name or with the C<:all> tag.

=head2 C<new( ... )>

Verifies an AT-uri and creates a new object containing it.

    my $uri = At::Protocol::URI->new( 'at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3jwdwj2ctlk26' );

On success, an object is returned that will stringify to the URI itself.

=head2 C<create( ... )>

    my $uri_1 = create('did:plc:44ybard66vv44zksje25o7dz');
    my $uri_2 = create('did:plc:44ybard66vv44zksje25o7dz', 'app.bsky.feed.post', '3jwdwj2ctlk26');
    my $uri_3 = create('bnewbold.bsky.team', 'app.bsky.feed.post', '3jwdwj2ctlk26');

Allows you to build a new URI from parts.

Expected parameters include:

=over

=item C<host> - required

This is either a L<DID|At::Protocol::DID> or L<handle|At::Protocol::Handle>.

=item C<collection>

=item C<rkey>

=back

A new object is returned on success.

=head2 C<protocol( )>

    my $prot = $uri->protocol;

Returns the URI's protocol. This is always C<at:>.

=head2 C<origin( )>

    my $base = $uri->origin;

Returns the protocol and host.

=head2 C<host( [...] )>

    my $host = $uri->host;
    $uri->host('did:plc:...');

Mutator around the host.

=head2 C<pathname( [...] )>

    my $path = $uri->pathname;
    $uri->pathname( '/foo' );

Mutator around the url path.

=head2 C<search( [...] )>

    my $search = $uri->search;
    $uri->search( '?foo=bar' );

Mutator around the URI's search parameters.

=head2 C<hash( [...] )>

    my $hash = $uri->hash;
    $uri->hash('hash');

Mutator around the URI's hash field.

When a I<strong> reference to another record is required, best practice is to use a CID hash in addition to the AT URI.