Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kentnl/call-from

Call functions/methods with a fake caller()
https://github.com/kentnl/call-from

Last synced: 4 days ago
JSON representation

Call functions/methods with a fake caller()

Awesome Lists containing this project

README 

        
=head1 NAME



Call::From - Call functions/methods with a fake caller()



=head1 SYNOPSIS



  use Call::From qw( call_method_from );



  my $proxy = call_method_from('Fake::Namespace');



  Some::Class->$proxy( method_name => @args ); # Some::Class->method_name( @args ) with caller() faked.



=head1 DESCRIPTION



Call::From contains a collection of short utility functions to ease calling

functions and methods from faked calling contexts without requiring arcane

knowledge of Perl eval tricks.



=head1 EXPORTS



The following functions and variables are exportable on request.



=head2 C



  my $function = call_method_from( CONTEXT_SPEC );

  $invocant->$function( method_name => @args );



Alternatively:



  $invocant->${ \call_method_from( CONTEXT_SPEC ) }( method_name => @args );



=head2 C



  my $function = call_function_from( CONTEXT_SPEC );

  $function->( "Class::Name::function" , @args );



Alternatively:



  my $function = call_function_from( CONTEXT_SPEC );

  $function->( Class::Name->can('function') , @args );



Or



  call_function_from( CONTEXT_SPEC )->( "Class::Name::function", @args );



=head2 C<$_call_from>



  $invocant->$_call_from( CONTEXT_SPEC, method_name => @args );



=head1 SPECIFYING A CALLING CONTEXT



Calling contexts can be specified in a number of ways.



=head2 Numeric Call Levels



In functions like C, you're most likely wanting to chain caller

meta-data from whoever is calling C



So for instance:



  package Bar;

  sub import {

    my $proxy = call_method_from(1);

    vars->$proxy( import => 'world');

  }

  package Foo;

  Bar->import();



Would trick `vars` to seeing `Foo` as being the calling C, with the line

of the C<< Bar->import() >> call being the C and C of the apparent

caller in C



This syntax is essentially shorthand for



  call_method_from([ caller(1) ])



=head2 Package Name Caller



Strings describing the name of the calling package allows you to conveniently

call functions from arbitrary name-spaces for C reasons, while

preserving the C and C context in C stack traces.



  package Bar;

  sub import {

    vars->${\call_method_from('Quux')}( import => 'world');

  }

  package Foo;

  Bar->import();



This example would call C<< vars->import('world') >> from inside the C

package, while C and C data would still indicate an origin inside

C ( on the line that C was called on )



This syntax is essentially shorthand for:



  call_method_from([ $package, __FILE__, __LINE__ ])



=head2 ArrayRef of Caller Info



Array References in the form



  [ $package, $file, $line ]



Can be passed as a C. All fields are optional and will be

supplemented with the contents of the calling context when missing.



Subsequently:



  call_method_from([])

    == call_method_from()

    == call_method_from([__PACKAGE__, __FILE__, __LINE__])



  call_method_from(['Package'])

    == call_method_from('Package')

    == call_method_from(['Package', __FILE__, __LINE__])



  call_method_from(['Package','file'])

    == call_method_from(['Package','file', __LINE__])



=head1 SEE ALSO



The following modules are similar in some way to C



=over 4



=item * L<< C|Import::Into >>



C is really inspiration that this module borrowed from. It contains the elegant

trick of using C to compile a kind of C or L<< C|https://en.wikipedia.org/wiki/Thunk >>

which contained the magical C spice that allows this behavior to work.



As such, this module had a big help from the authors and maintainers of C in mimicking

and generalizing its utility in contexts other than C



If C did not exist, you could use this module in its place:



    require Module;

    Module->${\call_method_from( $Into_Package )}( import => @IMPORT_ARGS );



However, it does exist, and should you need such a functionality, it is recommended instead of this module.



=item * L<< C|Scope::Upper >>



This module is similar to C in that it can be used to "hide" who C is from

a calling context.



However, C is more fancy, and uses Perl Guts in order to be able to actually hide

the entire stack frame, regardless of how many frames up you look with C.



C is much simpler in that it can only I stack frames to the caller, and then,

it adds redundant frames in performing its task.



This is sufficient for fooling something that only uses a simple C call, but is insufficient

if you need to hide entire call chains. In fact, I personally see it as a feature that you can still see

the true caller history in a full stack-trace, because the last place you want to be fooled is when you're debugging

whether or not you've been fooled.



But its worth pointing out that at the time of this writing, changes are pending in Perl 5 to L<< rework the entire

stack system|http://www.nntp.perl.org/group/perl.perl5.porters/2016/01/msg233631.html >>.



This change L<< may break C|http://www.nntp.perl.org/group/perl.perl5.porters/2016/01/msg233633.html >>

in ways that might not be fixable.



In the event this happens, C might be a suitable alternative if you only need to spoof a stack frame

and don't care that the full stack is still there.



=back



=head1 AUTHOR



Kent Fredric 



=head1 COPYRIGHT AND LICENSE



This software is copyright (c) 2016 by Kent Fredric .



This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.



=cut