lib/Moose/Autobox.pm

   1
   2 package Moose::Autobox;
   3 use 5.006;
   4 use strict;
   5 use warnings;
   6
   7 use Carp        qw(confess);
   8 use Scalar::Util ();
   9 use Moose::Util  ();
  10
  11 our $VERSION = '0.12';
  12
  13 use parent 'autobox';
  14
  15 use Moose::Autobox::Undef;
  16
  17 sub import {
  18     (shift)->SUPER::import(
  19         DEFAULT => 'Moose::Autobox::',
  20         UNDEF   => 'Moose::Autobox::Undef',
  21     );
  22 }
  23
  24 sub mixin_additional_role {
  25     my ($class, $type, $role) = @_;
  26     ($type =~ /SCALAR|ARRAY|HASH|CODE/)
  27         || confess "Can only add additional roles to SCALAR, ARRAY, HASH or CODE";
  28     Moose::Util::apply_all_roles(('Moose::Autobox::' . $type)->meta, ($role));
  29 }
  30
  31 {
  32
  33     package Moose::Autobox::SCALAR;
  34
  35     use Moose::Autobox::Scalar;
  36
  37     use metaclass 'Moose::Meta::Class';
  38
  39     Moose::Util::apply_all_roles(__PACKAGE__->meta, ('Moose::Autobox::Scalar'));
  40
  41     *does = \&Moose::Object::does;
  42
  43     package Moose::Autobox::ARRAY;
  44
  45     use Moose::Autobox::Array;
  46
  47     use metaclass 'Moose::Meta::Class';
  48
  49     Moose::Util::apply_all_roles(__PACKAGE__->meta, ('Moose::Autobox::Array'));
  50
  51     *does = \&Moose::Object::does;
  52
  53     package Moose::Autobox::HASH;
  54
  55     use Moose::Autobox::Hash;
  56
  57     use metaclass 'Moose::Meta::Class';
  58
  59     Moose::Util::apply_all_roles(__PACKAGE__->meta, ('Moose::Autobox::Hash'));
  60
  61     *does = \&Moose::Object::does;
  62
  63     package Moose::Autobox::CODE;
  64
  65     use Moose::Autobox::Code;
  66
  67     use metaclass 'Moose::Meta::Class';
  68
  69     Moose::Util::apply_all_roles(__PACKAGE__->meta, ('Moose::Autobox::Code'));
  70
  71     *does = \&Moose::Object::does;
  72
  73 }
  74
  75 1;
  76
  77 __END__
  78
  79 =pod
  80
  81 =head1 NAME
  82
  83 Moose::Autobox - Autoboxed wrappers for Native Perl datatypes
  84
  85 =head1 SYNOPOSIS
  86
  87   use Moose::Autobox;
  88
  89   print 'Print squares from 1 to 10 : ';
  90   print [ 1 .. 10 ]->map(sub { $_ * $_ })->join(', ');
  91
  92 =head1 DESCRIPTION
  93
  94 Moose::Autobox provides an implementation of SCALAR, ARRAY, HASH
  95 & CODE for use with L<autobox>. It does this using a hierarchy of
  96 roles in a manner similar to what Perl 6 I<might> do. This module,
  97 like L<Class::MOP> and L<Moose>, was inspired by my work on the
  98 Perl 6 Object Space, and the 'core types' implemented there.
  99
 100 =head2 A quick word about autobox
 101
 102 The L<autobox> module provides the ability for calling 'methods'
 103 on normal Perl values like Scalars, Arrays, Hashes and Code
 104 references. This gives the illusion that Perl's types are first-class
 105 objects. However, this is only an illusion, albeit a very nice one.
 106 I created this module because L<autobox> itself does not actually
 107 provide an implementation for the Perl types but instead only provides
 108 the 'hooks' for others to add implementation too.
 109
 110 =head2 Is this for real? or just play?
 111
 112 Several people are using this module in serious applications and
 113 it seems to be quite stable. The underlying technologies of L<autobox>
 114 and L<Moose::Role> are also considered stable. There is some performance
 115 hit, but as I am fond of saying, nothing in life is free.  Note that this hit
 116 only applies to the I<use> of methods on native Perl values, not the mere act
 117 of loading this module in your namespace.
 118
 119 If you have any questions regarding this module, either email me, or stop by
 120 #moose on irc.perl.org and ask around.
 121
 122 =head2 Adding additional methods
 123
 124 B<Moose::Autobox> asks L<autobox> to use the B<Moose::Autobox::*> namespace
 125 prefix so as to avoid stepping on the toes of other L<autobox> modules. This
 126 means that if you want to add methods to a particular perl type
 127 (i.e. - monkeypatch), then you must do this:
 128
 129   sub Moose::Autobox::SCALAR::bar { 42 }
 130
 131 instead of this:
 132
 133   sub SCALAR::bar { 42 }
 134
 135 as you would with vanilla autobox.
 136
 137 =head1 METHODS
 138
 139 =over 4
 140
 141 =item B<mixin_additional_role ($type, $role)>
 142
 143 This will mixin an additonal C<$role> into a certain C<$type>. The
 144 types can be SCALAR, ARRAY, HASH or CODE.
 145
 146 This can be used to add additional methods to the types, see the
 147 F<examples/units/> directory for some examples.
 148
 149 =back
 150
 151 =head1 TODO
 152
 153 =over 4
 154
 155 =item More docs
 156
 157 =item More tests
 158
 159 =back
 160
 161 =head1 BUGS
 162
 163 All complex software has bugs lurking in it, and this module is no
 164 exception. If you find a bug please either email me, or add the bug
 165 to cpan-RT.
 166
 167 =head1 AUTHOR
 168
 169 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 170
 171 B<with contributions from:>
 172
 173 Anders (Debolaz) Nor Berle
 174
 175 Matt (mst) Trout
 176
 177 renormalist
 178
 179 =head1 COPYRIGHT AND LICENSE
 180
 181 Copyright 2006-2008 by Infinity Interactive, Inc.
 182
 183 L<http://www.iinteractive.com>
 184
 185 This library is free software; you can redistribute it and/or modify
 186 it under the same terms as Perl itself.
 187
 188 =cut