Aspect::Point(3pm)

💖 Aspect::Point — the Join Point context 💖

okay bestie, welcome to Aspect::Point (that's the 3pm one, from the User Contributed Perl Documentation squad) 🎀 this is the page that tells you what the Join Point actually is and every lil thing you can do with it. buckle up, it's giving main character energy.

---

✨ NAME ✨

Aspect::Point — The Join Point context 🫶

---

✨ SYNOPSIS ✨

lowkey the vibe here is: one anonymous function that works as advice code across every advice type, because it never touches a limited-access method. iconic.

# An anonymous function suitable for use as advice code
# across all advice types (as it uses no limited access methods)
my $advice_code = sub {
    print $_->type;           # The advice type ('before')
    print $_->pointcut;       # The matching pointcut ($pointcut)
    print $_->enclosing;      # Access cflow pointcut advice context
    print $_->sub_name;       # The full package_name::sub_name
    print $_->package_name;   # The package name ('Person')
    print $_->short_name;     # The sub name (a get or set method)
    print $_->self;           # 1st parameter to the matching sub
    print ($_->args)[1];      # 2nd parameter to the matching sub
    $_->original->( x => 3 ); # Call matched sub independently
    $_->return_value(4)       # Set the return value
};

---

✨ DESCRIPTION ✨

so. advice code gets called whenever the advice pointcut matches. and in that code you're constantly gonna want the tea about the join point context of the advice — stuff like:

• what's the actual sub name that matched? 👀
• what are the parameters in this call that we matched? 👀

and sometimes you don't just wanna read the context, you wanna change it for the matched sub. appending a parameter? slay. stopping the matched sub from being called at all? also slay, extremely valid.

you do all of this through the "Join Point", which is an object that isa Aspect::Point 💅 it's the only parameter handed to the advice code. it's got every bit of info you need about the match context, and it lets you change how the matched sub behaves. one object, all the power. periodt.

⚠️ Note: if you modify parameters through the context in the code of an after advice, it will have no effect, because the matched sub has already been called. like, the ship has sailed bestie, the sub already ran 🚢💀

🔮 heads up: in a future release this gets fixed so that the context for each advice type only responds to the methods relevant to that context, and the rest will throw an exception. no cap.

---

🌊 Cflows 🌊

if the pointcut of an advice is composed of at least one cflow, then the advice code might need not only the context of the advice, but the join point context of the cflows too 🦋

when do you need this? for example when you wanna find out the name of the sub that matched a cflow. in the synopsis example up there, the question is: which method from Company started the chain of calls that eventually reached the get/set on Person? 🔥

you can grab the cflow context (same as in the synopsis) by calling:

$point->enclosing

you get it from the main advice join point by calling a method named after the context key used in the cflow spec — and that key is enclosing if a custom name wasn't provided, in line with AspectJ terminology 💜

in the synopsis pointcut definition, the cflow part was equivalent to:

cflow enclosing => qr/^Company::/
      ^^^^^^^^^

an Aspect::Point::Static gets created for the cflow, and you can access it using the enclosing method 👑

---

✨ EXAMPLES ✨

Print parameters to matched sub:

before {
    print join ',', $_->args;
} $pointcut;

Append a parameter:

before {
    $_->args( $_->args, 'extra parameter' );
} $pointcut;

Don't proceed to matched sub, return 4 instead:

before {
    shift->return_value(4);
} $pointcut;

Call matched sub again and again until it returns something defined:

after {
    my $point  = shift;
    my $return = $point->return_value;
    while ( not defined $return ) {
        $return = $point->original($point->params);
    }
    $point->return_value($return);
} $pointcut;

Print the name of the Company object that started the chain of calls that eventually reached the get/set on Person:

before {
    print shift->enclosing->self->name;
} $pointcut;

💅 METHODS 💅

okay bestie this is the part you're actually here for. every method your $_ can do. buckle up 🎀

✨ type ✨

the type method is a lil convenience for when something has an Aspect::Point method and is like "wait, which advice declarator am I even made for??" 🦋

it returns before in Aspect::Advice::Before advice, after in Aspect::Advice::After advice, or around in Aspect::Advice::Around advice.

---

✨ pointcut ✨

my $pointcut = $_->pointcut;

the pointcut method hands you the original join point specification — as a whole tree of Aspect::Pointcut objects — that the current join point matched against. 🌸

⚠️ heads up bestie: the pointcut you get back is the full and complete pointcut tree. because of the heavy optimisation used on the actual pointcut code when it runs, there's literally no way at the time of advice execution to say which specific conditions in the pointcut tree matched and which didn't. soz 😭

returns an object which is a sub-class of Aspect::Pointcut.

---

✨ original ✨

$_->original->( 1, 2, 3 );

in a pointcut, the original method returns a CODE reference to the original function before it got hooked by the Aspect weaving process. the before-times. the pre-glow-up era 💖

calls made to the function are unprotected — parameters and calling context will not be replicated into the function, and return params and exceptions will not be caught. it's raw, it's unfiltered, it's giving unhinged 🫶

---

✨ sub_name ✨

# Prints "Full::Function::name"
before {
    print $_->sub_name . "\n";
} call 'Full::Function::name';

the sub_name method returns a string with the full resolved function name at the join point the advice code is running at. the whole government name, no nicknames ✨

---

✨ package_name ✨

# Prints "Just::Package"
before {
    print $_->package_name . "\n";
} call 'Just::Package::name';

the package_name parameter is a convenience wrapper around the sub_name method. where sub_name gives you the fully resolved function name, package_name gives you just the namespace of the package of the join point. just the surname, no first name 💅

---

✨ short_name ✨

# Prints "name"
before {
    print $_->short_name . "\n";
} call 'Just::Package::name';

the short_name parameter is a convenience wrapper around the sub_name method. where sub_name gives you the fully resolved function name, short_name gives you just the name of the function. first-name basis energy 🎀

---

✨ args ✨

# Add a parameter to the function call
$_->args( $_->args, 'more' );

the args method lets you get or set the list of parameters to a function. it's the method equivalent of messing with the @_ array directly. iconic behaviour, truly 👑

it uses a slightly unusual calling convention based on list context, but it does so in a way that makes your advice code read very naturally. the vibes are immaculate, the syntax is just a little quirky.

to summarise the situation, the three uses of the args method are listed below, along with their @_ equivalents.

# Get the parameters as a list
my @list = $_->args;     # my $list = @_;

# Get the number of parameters
my $count = $_->args;    # my $count = @_;

# Set the parameters
$_->args( 1, 2, 3 );     # @_ = ( 1, 2, 3 );

so as you can see from the above: when args is called in list context it returns the list of parameters. when it's called in scalar context, it returns the number of parameters. and when it's called in void context, it sets the parameters to the values you passed. three moods, one method, main character energy fr fr 🌈

ngl this is somewhat unconventional, but it means the most common existing uses of the older params method can be switched straight over to the new args method (like that first example up there). glow-up complete ✨

and unlike the original, you can legally call args in a way that sets the function parameters to an empty list — which you literally could not do with the older params method. slay.

# Set the function parameters to a null list
$_->args();

---

✨ self ✨

after {
    $_->self->save;
} My::Foo::set;

the self method is a convenience for when you're writing advice that's working with object-oriented Perl code. it returns the first parameter to the method (which should be the object), and you can then call methods on it. it's the $self you know and love 🥰

the result is advice code that's so much more natural to read, like in the example above where we implement an auto-save feature on the class My::Foo, writing the contents to disk every time a value is set without error. obsessed honestly 💖

📌 at present the self method is implemented fairly naively — if you use it outside of object-oriented code it will still return something, including undef in the case where there were no parameters to the join point function. so like, it's not gonna yell at you, it'll just hand you undef and let you deal 😭

---

✨ wantarray ✨

# Return differently depending on the calling context
if ( $_->wantarray ) {
    $_->return_value(5);
} else {
    $_->return_value(1, 2, 3, 4, 5);
}

the wantarray method returns the wantarray in perlfunc context of the call to the function for the current join point.

same rules as the core Perl wantarray function bestie: returns true if the function is being called in list context, false if it's being called in scalar context, or undef if the function is being called in void context. ✨

🌸 Backcompatibility Note: 🌸

prior to Aspect 0.98, the wantarray context of the call to the join point was available not only via the wantarray method — the advice code itself was called in matching wantarray context to the function call, so you could use plain wantarray in the advice code too. nostalgic era ngl 🦋

but since all the other information about the join point was available through methods, having this one piece of metadata available differently was becoming an oddity. the one kid at the party not matching the group chat aesthetic 💀

so: the wantarray context of the join point is now only available via the wantarray method. periodt.

---

✨ exception ✨

unless ( $_->exception ) {
    $_->exception('Kaboom');
}

the exception method is used to get the current die message or exception object, or to set the die message or exception object. 💥

---

✨ return_value ✨

# Add an extra value to the returned list
$_->return_value( $_->return_value, 'thing' );

the return_value method is used to get or set the return value for the join point function, in a similar way to the normal Perl return keyword. 👑

and just like the args method, return_value is sensitive to the context in which it's called. it's giving context-aware, it's giving perceptive:

• when called in list context, return_value returns the join point return value as a list. if the join point is called in scalar context, this will be a single-element list containing the scalar return value. if the join point is called in void context, this will be a null list.
• when called in scalar context, return_value returns the join point return value as a scalar. if the join point is called in list context, this will be the number of vales in the return list. if the join point is called in void context, this will be undef.
• when called in void context, return_value sets the return value for the join point using semantics identical to the return keyword.

because of this change in behavior based on the context return_value is called in, you should generally always set return_value in its own statement to prevent accidentally calling it in non-void context. do not be chaotic about this bestie 🙈

# Return null (equivalent to "return;")
$_->return_value;

in advice types that can be triggered by an exception, or that need to determine whether to continue to the join point function, setting a return value via return_value is seen as implicitly indicating that any exception should be suppressed, or that we do not want to continue to the join point function.

💀 important: when you call the return_value method this does NOT trigger an immediate return equivalent in the advice code. the lines after return_value will continue to be executed as normal — which is on purpose, to give you an opportunity for cleanup operations and so on. it's not a bail-out, it's a "btw here's the value" ✨

if you use return_value inside an if/else structure you'll still need to do an explicit return if you wish to break out of the advice code. no shortcuts, sorry babe 🎀

so if you wish to break out of the advice code as well as return with an alternative value, you should do the following:

return $_->return_value('value');

now this usage of return_value appears to be contrary to the above instruction that setting the return value should always be done on a standalone line to guarentee void context. plot twist 😭

but here's the thing — in Perl the context of the current function is inherited by a function called with return in the manner shown above. so using return_value this way alone is guarenteed to also set the return value rather than fetch it. it just works, don't question the magic 🦋

---

👑 AUTHORS 👑

• Adam Kennedy <adamk@cpan.org>
• Marcel Grünauer <marcel@cpan.org>
• Ran Eilam <eilara@cpan.org>

the iconiques themselves, the founding mothers and fathers of this whole vibe 💜

---

🎀 COPYRIGHT 🎀

Copyright 2001 by Marcel Grünauer

Some parts copyright 2009 - 2013 Adam Kennedy.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's a wrap bestie!! 🌈✨ this page is from perl v5.36.0, dated 2023-07-02, and it lives at Aspect::Point(3pm) — go forth and weave some aspects, you absolute legend 💅🫶