TITLE

SUBTITLE

Callables can be stored in C<&>-sigiled containers, the default type constraint
of such a container is C<Callable>.


comment

my &a = {;}; # Empty block needs a semicolon
my &b = -> {};
my &c = sub () {};
sub foo() {};
my &d = &foo;


head

method CALL-ME(Callable:D $self: |arguments)


This method is required for the L«C<( )> postcircumfix operator|/language/operators#postcircumfix_(_)»
and the L«C<.( )> postcircumfix operator|/language/operators#index-entry-.(_)». It's what makes
an object actually call-able and needs to be overloaded to let a given object
act like a routine. If the object needs to be stored in an C<&>-sigiled
container, it has to implement Callable.


class A does Callable {
    submethod CALL-ME(|c){ 'called' }
}
my &a = A;
say a(); # OUTPUT: «called␤»


Applying the C<Callable> role is not a requirement to make an object callable;
if a class simply wants to add subroutine-like semantics in a regular scalar
container, the submethod C<CALL-ME> can be used for that.


class A {
    has @.values;
    submethod CALL-ME(Int $x where 0 <= * < @!values.elems) {
        @!values[$x]
    }
}
my $a = A.new: values => [4,5,6,7];
say $a(2); # OUTPUT: «6␤»


Throws L<C<X::Cannot::Capture>|/type/X::Cannot::Capture>.


root

Object that can be treated as a date


role Dateish


Distribution


role Distribution


Support for character encodings.


role Encoding


Iterators that can predict number of values


role PredictiveIterator


Provide leading/trailing doc functionality


class RakuAST::Doc::DeclaratorTarget


Number stored as numerator and denominator


role Rational


Non-complex number


role Real


String or object that can act as a string


role Stringy


Invocable code object


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

role Callable


A C<CallFrame> will be usually captured from the
current state of a program using the L<callframe|/routine/callframe> subroutine.


my $frame = callframe;
say "The above line of code ran at {$frame.file}:{$frame.line}.";


With no arguments the callframe will give you frame information for the line
calling C<callframe>. The file and line annotations will be identical to those
in L«C<$?FILE>|/language/variables#Compile-time_variables» and
L«C<$?LINE>|/language/variables#Compile-time_variables».


You may, however, pass a number to C<callframe> to specify a different frame
level. A positive number will move upward through the levels of frame. A
negative number will move downward into the C<callframe> method and class itself
at the point at which they are running to construct this information for you.


The frames themselves do not necessarily match only method or subroutine calls.
Raku constructs a frames for blocks and such as well, so if you need a callframe
for a particular method call, do not assume it is a fixed number of levels up.


Each frame stores L<annotations|/routine/annotations>, including the
L<file|/routine/file> and L<line|/routine/line> annotations, which have
convenience methods for accessing them directly. You can also retrieve a
reference to the code block of the currently executing frame using the
L<code|/routine/code> method.  The frame also captures all lexical variables
stored with the frame, which are available by calling L<my|/routine/my> on the
frame object.


Here's a short example that will find the calling routine and print the package
of the caller using the C<callframe> interface.


sub calling-frame() {
    for 1..* -> $level {
        given callframe($level) -> $frame {
            when $frame ~~ CallFrame {
                    next unless $frame.code ~~ Routine;
                    say $frame.code.package;
                    last;
            }
            default {
                    say "no calling routine or method found";
                    last;
            }
        }
    }
}


If you just need to trace caller information, L<C<Backtrace>|/type/Backtrace> may
provide a better means of getting it. C<CallFrame>
contains more information about a specific frame, but provides a tedious
interface for enumerating a call stack.


B<Note> From version 6.d, C<.raku> (C<.perl> before version 2019.11) can be
called on C<CallFrame>.


Return the callable code for the current block. When called on the object
returned by C<callframe(0)>, this will be the same value found in
L«C<&?BLOCK>|/language/variables#Compile-time_variables».


code

The C<$frame> variable will hold the L<C<Code>|/type/Code> for the block inside the loop in
this case.


This is a shortcut for looking up the C<file> annotation. Therefore, the
following code prints C<True>.


my $frame = callframe(0);
say $frame.file eq $frame.annotations<file>;


This is a shortcut for looking up the C<line> annotation. For example, the
following two calls are identical.


say callframe(1).line;
say callframe(1).annotations<line>;


