/wiki/ReleaseNotes.wiki

  1*Important note*
  2This release includes breaking changes compared to the 2.x series. These release notes will guide you through the process of updating your calling code.
  3----
  4The 3.0 and 3.1 releases mark a major transition. For starters, all methods use the API where possible. This means that return formats have changed in some cases. Likewise, some method calls have changed. Some of these still accept a backward-compatible form; this will be noted where applicable.
  5
  6==Breaking changes==
  7*Overview*
  8
  9 * `get_text()` now returns the page's wikitext. Blank pages return `""`; nonexistent pages return `undef`. These both evaluate to false; you can differentiate between them with `defined()`. `get_id()` now returns `undef` instead of `2` when there is no pageid (page is nonexistent or title is invalid).
 10 * All subs return `undef` when they encounter an error that is passed off to `_handle_api_error()`. Error details are still available in `$bot->{'error'}`.
 11 * `linksearch()` now uses keys `url` and `title` like the API does. This is to avoid confusion when using a callback hook, which is now exposed to callers. `linksearch()` now uses the API.
 12 * `login()`'s return values are reversed, and properly documented. Returns true for success; false for failure:
 13{{{
 14$bot->login($user, $pass) or die "Login failed\n"; # This is in accord with Perl standards
 15}}}
 16 * `what_links_here()` no longer handles transclusions. To get transclusions, use `list_transclusions()`. Also, key names are now `title` and `redirect` (defined when the page is a redirect; undefined otherwise).
 17 * `update_rc()` now accepts a hashref of options, and the hash structure returned is changed.
 18
 19===All methods===
 20*Overview*
 21Nearly all methods now return `undef` on failure.
 22
 23*Rationale*
 24Separating errors from returned data is important. If you require the error code or error details, they are available in `$bot->{'error'}->{'code'}` and `$bot->{'error'}->{'details'}` respectively.
 25
 26*Impact*
 27Any method calls which did not ignore the return value must now check for `undef`.
 28
 29====Example: `get_text()` and `get_pages()`====
 30*Overview*
 31These methods now return <code>undef</code> for non-existent pages instead of an error code.
 32
 33*Impact*
 34Any special cases you had for handling error codes must now look for <code>undef</code> instead. Calls involving pages which exist are unaffected.
 35
 36*new call*
 37{{{
 38my $text = $bot->get_text('Non-existent page');
 39print $text if defined($text);
 40
 41my @pages = ('Page 1', 'Page 2', 'Page 3');
 42my $thing = $bot->get_pages(\@pages);
 43foreach my $page (keys %$thing) {
 44    my $text = $thing->{$page};
 45    print "$text\n" if defined($text);
 46}
 47}}}
 48
 49*old-call*
 50{{{
 51my $text = $bot->get_text('Non-existent page');
 52print $text unless ($text eq "2");
 53
 54my @pages = ('Page 1', 'Page 2', 'Page 3');
 55my $thing = $bot->get_pages(\@pages);
 56foreach my $page (keys %$thing) {
 57    my $text = $thing->{$page};
 58    print "$text\n" unless ($text eq "2");
 59}
 60}}}
 61
 62===`login()`===
 63*Overview*
 64This method now returns true on success; false on failure.
 65
 66*Rationale*
 67In Perl, non-zero is true and means success. Even the syscall wrappings in Perl follow this convention.
 68
 69*Impact*
 70All calls to `login()` which checked return values must be updated.
 71
 72*new-call*
 73{{{
 74$bot->login({
 75    username => "Mike's bot account",
 76    password => $password,
 77}) or die "Couldn't log in";
 78}}}
 79
 80*old-call*
 81{{{
 82my $failure = $bot->login("Mike's bot account", $password);
 83die "Couldn't log in" if $failure;
 84}}}
 85
 86===`linksearch()`===
 87*Overview*
 88This method now uses keys `url` and `title`
 89
 90*Rationale*
 91This reduces confusion in cases where the programmer wishes to use a callback hook to do incremental processing. Without this change, accessing data would have been done with two different sets of keys.
 92
 93*Impact*
 94Any call needs to have the key names updated.
 95
 96*new-call*
 97{{{
 98my $options = { max => 10, }; # I only want some results
 99my @links = $bot->linksearch("slashdot.org", 1, undef, $options);
100foreach my $hash (@links) {
101    my $url = $hash->{'url'};
102    my $page = $hash->{'title'};
103    print "$page: $url\n";
104}
105
106# Use a callback:
107my $options = { hook => \&mysub, }; # I want to do incremental processing
108$bot->linksearch("slashdot.org", 1, undef, $options) or die;
109sub mysub {
110    my ($res) = @_;
111    foreach my $hashref (@$res) {
112        my $url   = $hashref->{'url'};
113        my $title = $hashref->{'title'};
114        print "$title: $url\n";
115    }
116}
117}}}
118
119*old-call*
120{{{
121my @links = $bot->linksearch("slashdot.org", 1) or die;
122foreach my $hashref (@links) {
123    my $link = $hashref->{'link'};
124    my $page = $hashref->{'page'};
125    print "$page: $link\n";
126}
127}}}
128
129===`what_links_here()`===
130*Overview*
131This method now uses keys `title` and `redirect`. It also returns _only_ links (incl. redirects). Transclusions are handled by `list_transclusions()`.
132
133*Rationale*
134This reduces confusion in cases where the programmer wishes to use a callback hook to do incremental processing. Without this change, accessing data would have been done with two different sets of keys.
135
136*Impact*
137Any call to this method needs to be evaluated as to whether it needs to be replaced with or supplemented by a call to `list_transclusions()`. Also, key names must be updated.
138
139*new-call*
140{{{
141my @links = $bot->what_links_here("Meta:Sandbox", undef, 1, {hook=>\&mysub});
142sub mysub{
143    my ($res) = @_;
144    foreach my $hash (@$res) {
145        my $title = $hash->{'title'};
146        my $is_redir = $hash->{'redirect'};
147        print "Redirect: $title\n" if $is_redir;
148        print "Page: $title\n" unless $is_redir;
149    }
150}
151}}}
152
153==Other changes==
154See the `Changes` file for other changes which are non-breaking (for example, new call styles but which are backward-compatible, and new features).