view release on metacpan or  search on metacpan

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

Namespaced Identifiers (NSIDs) are used to reference Lexicon schemas for records, XRPC endpoints, and more.

The basic structure and semantics of an NSID are a fully-qualified hostname in Reverse Domain-Name Order, followed by a
simple name. The hostname part is the B<domain authority>, and the final segment is the B<name>.

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 NSID and creates a new object containing it.

    my $nsid = At::Protocol::NSID->new( 'com.example.fooBar' );

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

=head2 C<parse( ... )>

    my $nsid = parse( 'com.example.fooBar' );

Wrapper around C<new(...)> for the sake of compatibility.

=head2 C<create( ... )>

    my $nsid = create( 'alex.example.com' );

Parses a 'normal' (sub)domain name and creates an NSID object.

=head2 C<authority( )>

    my $auth = $nsid->authority;

Returns the domain authority of the NSID.

=head2 C<name( )>

    my $name = $nsid->name;

Returns the name from the NSID.

=head2 C<isValid( ... )>

    my $ok = isValid( 'com.exa💩ple.thing' );

Returns a boolean value indicating whether the given NSID is valid and can be parsed.

=head2 C<ensureValidNsid( ... )>

    ensureValidNsid( '.com.example.wrong' );

Validates an NSID. Throws errors on failure and returns a true value on success.

=head2 C<ensureValidNsidRegex( ... )>

    ensureValidNsidRegex( 'com.example.right' );

Validates an NSID with cursory regex provided by the AT protocol designers. Throws errors on failure and returns a true
value on success.

=head1 See Also

L<https://atproto.com/specs/nsid>

=head1 LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License
2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=begin stopwords

atproto

=end stopwords

=cut