NAME

Sietima::HeaderURI - annotated URI for list headers

VERSION

version 1.1.2

SYNOPSIS

  around list_addresses => sub($orig,$self) {
   return +{
    $self->$orig->%*,
    one => Sietima::HeaderURI->new({
      uri => 'http://foo/',
      comment => 'a thing',
    }),
    two => Sietima::HeaderURI->new_from_address(
     $self->owner,
     { subject => 'Hello' },
    ),
    three => Sietima::HeaderURI->new('http://some/url'),
    four => Sietima::HeaderURI->new('(comment) address@example.com'),
   };
  }

DESCRIPTION

This class pairs a URI with a comment, and knows how to render itself as a string that can be used in a list management header (see Sietima::Role::Headers).

ATTRIBUTES

All attributes are read-only.

uri

Required URI object, coercible from a string or a hashref (see Types::Uri for the details). This is the URI that users should follow to perform the action implied by the list management header.

comment

Optional string, will be added to the list management header as a comment (in parentheses).

METHODS

new

 Sietima::HeaderURI->new({
   uri => 'http://foo/', comment => 'a thing',
 });

 Sietima::HeaderURI->new(
  Email::Address->parse('(comment) address@example.com'),
 );

 Sietima::HeaderURI->new( '(comment) address@example.com' );

 Sietima::HeaderURI->new(
  URI->new('http://some/url'),
 );

 Sietima::HeaderURI->new( 'http://some/url' );

Objects of this class can be constructed in several ways.

You can pass a hashref with URI (or something that Types::Uri can coerce into a URI) and a comment string, as in the first example.

Or you can pass a single value that can be (or can be coerced into) either a Email::Address or a URI.

Email addresse became mailto: URIs, and the optional comment is preserved.

new_from_address

 Sietima::HeaderURI->new_from_address(
  $email_address,
  \%query,
 );

This constructor builds a complex mailto: URI with the query hash you provide. It's a shortcut for:

 my $uri = URI->new("mailto:$email_address");
 $uri->query_form(\%query);

Common query keys are subject and body. See RFC 6068 ("The 'mailto' URI Scheme") for details.

as_header_raw

  $mail->header_raw_set('List-Thing' => $headeruri->as_header_raw);

This method returns a string representation of the "URI" and "comment" in the format specified by RFC 2369 ("The Use of URLs as Meta-Syntax for Core Mail List Commands and their Transport through Message Header Fields").

For example:

 Sietima::HeaderURI->new({
   uri => 'http://foo/', comment => 'a thing',
 })->as_header_raw eq '<http://foo/> (a thing)';

 Sietima::HeaderURI->new( '(comment) address@example.com' )
 ->as_header_raw eq '<mailto:address@example.com> (comment)';

 Sietima::HeaderURI->new( 'http://some/url' )
 ->as_header_raw eq '<http://some/url>';

Notice that, since the list management headers are structured, they should always be set with header_raw_set.

AUTHOR

Gianni Ceccarelli <dakkar@thenautilus.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Gianni Ceccarelli <dakkar@thenautilus.net>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Sietima

perl -MCPAN -e shell
install Sietima