Perlguts: Minor queries regarding the "Ref-counted arg stack" documentation

[richardleach]

Where
pod/perlguts.pod

Description

1. The "Reference-counted argument stack" section discusses changes to the stack previously referred to as the "value" stack. We should pick either "argument stack" or "value stack" and stick to it in core documentation to avoid unnecessary reader confusion. (I dunno which, or else would have raised a PR.)
2. In the "(Re)writing a PP function using the rpp_() API" section, it says that rpp_try_AMAGIC_1() is akin to tryAMAGICun_MG(), but it looks the old macro cannot just be switched to the new one, the return value of rpp_try_AMAGIC_1() seems to always have to be checked to see if it is true, and if so, an immediate return is required.

i.e.

tryAMAGICun_MG(neg_amg, AMGf_numeric);

becomes:

if (rpp_try_AMAGIC_1(neg_amg, AMGf_numeric))
    return NORMAL;

I don't know if that will always be the case and if it should be documented here if so? (Or if this will be a moot point if we make all pp functions RC-aware relatively quickly.)

[iabyn]

On Thu, Aug 31, 2023 at 03:05:13PM -0700, Richard Leach wrote: **Where** pod/perlguts.pod **Description** 1. The "**Reference-counted argument stack**" section discusses changes to the stack previously referred to as the "value" stack. We should pick either "argument stack" or "value stack" and stick to it in core documentation to avoid unnecessary reader confusion. (I dunno which, or else would have raised a PR.)

I've always referred to it as the "argument stack". I'm open to an alternative consensus.

2. In the "**(Re)writing a PP function using the rpp_() API**" section, it says that `rpp_try_AMAGIC_1()` is akin to `tryAMAGICun_MG()`, but it looks the old macro cannot just be switched to the new one, the return value of `rpp_try_AMAGIC_1()` seems to always have to be checked to see if it is true, and if so, an immediate return is required.

Looking at my soon-to-be-pushed branch, there are 48 usages of the new currently rpp_try_AMAGIC_1/1 functions. So there will be many examples. The text says: The macros which appear at the start of many PP functions to check for unary or binary op overloading (among other things) have been replaced with rpp_try_AMAGIC_1() and _2() inline functions, which now rely on the calling PP function to choose whether to return immediately rather than the return being hidden away in the macro. so it's documented. The return was always there, it was just hidden away within the old tryAMAGICun_MG() macro. The new API just makes it explicit.

…

-- In economics, the exam questions are the same every year. They just change the answers.

[leonerd]

I've always referred to it as the "argument stack". I'm open to an alternative consensus.

Ah I think "value stack" might have been my invention when I wrote about "the stacks", first in a blog post and second followed it up by expanding on the docs in perlguts.pod. If the phrase "argument stack" is already established, I'd be happy to rename it there.

[richardleach]

Thanks for the clarifications.

• I think I'd seen "argument stack" mentioned outside of perlguts too, so standardizing on that seems good.
• There doesn't seem to be any need to expand on the explicit return text.