.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTTP::CookieMonster 3pm"
.TH HTTP::CookieMonster 3pm "2022-10-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::CookieMonster \- Easy read/write access to your jar of HTTP::Cookies
.SH "VERSION"
.IX Header "VERSION"
version 0.11
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    # Use the functional interface for quick read\-only access
\&    use HTTP::CookieMonster qw( cookies );
\&    use WWW::Mechanize;
\&
\&    my $mech = WWW::Mechanize\->new;
\&    my $url = \*(Aqhttps://www.nytimes.com\*(Aq;
\&    $mech\->get( $url );
\&
\&    my @cookies = cookies( $mech\->cookie_jar );
\&    my $cookie  = cookies( $mech\->cookie_jar, \*(AqRMID\*(Aq );
\&    print $cookie\->val;
\&
\&    # Use the OO interface for read/write access
\&
\&    use HTTP::CookieMonster;
\&
\&    my $monster = HTTP::CookieMonster\->new( $mech\->cookie_jar );
\&    my $cookie = $monster\->get_cookie(\*(AqRMID\*(Aq);
\&    print $cookie\->val;
\&
\&    $cookie\->val(\*(Aqrandom stuff\*(Aq);
\&    $monster\->set_cookie( $cookie );
\&
\&    # now fetch page using mangled cookie
\&    $mech\->get( $url );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module was created because messing around with HTTP::Cookies is
non-trivial.  HTTP::Cookies a very useful module, but using it is not always
as easy and clean as it could be. For instance, if you want to find a
particular cookie, you can't just ask for it by name.  Instead, you have to use
a callback:
.PP
.Vb 1
\&    $cookie_jar\->scan( \e&callback )
.Ve
.PP
The callback will be invoked with 11 positional parameters:
.PP
.Vb 11
\&    0 version
\&    1 key
\&    2 val
\&    3 path
\&    4 domain
\&    5 port
\&    6 path_spec
\&    7 secure
\&    8 expires
\&    9 discard
\&    10 hash
.Ve
.PP
That's a lot to remember and it doesn't make for very readable code.
.PP
Now, let's say you want to save or update a cookie. Now you're back to the many
positional params yet again:
.PP
.Vb 1
\&    $cookie_jar\->set_cookie( $version, $key, $val, $path, $domain, $port, $path_spec, $secure, $maxage, $discard, \e%rest )
.Ve
.PP
Also not readable. Unless you have an amazing memory, you may find yourself
checking the docs regularly to see if you did, in fact, get all those params in
the correct order etc.
.PP
HTTP::CookieMonster gives you a simple interface for getting and setting
cookies. You can fetch an \s-1ARRAY\s0 of all your cookies:
.PP
.Vb 8
\&    my @all_cookies = $monster\->all_cookies;
\&    foreach my $cookie ( @all_cookies ) {
\&        print $cookie\->key;
\&        print $cookie\->val;
\&        print $cookie\->secure;
\&        print $cookie\->domain;
\&        # etc
\&    }
.Ve
.PP
Or, if you know for a fact exactly what will be in your cookie jar, you can
fetch a cookie by name.
.PP
.Vb 1
\&    my $cookie = $monster\->get_cookie( \*(Aqplack_session\*(Aq );
.Ve
.PP
This gives you fast access to a cookie without a callback, iterating over a
list etc. It's good for quick hacks and you can dump the cookie quite easily to
inspect its contents in a highly readable way:
.PP
.Vb 2
\&    use Data::Printer;
\&    p $cookie;
.Ve
.PP
If you want to mangle the cookie before the next request, that's easy too.
.PP
.Vb 3
\&    $cookie\->val(\*(Aqwoohoo\*(Aq);
\&    $monster\->set_cookie( $cookie );
\&    $mech\->get( $url );
.Ve
.PP
Or, add an entirely new cookie to the jar:
.PP
.Vb 10
\&    use HTTP::CookieMonster::Cookie;
\&    my $cookie = HTTP::CookieMonster::Cookie\->new(
\&        key       => \*(Aqcookie\-name\*(Aq,
\&        val       => \*(Aqcookie\-val\*(Aq,
\&        path      => \*(Aq/\*(Aq,
\&        domain    => \*(Aq.somedomain.org\*(Aq,
\&        path_spec => 1,
\&        secure    => 0,
\&        expires   => 1376081877
\&    );
\&
\&    $monster\->set_cookie( $cookie );
\&    $mech\->get( $url );
.Ve
.SS "new"
.IX Subsection "new"
\&\fBnew()\fR takes just one required parameter, which is cookie_jar, a valid
HTTP::Cookies object.
.PP
.Vb 1
\&    my $monster = HTTP::CookieMonster\->new( $mech\->cookie_jar );
.Ve
.SS "cookie_jar"
.IX Subsection "cookie_jar"
A reader which returns an HTTP::Cookies object.
.SS "all_cookies"
.IX Subsection "all_cookies"
Returns an \s-1ARRAY\s0 of all cookies in the cookie jar, represented as
HTTP::CookieMonster::Cookie objects.
.PP
.Vb 4
\&    my @cookies = $monster\->all_cookies;
\&    foreach my $cookie ( @cookies ) {
\&        print $cookie\->key;
\&    }
.Ve
.ie n .SS "set_cookie( $cookie )"
.el .SS "set_cookie( \f(CW$cookie\fP )"
.IX Subsection "set_cookie( $cookie )"
Sets a cookie and updates the cookie jar.  Requires a
HTTP::CookieMonster::Cookie object.
.PP
.Vb 3
\&    my $monster = HTTP::CookieMonster\->new( $mech\->cookie_jar );
\&    my $s = $monster\->get_cookie(\*(Aqsession\*(Aq);
\&    $s\->val(\*(Aqrandom_string\*(Aq);
\&
\&    $monster\->set_cookie( $s );
\&
\&    # You can also add an entirely new cookie to the jar via this method
\&
\&    use HTTP::CookieMonster::Cookie;
\&    my $cookie = HTTP::CookieMonster::Cookie\->new(
\&        key       => \*(Aqcookie\-name\*(Aq,
\&        val       => \*(Aqcookie\-val\*(Aq,
\&        path      => \*(Aq/\*(Aq,
\&        domain    => \*(Aq.somedomain.org\*(Aq,
\&        path_spec => 1,
\&        secure    => 0,
\&        expires   => 1376081877
\&    );
\&
\&    $monster\->set_cookie( $cookie );
.Ve
.ie n .SS "delete_cookie( $cookie )"
.el .SS "delete_cookie( \f(CW$cookie\fP )"
.IX Subsection "delete_cookie( $cookie )"
Deletes a cookie and updates the cookie jar.  Requires a
HTTP::CookieMonster::Cookie object.
.ie n .SS "get_cookie( $name )"
.el .SS "get_cookie( \f(CW$name\fP )"
.IX Subsection "get_cookie( $name )"
Be aware that this method may surprise you by what it returns.  When called in
scalar context, \fBget_cookie()\fR returns the first cookie which exactly matches the
name supplied.  In many cases this will be exactly what you want, but that
won't always be the case.
.PP
If you are spidering multiple web sites with the same UserAgent object, be
aware that you'll likely have cookies from multiple sites in your cookie jar.
In this case asking for get_cookie('session') in scalar context may not return
the cookie which you were expecting.  You will be safer calling \fBget_cookie()\fR in
list context:
.PP
.Vb 1
\&    $monster = HTTP::CookieMonster\->new( $mech\->cookie_jar );
\&
\&    # first cookie with this name
\&    my $first_session = $monster\->get_cookie(\*(Aqsession\*(Aq);
\&
\&    # all cookies with this name
\&    my @all_sessions  = $monster\->get_cookie(\*(Aqsession\*(Aq);
.Ve
.SH "FUNCTIONAL/PROCEDURAL INTERFACE"
.IX Header "FUNCTIONAL/PROCEDURAL INTERFACE"
.SS "cookies"
.IX Subsection "cookies"
This function will \s-1DWIM.\s0  Here are some examples:
.PP
.Vb 1
\&    use HTTP::CookieMonster qw( cookies );
\&
\&    # get all cookies in your jar
\&    my @cookies = cookies( $mech\->cookie_jar );
\&
\&    # get all cookies of a certain name/key
\&    my @session_cookies = cookies( $mech\->cookie_jar, \*(Aqsession_cookie_name\*(Aq );
\&
\&    # get the first cookie of a certain name/key
\&    my $first_session_cookie = cookies( $mech\->cookie_jar, \*(Aqsession_cookie_name\*(Aq );
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Olaf Alders <olaf@wundercounter.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Olaf Alders.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.