.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Twitter::API::Trait::Migration 3pm"
.TH Twitter::API::Trait::Migration 3pm "2018-10-05" "perl v5.26.2" "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"
Twitter::API::Trait::Migration \- Migration support Net::Twitter/::Lite users
.SH "VERSION"
.IX Header "VERSION"
version 1.0005
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Twitter::API is a rewrite of Net::Twitter. It's leaner, lighter, and
has fasterXfewer dependencies, and less baggage. This trait helps Net::Twitter and
Net::Twitter::Lite users migrate to Twitter::API by providing Net::Twitter
compatible behavior where possible and warning politely where code should be
changed.
.SH "Migrating from Net::Twitter"
.IX Header "Migrating from Net::Twitter"
Twitter::API requires a minimum perl version of 5.14.1. Make sure you have that.
.PP
Just change your constructor call:
.PP
.Vb 7
\&        my $client = Net::Twitter\->new(
\&                traits => [ qw/API::RESTv1_1 OAuth RetryOnError/ ],
\&                consumer_key        => $key,
\&                consumer_secret     => $secret,
\&                access_token        => $token,
\&                access_token_secret => $token_secret,
\&        );
.Ve
.PP
Becomes:
.PP
.Vb 7
\&        my $client = Twitter::API\->new_with_traits(
\&                traits => [ qw/Migration ApiMethods RetryOnError/ ],
\&                consumer_key        => $key,
\&                consumer_secret     => $secret,
\&                access_token        => $token,
\&                access_token_secret => $token_secret,
\&        );
.Ve
.PP
Differences:
.IP "\(bu" 4
replace \f(CW\*(C`new\*(C'\fR with \f(CW\*(C`new_with_traits\*(C'\fR
.IP "\(bu" 4
replace trait \f(CW\*(C`API::RESTv1_1\*(C'\fR with \f(CW\*(C`ApiMethods\*(C'\fR
.IP "\(bu" 4
drop trait \f(CW\*(C`OAuth\*(C'\fR, Twitter::API's core includes it
.IP "\(bu" 4
add the Migration trait so Twitter::API will handle oauth key management in a Net::Twitter compatible way and warn
.SS "Traits"
.IX Subsection "Traits"
Twitter::API supports the following traits:
.IP "\(bu" 4
ApiMethods
.IP "\(bu" 4
AppAuth
.IP "\(bu" 4
DecodeHtmlEntities
.IP "\(bu" 4
NormalizeBooleans
.IP "\(bu" 4
RetryOnError
.IP "\(bu" 4
Enchilada
.PP
\&\fBApiMethods \fRis a direct replacement for Net::Twitter's API::RESTv1_1 trait.
.PP
Net::Twitter's \fBInflateObjects\fR trait will be released as a separate distribution
to minimize Twitter::API's dependencies.
.PP
If you are using the Net::Twitter's \fBWrapResults\fR trait, Twitter::API provides
a better way to access the what it provides. In list context, \s-1API\s0 calls return
both the \s-1API\s0 call results and a Twitter::API::Context object that provides
the same accessors and attributes \fBWrapResult\fR provided, including the
\&\fBresult\fR accessor.
.PP
So, if you had:
.PP
.Vb 3
\&    my $r = $client\->home_timeline;
\&    $r\->result;
\&    $r\->rate_limit_remaining;
.Ve
.PP
You can change that to:
.PP
.Vb 3
\&    my ( $result, $context ) = $client\->home_timeline;
\&    $result;
\&    $context\->rate_limit_remaining;
.Ve
.PP
Or for the smallest change to your code:
.PP
.Vb 3
\&    my ( undef, $r ) = $client\->home_timeline;
\&    $r\->result; i            # same as before
\&    $r\->rate_limit_remaning; # same as before
.Ve
.PP
However, there is migration support for \fBWrapResult\fR. Call the constructor
with option \f(CW\*(C`wrap_result => 1\*(C'\fR and Twitter::API will return the context
object, only, for \s-1API\s0 calls. This should give you the same behavior you had
with \fBWrapResult\fR while you modify your code. Twitter::API will warn when this
option is used. You may disale warnings with
\&\f(CW\*(C`$ENV{TWITTER_API_NO_MIGRATION_WARNINGS} = 1\*(C'\fR.
.PP
If you are using any other Net::Twitter traits, please contact the author of
Twitter::API.  Additional traits may be added to Twitter::API or released as
separate distributions.
.PP
If you are using \f(CW\*(C`decode_html_entities => 1\*(C'\fR in Net::Twitter, drop that
option and add trait \fBDecodeHtmlEntities\fR. Traits \fBAppAuth\fR and
\&\fBRetryOnError\fR provide the same functionality in Twitter::API as their
Net::Twitter counterparts. So, no changes required, there, if you're using
them. (Although there is a change to one of \fBAppAuth\fR's methods. See the
\&\*(L"OAuth changes\*(R" discussion.)
.PP
NormalizeBooleans is something you'll probably want. See the
NormalizeBooleans documentation.
.PP
Enchilda just bundles ApiMethods, NormalizeBooleans, RetryOnError, and
DecodeHtmlEntities.
.SS "Other constructor options"
.IX Subsection "Other constructor options"
Drop option \f(CW\*(C`ssl => 1\*(C'\fR. It is no longer necessary. By default, all
connections use \s-1SSL.\s0
.PP
If you are setting \fBuseragent_lass\fR and/or \fBuseragent_args\fR to customize the
user agent, just construct your own pass it to new with \f(CW\*(C`user_agent =>
$custom_user_agent\*(C'\fR.
.PP
If you are using \fBua\fR to set a custom user agent, the attribute name has
changed to \fBusre_agent\fR. So, pass it to new with \f(CW\*(C`user_agent =>
$custom_user_agent\*(C'\fR.
.PP
By default, Twitter::API uses HTTP::Thin as its user agent. You should be
able to use any user agent you like, as long as it has a \fBrequest\fR method that
takes an HTTP::Request and returns an HTTP::Response.
.PP
If you used \fBclientname\fR, \fBclientver\fR, \fBclienturl\fR, or \fBuseragent\fR, see
\&\*(L"agent\*(R" in Twitter::API and \*(L"default_headers\*(R" in Twitter::API. If all you're after
is a custom User-Agent header, just pass \f(CW\*(C`agent => $user_agent_string\*(C'\fR.
It will be used for both User-Agent header and the X\-Twitter-Client header on
requests. If you want to include your own application version and url, pass
\&\f(CW\*(C`default_headers => \e%my_request_headers\*(C'\fR.
.SS "OAuth changes"
.IX Subsection "OAuth changes"
Net::Twitter saved request and access tokens in the client instance as part of
the 3\-legged OAuth handshake. That was a poor design decision. Twitter::API
returns request and access tokens to the caller. It is the caller's
responsibility to store and cache them appropriately. Hovever, transitional
support is provided, with client instance storage, so your code can run
unmodified while you make the transition.
.PP
The following methods exist only for migration from Net::Twitter and will be
removed in a future release. A warning is issued on each call to these methods.
To disable the warnings, set \f(CW\*(C`$ENV{TWITTER_API_NO_MIGRATION_WARNINGS} = 1\*(C'\fR.
.IP "\(bu" 4
\&\fBget_authentication_url\fR
.Sp
replace with oauth_authentication_url
  or oauth_request_token and
  oauth_authentication_url
.IP "\(bu" 4
\&\fBget_autorization_url\fR
.Sp
replace with oauth_authorization_url or
  oauth_request_token and
  oauth_authorization_url
.IP "\(bu" 4
\&\fBget_access_token\fR
.Sp
replace with oauth_access_token
.PP
If you are using the \fBAppAuth\fR trait, replace \fBrequest_access_token\fR calls
with \fBoauth2_token\fR calls. Method \fBoauth2_token\fR does not set the
\&\f(CW\*(C`access_token\*(C'\fR attribute. Method \f(CW\*(C`request_access_token\*(C'\fR is provided for
transitional support, only. It warns like the OAuth methods discussed above, and
it sets the \f(CW\*(C`access_token\*(C'\fR attribute so existing code should work as expected
during migration. It will be removed in a future release.
.SH "Migrating from Net::Twitter::Lite"
.IX Header "Migrating from Net::Twitter::Lite"
The discussion, above applies for Net::Twitter::Lite with a few exceptions.
.PP
Net::Twitter::Lite does not use traits. Change your constructor call from:
.PP
.Vb 1
\&    my $client = Net::Twitter::Lite::WithAPIv1_1\->new(%args);
.Ve
.PP
To:
.PP
.Vb 4
\&    my $client = Twitter::API\->new_with_traits(
\&        traits => [ qw/Migration ApiMethods/ ],
\&        %args,
\&    );
.Ve
.PP
If you're using the option \fBwrap_result\fR, see the discussion above about the
Net::Twitter WrapResult trait. There is migration support for \fBwrap_result\fR.
It will be removed in a future release.
.SH "AUTHOR"
.IX Header "AUTHOR"
Marc Mims <marc@questright.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015\-2018 by Marc Mims.
.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.