Add a work-around for older Perl's that need @{^CAPTURE}

[scottchiefbaker]

I was bit by a bug wherein I was accessing @{^CAPTURE} on Perl v5.16 which does not have this variable. This PR adds some documentation to allow a user a work-around if they are in the same situation.

[scottchiefbaker]

I'm not sure if this is the type of thing we want/need in the documentation, but it would have saved me about an hour of hair pulling if it were documented.

[scottchiefbaker]

@mauke pointed out on IRC that this functionality is also in Data::Munge. Their implementation is a little hacky, shorter, and harder to read. For completeness I'm including it here:

sub get_captures {
    no strict 'refs';
    map $$_, 1 .. $#+
}

We could include this in the documentation if my function is too long/wordy.

[mauke]

At least in older Perls, the use of $& slows down all regex matches everywhere in the program.

[mauke]

Why use a C-style for loop here? This is a simple counting loop, so

for my $i (1 .. $#-) {

expresses the idea more directly (and slightly more efficient).

[scottchiefbaker]

Agree to disagree here... $#- is too much punctuation and not as easily understood.

I've been using Perl for 20+ years and I just learned about # syntax in arrays today.

[mauke]

If you don't like $#-, @- - 1 is the same thing. (Doesn't really look better with @-, though, IMHO).

[mauke]

my @captures;
for (RANGE) {
    push(@captures, ...)
}

could also be written as

my @captures = map {
    ...
} RANGE;

[scottchiefbaker]

Upon further reflection I think it makes sense to use the format that @mauke proposed in Data::Munge. I would however like to expand it slightly so it's more clear and readable for novices. Since the intention is to put it in the documentation I think readability is key here. Here is my expanded version:

sub get_captures {
    no strict 'refs';

    my $last_idx = scalar(@-) - 1;
    my @arr      = 1 .. $last_idx;
    my @ret      = map { $$_; } @arr;

    return @ret;
}

[khwilliamson]

I have quibbles about the commit messages, in particular the titles. A title should have enough information for someone scanning a log of commits to be able to quickly determine if this is potentially a commit that has bearing on what they're scanning for. For that, the title should include what the commit pertains to. For small specific changes like this, noting in the title that it is perlvar that is affected will tell me immediately if I should look further into it or not. I have adopted the convention for myself to place the file name at the beginning of the message, like

perlvar: Use a faster/shorter version of get_captures()

Something that affects more things wouldn't have the file name, but should indicate what area, as explicitly as possible, is affected.

A commit message should answer the classic questions "Who, what, when, where, and why". The who and when are automatically filled in for you by the system, and appear adjacent to the title, but they are less important than the other three. A title should give at least a hint towards those. So "perlvar: Fix a typo" is better than "perlvar: Fix a word" because it more explicitly says what is wrong that needs to be fixed.

[scottchiefbaker]

@khwilliamson all that makes sense to me. Usually that all gets corrected on the squash and merge phase. Unless you'd like me to rebase and squash all these down to a single commit before then.

[khwilliamson]

On 12/6/23 09:11, Scott Baker wrote: @khwilliamson <https://github.com/khwilliamson> all that makes sense to me. Usually that all gets corrected on the squash and merge phase. Unless you'd like me to rebase and squash all these down to a single commit before then.

Just as long as it doesn't get merged with uncorrected wording is fine with me

…

— Reply to this email directly, view it on GitHub <#21678 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA2DH7GJ6Y6VROINQM6I5DYICKMPAVCNFSM6AAAAABAAJXA5SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNBTGIYTIOBWHE>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[scottchiefbaker]

Ping... what's next on this? Is this something we need in the docs?

[khwilliamson]

I think now is a good time to squash and make sure the commit msg is good. Then I would look at the full result.

[scottchiefbaker]

@khwilliamson I have squashed

[scottchiefbaker]

@khwilliamson Thank you sir!