NAME

Sub::Called - get information about how the subroutine is called

VERSION

Version 0.03

SYNOPSIS

    use Sub::Called;
    
    sub test {
        if( Sub::Called::with_ampersand() ){
            print "you called this subroutine this way: &test\n",
                  "note that this disables prototypes!\n";
        }
    }


    use Sub::Called 'already_called', 'not_called';
    
    sub user {
        unless (already_called) {   # only gets called once
            My::Fixtures::Users->load;
        }
        ...
    }
    
    sub schema {
        if ( not_called ) {
            # setup schema
        }
        else {
            return $schema;
        }
    }

EXPORTS

There are no subroutines exported by default, but you can export all subroutines explicitly

  use Sub::Called qw(with_ampersand already_called not_called);

already_called

This function must be called from inside a subroutine. It will return false if the subroutine has not yet been called. It will only return false once.

This subroutine is only exported on demand.

not_called

This function must be called from inside a subroutine. It returns the opposite value of already_called. Aside from this, there is no difference. You may find aesthetically more pleasing.

This subroutine is only exported on demand.

with_ampersand

This function must be called from inside a subroutine. It returns 1 if the subroutine was called with an ampersand (e.g. &subroutine()).

This subroutine is only exported on demand.

FUNCTIONS

with_ampersand

already_called

not_called

LIMITATIONS / TODO

There are limitations and I don't know if I can solve these "problems". So this section is also named "TODO". If you know a solution for any of these limitations, please let me know.

Subroutine References

It seems that there are some problems with subroutine references.

This may not work:

  sub test2 {
      if( Sub::Called::with_ampersand() ){
          die "die hard";
      }
  };
    
  my $sub2 = main->can( 'test2' );
  &$sub2();

Inside a module

If you call subroutines in a module but outside any subroutine (so the subroutine calls are executed when the module is loaded), I cannot give a correct answer ;-)

  package Check;
  
  use strict;
  use warnings;
  use Sub::Called qw(with_ampersand);
  
  &test;
  
  sub test {
      if( with_ampersand() ){
          print "yada yada yada\n";
      }
  }

AUTHOR

Renee Baecker, <module at renee-baecker.de>

Curtis "Ovid" Poe, <ovid at cpan.org>

BUGS

Please report any bugs or feature requests to bug-sub-called at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Called. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Sub::Called

You can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Sub-Called

• CPAN Ratings

  http://cpanratings.perl.org/d/Sub-Called

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sub-Called

• Search CPAN

  http://search.cpan.org/dist/Sub-Called

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Renee Baecker, Curtis "Ovid" Poe, all rights reserved.

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