NAME

HTTP::Promise::Headers::Link - Link Header Field

SYNOPSIS

    use HTTP::Promise::Headers::Link;
    my $link = HTTP::Promise::Headers::Link->new || 
        die( HTTP::Promise::Headers::Link->error, "\n" );
    my $uri = $link->link;
    $link->link( 'https://example.org' );
    $link->rel( 'preconnect' );
    $h->link( "$link" );
    # Link: <https://example.org>; rel="preconnect"
    $link->title( 'Foo' );
    $link->anchor( '#bar' );
    $cd->params( rel => 'preconnect', anchor => 'bar' );

VERSION

    v0.1.0

DESCRIPTION

The following is an extract from Mozilla documentation.

The HTTP Link entity-header field provides a means for serializing one or more links in HTTP headers. It is semantically equivalent to the HTML link element.

Example:

    Link: <https://example.com>; rel="preconnect"; title="Foo"; anchor="#bar"

METHODS

anchor

Sets or gets the anchor property.

as_string

Returns a string representation of the Link object.

rel

Sets or gets the relationship of the Link as a scalar.

link

Sets or gets an URI. It returns the URI value (not an object).

When you set this value, it will be automatically surrounded by <>

param

Sets or gets an arbitrary Link property.

Note that if you use this, you bypass other specialised method who do some additional processing, so be mindful.

params

Sets or gets multiple arbitrary Link properties at once.

If called without any arguments, this returns the hash object used to store the Link properties.

title

Without any argument, this returns the string containing the original title of the link. The title is always optional.

If the property title* is set instead, then it will be decoded and used instead, and the value for "title_charset" and "title_lang" will be set.

When setting the title value, this takes an optional language iso 639 code (see rfc5987 and rfc2231). If the title contains non ascii characters, it will be automatically encoded according to rfc5987. and the property title* set instead. That property, by rfc standard, takes precedence over the title one.

See rfc8288, section 3 for more information.

The language provided, if any, will be used then.

For example:

    $h->link( 'https://www.example.com' );
    $h->rel( 'preconnect' );
    $h->title( q{Foo} );
    say "$h";
    # <https://www.example.com>; rel="preconnect"; title="Foo"

    $h->link( 'https://www.example.com' );
    $h->rel( 'previous' );
    $h->title( q{「お早う」小津安二郎} );
    say "$h";
    # https://www.example.com; rel="previous"; title*="UTF-8''%E3%81%8A%E6%97%A9%E3%81%86%E3%80%8D%E5%B0%8F%E6%B4%A5%E5%AE%89%E4%BA%8C%E9%83%8E"
 
    $h->link( 'https://www.example.com' );
    $h->rel( 'previous' );
    $h->title( q{「お早う」小津安二郎}, 'ja-JP' );
    say "$h";
    # https://www.example.com; rel="previous"; title*="UTF-8'ja-JP'%E3%81%8A%E6%97%A9%E3%81%86%E3%80%8D%E5%B0%8F%E6%B4%A5%E5%AE%89%E4%BA%8C%E9%83%8E"

    # Using default value
    $h->title_lang( 'ja-JP' );
    $h->link( 'https://www.example.com' );
    $h->rel( 'previous' );
    $h->title( q{「お早う」小津安二郎}, 'ja-JP' );
    say "$h";
    # https://www.example.com; rel="previous"; title*="UTF-8'ja-JP'%E3%81%8A%E6%97%A9%E3%81%86%E3%80%8D%E5%B0%8F%E6%B4%A5%E5%AE%89%E4%BA%8C%E9%83%8E"

    $headers->header( Link => "$h" );

The Link header value would then contain a property title* (with the trailing wildcard).

title_charset

Sets or gets the encoded title charset.

This is used when the title contains non-ascii characters, such as Japanese, Korean, or Cyrillic. Although theoretically one can set any character set, by design this only accepts UTF-8 (case insensitive).

This is set automatically when calling "title". You actually need to call "title" first to have a value set.

Returns a scalar object containing the title charset.

title_lang

Sets or gets the encoded title language. This takes an iso 639 language code (see rfc1766).

This is set automatically when calling "title". You actually need to call "title" first to have a value set.

Returns a scalar object containing the title language.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

See also rfc8288, section 3 and Mozilla documentation

HTTP::Promise, HTTP::Promise::Request, HTTP::Promise::Response, HTTP::Promise::Message, HTTP::Promise::Entity, HTTP::Promise::Headers, HTTP::Promise::Body, HTTP::Promise::Body::Form, HTTP::Promise::Body::Form::Data, HTTP::Promise::Body::Form::Field, HTTP::Promise::Status, HTTP::Promise::MIME, HTTP::Promise::Parser, HTTP::Promise::IO, HTTP::Promise::Stream, HTTP::Promise::Exception

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

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

cpanm HTTP::Promise

perl -MCPAN -e shell
install HTTP::Promise