Returns a L<C<Map>|/type/Map> containing the invocants annotations, i.e. C<line>
and C<file>. An easier way to get hold of the annotation information is to use
one of the convenience methods instead.


say callframe.annotations.^name;                   # OUTPUT: «Map␤»
say callframe.annotations<file> eq callframe.file; # OUTPUT: «True␤»


Return a L<C<Hash>|/type/Hash> that names all the variables and their values
associated with the lexical scope of the frame.


sub some-value {
    my $the-answer = 42;
    callframe(0);
}


my $frame = some-value();
say $frame.my<$the-answer>; # OUTPUT: «42␤»


Returns a C<CallFrame> object for the given level. If no level
is given, the default level is 0. Positive levels move up the frame stack and
negative levels move down (into the call to C<callframe> and deeper).


Returns L<C<Mu>|/type/Mu> if there is no call information for the given level.
Negative levels may result in an exception.


Native integer


class int


Dual value number and string


class Allomorph


Thing/object


class Any


Abstract representation of a piece of source code


class AST


Integer (native storage at the platform's atomic operation size)


class atomicint


Code object with its own lexical scope


class Block


Code object


class Code


Encapsulates instructions about how strings should be sorted


class Collation


Information related to the compiler that is being used


class Compiler


Complex number


class Complex


Dual value complex number and string


class ComplexStr


Object that can be treated as both a string and number


class Cool


Scheduler that synchronously executes code on the current thread


class CurrentThreadScheduler


Calendar date


class Date


Calendar date with time


class DateTime


Distribution::Hash


class Distribution::Hash


Distribution::Locally


class Distribution::Locally


Distribution::Path


class Distribution::Path


Every one of the resources installed with a distribution


class Distribution::Resource


Length of time


class Duration


Management of available encodings


class Encoding::Registry


Rational number (arbitrary-precision)


class FatRat


Rakudo-specific class that wraps around code in other languages (generally NQP)


class ForeignCode


Convert values to a string given a format specification


class Format


Produce Callable for given format specification


class Formatter


An object for performing batches of work in parallel with ordered
output


class HyperSeq


Placeholder for multiple unspecified values/arguments


class HyperWhatever


Specific moment in time


class Instant


Integer (arbitrary-precision)


class Int


Dual value integer and string


class IntStr


Logical superposition of values


class Junction


Tagged location in the source code


class Label


A non-blocking, non-re-entrant, mutual exclusion lock


class Lock::Async


Compile-time routine


class Macro


Member function


class Method


The root of the Raku type hierarchy.


class Mu


Absence of a value or a benign failure


class Nil


Floating-point number


class Num


Number or object that can act as a number


role Numeric


Dual value floating-point number and string


class NumStr


Unique identification for an object


class ObjAt


Element of a Signature


class Parameter


Perl related information


class Perl


Item container with custom storage and retrieval


class Proxy


Performs batches of work in parallel without respecting original
order.


class RaceSeq


Raku related information


class Raku


Namespace for holding RakuAST related classes


package RakuAST


Contains the information of a RakuDoc block


class RakuAST::Doc::Block


Contains the declarator docs of a RakuAST object


class RakuAST::Doc::Declarator


Contains the information about RakuDoc markup


class RakuAST::Doc::Markup


Contains the information about a RakuDoc paragraph


class RakuAST::Doc::Paragraph


Rational number (limited-precision)


class Rat


Dual value rational number and string


class RatStr


Code object with its own lexical scope and return handling


class Routine


Holds all information needed to unwrap a wrapped routine.


class Routine::WrapHandle


A mostly transparent container used for indirections


class Scalar


Parameter list pattern


class Signature


String of characters


class Str


Contains the result of a string transformation.


class StrDistance


Subroutine


class Sub


Member function that is not inherited by subclasses


class Submethod


Collect performance state for analysis


class Telemetry


Instrument for collecting Thread data


class Telemetry::Instrument::Thread


Instrument for collecting ThreadPoolScheduler data


class Telemetry::Instrument::ThreadPool


Instrument for collecting getrusage data


class Telemetry::Instrument::Usage


Performance data over a period


class Telemetry::Period


Telemetry instrument pod


class Telemetry::Sampler


Unsigned integer (arbitrary-precision)


Subset UInt


Unique identification for value types


class ValueObjAt


Captures the current frame state


class CallFrame


The Raku Knowledge Base


role Callable

Methods

method CALL-ME

method Capture

See Also