File Coverage

blib/lib/mem.pm

Criterion	Covered	Total	%
statement	12	12	100.0
branch	5	8	62.5
condition	2	2	100.0
subroutine	2	2	100.0
pod			n/a
total	21	24	87.5

#!/usr/bin/perl -w
use strict;
#does nothing if run!
#

package mem;
  our $VERSION='0.4.5';

	our %os2sep = ( Wi => "\x{5c}", MS => "\x{5c}" );

	sub sep_detect() {
#		my $OS = substr(($ENV{OS} || $^O),0,2);
#		defined $os2sep{$OS} ? $os2sep{$OS} :
		'/';
	}

  # RCS $Revision: 1.7 $ $Date: 2013-12-16 13:21:47-08 $
	# 0.4.5		- Add alt version format for ExtMM
	# 0.4.4		- Add dep on recent ExtMM @ in BUILD_REQ
	#           Documentation enhancements and clarifications.
	# 0.4.3		- change format of VERSION to a string (vec unsupported
	# 					in earlier perl versions)
	# 0.4.2		- doc change & excisement of  a symlink (maybe winprob)
	# 0.4.1		- revert attempt to use win32 BS -- seems to cause
	# 					more problems than it fixed.
	# 0.4.0		- Documentation upgrade;
  #           Attempt to point to win32 paths w/backslash
	# 0.3.3		- Switch to using ptar for archive creation
	# 0.3.2		- Fix summary to be more descriptive
	#	0.3.1		- Fix Manifest => MANIFEST
	#	0.3.0		- Initial external 'non'-release

	our $sep;

  sub import {
    if (@_ >= 1) {
      my ($p, $f, $l)=caller;
		  $sep ||= sep_detect();
      if (@_ >= 1) {
        $p="main" unless $p;
        $p =~ s!::!$sep!ge;
        $p .= ".pm";
        $::INC{$p} = $f."#".$l unless exists $::INC{$p};
      }
    }
  }
1;


##########################################################################
#                 use mem; {{{1

=pod

=head1 NAME

=over

=item

mem  -  use "in-mem" pkgs & force definitions into mem early

=back

=head1 VERSION

=over

Version "0.4.5"

=back

=head1 SYNOPSIS


  use mem;
  use mem(@COMPILE_TIME_DEFINES=qw(a b c));

B> is a trivial pragma to either allow defining the module it is included from as being defined so that later classes or packages in the same file can C the package to pull in a reference to it, or to be able to call its import routine from a different package in the same file.

With parameter assignments or other actions, it forces those assignments to be
done, immediately, at compile time instead of later at run time.  It can be use, for example, with Exporter, to export typed-sub's among other usages.


=head1 EXAMPLE

Following, is a sample program, showing two uses of C.

  use strict; use warnings;

  { package Ar_Type;
      #
      use mem;                                    #1st usage
      our (@EXPORT, @ISA);
      sub ARRAY (;*) {
          my $p = $_[0]; my $t="ARRAY";
          return @_ ? (ref $p && (1+index($p, $t))) : $t;
      }
      #
      use mem(                                    #2nd usage
          @EXPORT=qw(ARRAY), @ISA=qw(Exporter)
      #
      )                                           #(also) 2nd usage
      ;
      use Exporter;
  }

  package main;
  use Ar_Type;
  use P;
	use Types::Core

  my @a=(1,2,3);
  my ($ed, $light);
      (@$ed, @$light) = (@a, @a);  #ed & light point to copies of @a
  bless $ed, "bee";

  P "\@a = ref of array" if ARRAY \@a;
  P "ref of ed is %s", ref $ed;
  P "ed still points to underlying type, 'array'" if ARRAY $ed;
  P "Is ref \$light, ARRAY?: %s", (ref $light eq ARRAY) ? 'yes':'no';
  P "Does \"ref \$ed\" eq ARRAY?: %s", (ref $ed eq ARRAY) ? 'yes':'no';
  P "%s", "#  (Because \"ref \$ed\" is really a bless \"ed\" bee)"

=over

=item

First, the correct output:

  @a = ref of array
  ref of ed is bee
  ed still points to underlying type, 'array'
  Is ref $light, ARRAY?: yes
  Does ref $ed eq ARRAY?: no
  #  (Because ref "ed" is really a bless "ed" bee)


=item

Second, B> the first "C< use mem >", presuming the line was commented out:

  Can't locate Ar_Type.pm in @INC (@INC contains:
    /usr/lib/perl5/5.16.2 ...   /usr/lib/perl5/site_perl .)
    at /tmp/ex line 18.
  BEGIN failed--compilation aborted at /tmp/ex line 18.

This is due to C, the package already declared
and in Iory>>, being I by Perl's C statement
because some I, I<"internal flag"> is not set for
C.  The first C causes this flag, normally
set with the path of the of a Cd file, to be set with the
containing file path and an added comment, containing the line number.

This tells perl to use the definition of the package that is already
in Cory.

=over

I

=back

=item

Third, instead of dropping the 1st "C< use mem >", you drop (or comment out) the 2nd usage in the above example, you get:

  Bareword "ARRAY" not allowed while "strict subs"
    in use at /tmp/ex line 27.
  syntax error at /tmp/ex line 27, near "ARRAY \"
  Bareword "ARRAY" not allowed while "strict subs"
    in use at /tmp/ex line 30.
  Bareword "ARRAY" not allowed while "strict subs"
    in use at /tmp/ex line 31.
  Execution of /tmp/ex aborted due to compilation errors.


This happens because when C is called, the
contents of C<@EXPORT> is not known.  Even with the assignment
to C<@EXPORT>, the "C<@EXPORT=qw(ARRAY)>" being right above
the C statement.  Similarly to the first error, above,
Perl doesn't use the value of C<@EXPORT> just above it.  Having
C< use mem > in the second position forces Perl to put the assignment
to @EXPORT in C< mem >ory, so that when C< use Exporter > is called,
it can pick up the name of C as already being "exported" and
B.

Without C putting the value of C<@EXPORT> in Cory,
C isn't defined, an you get the errors shown above.

=back

=head2 Summary

The first usage allows 'C' to find C, I
Cory>.

The second usage forces the definition of 'C' into Cory so
they can be exported by an exporter function.

In B cases, C allows your already-in-Cory code to
be used.  Thsi allows simplified programming and usage without knowledge
of or references to Perl's internal-flags or internal run phases.

=head1 SEE ALSO


See L for information on exporting names.  See the newer,
L for doing similar without the need for setting C<@ISA>
and persistent defaults in C<@EXPORT>. See L for more details about
the generic print verb and see L for a more complete
treatment of the CORE Types.



=cut