X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FLexical-Types.git;a=blobdiff_plain;f=README;h=919e0afe5d8cda6269335e27e72deae4b9c87fbf;hp=42aec0ed1eb8457066574bf1d33e6efded37d18d;hb=005b1303d3fd36462b38b097f8c4f5abc7aa8369;hpb=eadc95d93dd6093c2e4805459beae335dd969bc8 diff --git a/README b/README index 42aec0e..919e0af 100644 --- a/README +++ b/README @@ -2,61 +2,118 @@ NAME Lexical::Types - Extend the semantics of typed lexicals. VERSION - Version 0.01 + Version 0.12 SYNOPSIS + { package Str; } + + { + package My::Types::Str; + + sub new { bless { }, shift } + } + + use Lexical::Types as => sub { 'My::Types::' . $_[0] => 'new' }; + + my Str $x; # $x is now a My::Types::Str object + { - package Str; + package My::Types::Int; - sub TYPEDSCALAR { Some::String::Implementation->new } + sub TYPEDSCALAR { bless { }, shift } } use Lexical::Types; - my Str $x; # $x is now a Some::String::Implementation object + use constant Int => 'My::Types::Int'; + + my Int $y; # $y is now a My::Types::Int object DESCRIPTION - This module allows you to hook the execution of typed lexicals - declarations ("my Foo $x"). In particular, it can be used to - automatically tie or bless typed lexicals. + This pragma allows you to hook the execution of typed lexicals + declarations ("my Str $x") by calling a configurable method in a + configurable package at each run. In particular, it can be used to + automatically tie or bless typed lexicals whenever they are initialized. + + Remind that for "perl" to be able to parse "my Str $x", you need : + + * either the "Str" package to be defined ; + + * or for "Str" to be a constant sub returning a valid defined package. + + so make sure you follow one of those two strategies to define your + types. - It is not implemented with a source filter. + This pragma is not implemented with a source filter. FUNCTIONS "import [ as => [ $prefix | $mangler ] ]" Magically called when writing "use Lexical::Types". All the occurences - of "my Foo $x" in the current lexical scope will be changed to call at + of "my Str $x" in the current lexical scope will be changed to call at each run a given method in a given package. The method and package are - determined by the parameter "as" : + determined by the parameter 'as' : - * If it's left unspecified, the "TYPEDSCALAR" method in the "Foo" + * If it's left unspecified, the "TYPEDSCALAR" method in the "Str" package will be called. use Lexical::Types; my Str $x; # calls Str->TYPEDSCALAR * If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR" - method in the "${prefix}::Foo" package will be used. + method in the "${prefix}::Str" package will be used. use Lexical::Types as => 'My::'; # or "as => 'My'" my Str $x; # calls My::Str->TYPEDSCALAR * If the value given is a code reference $mangler, it will be called - at compile-time with arguments 'Foo' and 'TYPEDSCALAR' and is - expected to return the desired package and method name (in that - order). If any of those is "undef", the default value will be used - instead. + at compile-time with arguments 'Str' and 'TYPEDSCALAR' and is + expected to return : - use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) }; - my Str $x; # the coderef indicates to call My->new_str + * either an empty list, in which case the current typed lexical + definition will be skipped (thus it won't be altered to trigger + a run-time hook) ; - The initializer method receives an alias to the pad entry of $x in $_[1] - and the original type name ("Foo") in $_[2]. You can either edit $_[1] - in place, in which case you should return an empty list, or return a new - scalar that will be copied into $x. + use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () }; + my Str $y; # calls Str->TYPEDSCALAR + my Int $x; # nothing special + + * or the desired package and method name, in that order (if any of + those is "undef", the default value will be used instead). + + use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) }; + my Str $x; # the coderef indicates to call My->new_str + + Note that if the type is a constant, $_[0] will be set to the + *value* of constant and not to its name. + + use Lexical::Types as => sub { $_[0] => 'new' }; + use constant Str => 'MyStr'; + my Str $x; # calls MyStr->new + + This means in particular that you can't both use constant types and + redirect several types to different methods of the same package, + because then you can't distinguish between the original types with + $_[0]. "unimport" - Magically called when writing "no Lexical::Types". Turns the module off. + Magically called when writing "no Lexical::Types". Turns the pragma off. + +RUN-TIME INITIALIZER METHOD + The initializer method receives an alias to the pad slot of the + initialized lexical in $_[1] and the original type name in $_[2]. You + can either edit $_[1] in place, in which case you should return an empty + list, or return a new scalar that will be copied into the pad slot. + + use Lexical::Types as => 'My'; + + my Str $x; + + ... + + sub My::Str::TYPEDSCALAR { + # $_[1] is an alias to $x, and $_[2] is 'Str' + ... + } INTEGRATION You can integrate Lexical::Types in your module so that using it will @@ -82,17 +139,73 @@ INTEGRATION sub new_int { ... } + If you prefer to use constants rather than creating empty packages, you + can replace the previous example with something like this : + + package MyTypes; + + BEGIN { require Lexical::Types; } + + sub import { + my $pkg = caller; + for (qw) { + my $type = __PACKAGE__ . '::' . $_; + no strict 'refs'; + no warnings 'redefine'; + *{$pkg.'::'.$_} = eval "sub () { '$type' }"; + } + Lexical::Types->import( + as => sub { $_[0] => 'new' } + ); + } + + sub unimport { + Lexical::Types->unimport; + } + + package MyTypes::Str; + + sub new { ... } + + package MyTypes::Int; + + sub new { ... } + +CONSTANTS + "LT_THREADSAFE" + True iff the module could have been built with thread-safety features + enabled. + + "LT_FORKSAFE" + True iff this module could have been built with fork-safety features + enabled. This will always be true except on Windows where it's false for + perl 5.10.0 and below . + CAVEATS - For "perl" to be able to parse "my Foo $x", the package "Foo" must be - defined somewhere, and this even if you use the "as" option to redirect - to another package. It's unlikely to find a workaround, as this happens - deep inside the lexer, far from the reach of an extension. + The restrictions on the type (being either a defined package name or a + constant) apply even if you use the 'as' option to redirect to another + package, and are unlikely to find a workaround as this happens deep + inside the lexer - far from the reach of an extension. Only one mangler or prefix can be in use at the same time in a given scope. + The implementation was tweaked to work around several limitations of + vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a + "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into + "require"d scopes. + + With 5.8 perls, the pragma does not propagate into "eval STRING". This + is due to a shortcoming in the way perl handles the hints hash, which is + addressed in perl 5.10. + DEPENDENCIES - perl 5.8, XSLoader. + perl 5.8.3. + + A C compiler. This module may happen to build with a C++ compiler as + well, but don't rely on it, as no guarantee is made in this regard. + + XSLoader (standard since perl 5.006). SEE ALSO fields. @@ -122,8 +235,10 @@ SUPPORT ACKNOWLEDGEMENTS Inspired by Ricardo Signes. + Thanks Florian Ragwitz for suggesting the use of constants for types. + COPYRIGHT & LICENSE - Copyright 2009 Vincent Pit, all rights reserved. + Copyright 2009,2010,2011 Vincent Pit, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.