[{"date":"2009-04-28T06:09:31Z","categories":["Perl"],"author":{"name":"Florian Ragwitz","email":"rafl@fsfe.org","keyid":"742f2a428e635a5e"},"tags":[{"perl":0},{"types":0},{"moose":0},{"syntax":0}],"modified":"2009-04-28T06:20:16Z","uri":"http://perldition.org/articles/Implementing%20Typed%20Lexical%20Variables.pod","signed":1,"summary":" For quite some time perl provided a form of …","xhtml":"
\n

For quite some time perl provided a form of my declarations that\nincludes a type name, like this:

\n
my Str $x = 'foo';\n
\n

However, that didn't do anything useful, until Vincent Pit came along\nand wrote the excellent\nLexical::Types\nmodule, which allows you to extend the semantics of typed lexicals and\nactually make them do something useful. For that, it simply invokes a\ncallback for every my declaration with a type in the scopes it is\nloaded. Within that callback you get the variable that is being\ndeclared as well as the name of the type used in the declaration.

\n

We also have Moose type constraints and the great\nMooseX::Types module,\nthat allows us to define our own type libraries and import the type\nconstraints into other modules.

\n

Let's glue those modules together. Consider this code:

\n
use MooseX::Types::Moose qw/Int/;\nuse Lexical::Types;\nmy Int $x = 42;\n
\n

The first problem is that the perl compiler expects a package with the\nname of the type used in my to exist. If there's no such package\ncompilation will fail.

\n

Creating top-level namespaces for all the types we want to use would\nobviously suck. Luckily the compiler will also try to look for a\nfunction with the name of the type in the current scope. If that\nexists and is inlineable, it will call that function and use the\nreturn value as a package name.

\n

In the above code snippet an Int function already exists. We\nimported that from MooseX::Types::Moose. Unfortunately it isn't\ninlineable. Even if it were, compilation would still fail, because it\nwould return a Moose::Meta::TypeConstraint instead of a valid\npackage name.

\n

To fix that, let's rewrite the code to this:

\n
use MooseX::Types::Moose qw/Int/;\nuse MooseX::Lexical::Types qw/Int/;\nmy Int $x = 42;\n
\n

Let's also write a MooseX::Lexical::Types module that replaces\nexisting imported type exports with something that can be inlined and\nreturns an existing package name based on the type constraint's name.

\n
package MooseX::Lexical::Types;\n\nuse Class::MOP;\nuse MooseX::Types::Util qw/has_available_type_export/;\nuse namespace::autoclean;\n\nsub import {\n    my ($class, @args) = @_;\n    my $caller = caller();\n\n    my $meta = Class::MOP::class_of($caller) || Class::MOP::Class->initialize($caller);\n\n    for my $type_name (@args) {\n        # get the type constraint by introspecting the caller\n        my $type_constraint = has_available_type_export($caller, $type_name);\n\n        my $package = 'MooseX::Lexical::Types::TYPE::' . $type_constraint->name;\n        Class::MOP::Class->create($package);\n        $meta->add_package_symbol('&'.$type_name => sub () { $package });\n    }\n\n    Lexical::Types->import; # enable Lexical::Types for the caller\n}\n\n1;\n
\n

With that the example code now compiles. Unfortunately it breaks every\nother usecase of MooseX::Types. The export will still need to return a\nMoose::Meta::TypeConstraint at run time so this will continue to\nwork:

\n
has some_attribute => (is => 'ro', isa => Int);\n
\n

So instead of returning a plain package name from our exported\nfunction we will return an object that delegates all method calls to\nthe actual type constraint, but evaluates to our special package name\nwhen used as a string:

\n
my $decorator = MooseX::Lexical::Types::TypeDecorator->new($type_constraint);\n$meta->add_package_symbol('&'.$type_name => sub () { $decorator });\n
\n

and:

\n
package MooseX::Lexical::Types::TypeDecorator;\nuse Moose;\nuse namespace::autoclean;\n\n# MooseX::Types happens to already have a class that doesn't do much\n# more than delegating to a real type constraint!\nextends 'MooseX::Types::TypeDecorator';\n\nuse overload '""' => sub {\n    'MooseX::Lexical::Types::TYPE::' . $_[0]->__type_constraint->name\n};\n\n1;\n
\n

Now we're able to use Int as usual and have Lexical::Types invoke\nits callback on MooseX::Lexical::Types::TYPE::Int. Within that\ncallback we will need the real type constraint again, but as it is\ninvoked as a class method with no good way to pass in additional\narguments, we will need to store the type constraint somewhere. I\nchoose to simply add a method to the type class we create when\nconstructing our export. After that, all we need is to implement our\nLexical::Types callback. We will put that in a class all our type\nclasses will inherit from:

\n
Class::MOP::Class->create(\n    $package => (\n        superclasses => ['MooseX::Lexical::Types::TypedScalar'],\n        methods      => {\n            get_type_constraint => sub { $type_constraint },\n        },\n    ),\n);\n
\n

The Lexical::Types callback will now need to tie things together by\nmodifying the declared variable so it will automatically validate\nvalues against the type constraint when being assigned to. There are\nseveral ways of doing this. Using tie on the declared variable\nwould probable be the easiest thing to do. However, I decided to use\nVariable::Magic\n(also written by Vincent Pit - did I mention he's awesome?), because\nit's mostly invisible at the perl level and also performs rather well\n(not that it'd matter, given that validation itself is relatively\nslow):

\n
package MooseX::Lexical::Types::TypedScalar;\n\nuse Carp qw/confess/;\nuse Variable::Magic qw/wizard cast/;\nuse namespace::autoclean;\n\nmy $wiz = wizard\n    # store the type constraint in the data attached to the magic\n    data => sub { $_[1]->get_type_constraint },\n    # when assigning to the variable, fail if we can't validate the\n    # new value ($_[0]) against the type constraint ($_[1])\n    set  => sub {\n        if (defined (my $msg = $_[1]->validate(${ $_[0] }))) {\n            confess $msg;\n        }\n        ();\n    };\n\nsub TYPEDSCALAR {\n    # cast $wiz on the variable in $_[1]. pass the type package name\n    # in $_[0] to the wizard's data construction callback.\n    cast $_[1], $wiz, $_[0];\n    ();\n}\n\n1;\n
\n

With this, our example code now works. If someone wants to assign,\nsay, 'foo' to the variable declared as my Int $x our magic\ncallback will be invoked, try to validate the value against the type\nconstraint and fail loudly. WIN!

\n

The code for all this is available\ngithub and should also\nbe on CPAN shortly.

\n

You might notice warnings about mismatching prototypes. Those are\ncaused by Class::MOP and fixed in the git version of it, so they'll go\naway with the next release.

\n

There's still a couple of caveats, but please see the documentation\nfor that.

\n\n\n
","text":" For quite some time perl provided a form of my declarations that in-\n cludes a type name, like this:\n\n lang:Perl my Str $x = 'foo';\n\n However, that didn't do anything useful, until Vincent Pit came a-\n long and wrote the excellent Lexical::Types module, which allows you\n to extend the semantics of typed lexicals and actually make them do\n something useful. For that, it simply invokes a callback for every\n my declaration with a type in the scopes it is loaded. Within that\n callback you get the variable that is being declared as well as the\n name of the type used in the declaration.\n\n We also have Moose type constraints and the great MooseX::Types mod-\n ule, that allows us to define our own type libraries and import the\n type constraints into other modules.\n\n Let's glue those modules together. Consider this code:\n\n lang:Perl use MooseX::Types::Moose qw/Int/; use Lexical::Types; my\n Int $x = 42;\n\n The first problem is that the perl compiler expects a package with\n the name of the type used in my to exist. If there's no such package\n compilation will fail.\n\n Creating top-level namespaces for all the types we want to use would\n obviously suck. Luckily the compiler will also try to look for a\n function with the name of the type in the current scope. If that ex-\n ists and is inlineable, it will call that function and use the re-\n turn value as a package name.\n\n In the above code snippet an Int function already exists. We im-\n ported that from MooseX::Types::Moose. Unfortunately it isn't in-\n lineable. Even if it were, compilation would still fail, because\n it would return a Moose::Meta::TypeConstraint instead of a valid\n package name.\n\n To fix that, let's rewrite the code to this:\n\n lang:Perl use MooseX::Types::Moose qw/Int/; use MooseX::Lexi-\n cal::Types qw/Int/; my Int $x = 42;\n\n Let's also write a MooseX::Lexical::Types module that replaces\n existing imported type exports with something that can be in-\n lined and returns an existing package name based on the type\n constraint's name.\n\n lang:Perl package MooseX::Lexical::Types;\n\n use Class::MOP; use MooseX::Types::Util qw/has_available_type_ex-\n port/; use namespace::autoclean;\n\n sub import { my ($class, @args) = @_; my $caller = caller();\n\n my $meta = Class::MOP::class_of($caller) ||\n Class::MOP::Class->initialize($caller);\n\n for my $type_name (@args) {\n # get the type constraint by introspecting the caller\n my $type_constraint = has_available_type_export($caller,\n $type_name);\n\n my $package = 'MooseX::Lexical::Types::TYPE::' . $type_-\n constraint->name; Class::MOP::Class->create($package);\n $meta->add_package_symbol('&'.$type_name => sub () { $-\n package }); }\n\n Lexical::Types->import; # enable Lexical::Types for the caller\n }\n\n 1;\n\n With that the example code now compiles. Unfortunately it breaks ev-\n ery other usecase of MooseX::Types. The export will still need to\n return a Moose::Meta::TypeConstraint at run time so this will con-\n tinue to work:\n\n lang:Perl has some_attribute => (is => 'ro', isa => Int);\n\n So instead of returning a plain package name from our exported func-\n tion we will return an object that delegates all method calls to the\n actual type constraint, but evaluates to our special package name\n when used as a string:\n\n lang:Perl my $decorator = MooseX::Lexical::Types::TypeDecora-\n tor->new($type_constraint); $meta->add_package_symbol('&'.$type_-\n name => sub () { $decorator });\n\n and:\n\n lang:Perl package MooseX::Lexical::Types::TypeDecorator; use\n Moose; use namespace::autoclean;\n\n # MooseX::Types happens to already have a class that doesn't do\n # much more than delegating to a real type constraint!\n extends 'MooseX::Types::TypeDecorator';\n\n use overload '\"\"' => sub { 'MooseX::Lexical::Types::TYPE::' .\n $_[0]->__type_constraint->name };\n\n 1;\n\n Now we're able to use Int as usual and have Lexical::Types invoke\n its callback on MooseX::Lexical::Types::TYPE::Int. Within that call-\n back we will need the real type constraint again, but as it is in-\n voked as a class method with no good way to pass in additional argu-\n ments, we will need to store the type constraint somewhere. I choose\n to simply add a method to the type class we create when constructing\n our export. After that, all we need is to implement our Lexi-\n cal::Types callback. We will put that in a class all our type class-\n es will inherit from:\n\n lang:Perl Class::MOP::Class->create( $package => ( superclasses =>\n ['MooseX::Lexical::Types::TypedScalar'], methods => { get_type_-\n constraint => sub { $type_constraint }, }, ), );\n\n The Lexical::Types callback will now need to tie things together by\n modifying the declared variable so it will automatically validate\n values against the type constraint when being assigned to. There are\n several ways of doing this. Using tie on the declared variable would\n probable be the easiest thing to do. However, I decided to use Vari-\n able::Magic (also written by Vincent Pit - did I mention he's awe-\n some?), because it's mostly invisible at the perl level and also\n performs rather well (not that it'd matter, given that validation\n itself is relatively slow):\n\n lang:Perl package MooseX::Lexical::Types::TypedScalar;\n\n use Carp qw/confess/; use Variable::Magic qw/wizard cast/; use\n namespace::autoclean;\n\n my $wiz = wizard\n # store the type constraint in the data attached to the magic\n data => sub { $_[1]->get_type_constraint },\n # when assigning to the variable, fail if we can't validate\n # the new value ($_[0]) against the type constraint ($_[1])\n set => sub { if (defined (my $msg = $_[1]->validate(${ $_[0]\n }))) { confess $msg; } (); };\n\n sub TYPEDSCALAR {\n # cast $wiz on the variable in $_[1]. pass the type package\n # name in $_[0] to the wizard's data construction callback.\n cast $_[1], $wiz, $_[0]; (); }\n\n 1;\n\n With this, our example code now works. If someone wants to assign,\n say, 'foo' to the variable declared as my Int $x our magic callback\n will be invoked, try to validate the value against the type con-\n straint and fail loudly. WIN!\n\n The code for all this is available github and should also be on\n CPAN shortly.\n\n You might notice warnings about mismatching prototypes. Those are\n caused by Class::MOP and fixed in the git version of it, so they'll\n go away with the next release.\n\n There's still a couple of caveats, but please see the documenta-\n tion for that.\n","title":"Implementing Typed Lexical Variables","type":"pod","guid":"97a76a6d-4019-4554-9993-2de23bde7e39","raw":"-----BEGIN PGP SIGNED MESSAGE-----\nHash: SHA1\n\n=pod\n\nFor quite some time perl provided a form of C declarations that\nincludes a type name, like this:\n\n lang:Perl\n my Str $x = 'foo';\n\nHowever, that didn't do anything useful, until Vincent Pit came along\nand wrote the excellent\nL\nmodule, which allows you to extend the semantics of typed lexicals and\nactually make them do something useful. For that, it simply invokes a\ncallback for every C declaration with a type in the scopes it is\nloaded. Within that callback you get the variable that is being\ndeclared as well as the name of the type used in the declaration.\n\nWe also have Moose type constraints and the great\nL module,\nthat allows us to define our own type libraries and import the type\nconstraints into other modules.\n\nLet's glue those modules together. Consider this code:\n\n lang:Perl\n use MooseX::Types::Moose qw/Int/;\n use Lexical::Types;\n my Int $x = 42;\n\nThe first problem is that the perl compiler expects a package with the\nname of the type used in C to exist. If there's no such package\ncompilation will fail.\n\nCreating top-level namespaces for all the types we want to use would\nobviously suck. Luckily the compiler will also try to look for a\nfunction with the name of the type in the current scope. If that\nexists and is inlineable, it will call that function and use the\nreturn value as a package name.\n\nIn the above code snippet an C function already exists. We\nimported that from C. Unfortunately it isn't\ninlineable. Even if it were, compilation would still fail, because it\nwould return a C instead of a valid\npackage name.\n\nTo fix that, let's rewrite the code to this:\n\n lang:Perl\n use MooseX::Types::Moose qw/Int/;\n use MooseX::Lexical::Types qw/Int/;\n my Int $x = 42;\n\nLet's also write a MooseX::Lexical::Types module that replaces\nexisting imported type exports with something that can be inlined and\nreturns an existing package name based on the type constraint's name.\n\n lang:Perl\n package MooseX::Lexical::Types;\n\n use Class::MOP;\n use MooseX::Types::Util qw/has_available_type_export/;\n use namespace::autoclean;\n\n sub import {\n my ($class, @args) = @_;\n my $caller = caller();\n\n my $meta = Class::MOP::class_of($caller) || Class::MOP::Class->initialize($caller);\n\n for my $type_name (@args) {\n # get the type constraint by introspecting the caller\n my $type_constraint = has_available_type_export($caller, $type_name);\n\n my $package = 'MooseX::Lexical::Types::TYPE::' . $type_constraint->name;\n Class::MOP::Class->create($package);\n $meta->add_package_symbol('&'.$type_name => sub () { $package });\n }\n\n Lexical::Types->import; # enable Lexical::Types for the caller\n }\n\n 1;\n\nWith that the example code now compiles. Unfortunately it breaks every\nother usecase of MooseX::Types. The export will still need to return a\nC at run time so this will continue to\nwork:\n\n lang:Perl\n has some_attribute => (is => 'ro', isa => Int);\n\nSo instead of returning a plain package name from our exported\nfunction we will return an object that delegates all method calls to\nthe actual type constraint, but evaluates to our special package name\nwhen used as a string:\n\n lang:Perl\n my $decorator = MooseX::Lexical::Types::TypeDecorator->new($type_constraint);\n $meta->add_package_symbol('&'.$type_name => sub () { $decorator });\n\nand:\n\n lang:Perl\n package MooseX::Lexical::Types::TypeDecorator;\n use Moose;\n use namespace::autoclean;\n\n # MooseX::Types happens to already have a class that doesn't do much\n # more than delegating to a real type constraint!\n extends 'MooseX::Types::TypeDecorator';\n\n use overload '\"\"' => sub {\n 'MooseX::Lexical::Types::TYPE::' . $_[0]->__type_constraint->name\n };\n\n 1;\n\nNow we're able to use C as usual and have Lexical::Types invoke\nits callback on C. Within that\ncallback we will need the real type constraint again, but as it is\ninvoked as a class method with no good way to pass in additional\narguments, we will need to store the type constraint somewhere. I\nchoose to simply add a method to the type class we create when\nconstructing our export. After that, all we need is to implement our\nLexical::Types callback. We will put that in a class all our type\nclasses will inherit from:\n\n lang:Perl\n Class::MOP::Class->create(\n $package => (\n superclasses => ['MooseX::Lexical::Types::TypedScalar'],\n methods => {\n get_type_constraint => sub { $type_constraint },\n },\n ),\n );\n\nThe Lexical::Types callback will now need to tie things together by\nmodifying the declared variable so it will automatically validate\nvalues against the type constraint when being assigned to. There are\nseveral ways of doing this. Using C on the declared variable\nwould probable be the easiest thing to do. However, I decided to use\nL\n(also written by Vincent Pit - did I mention he's awesome?), because\nit's mostly invisible at the perl level and also performs rather well\n(not that it'd matter, given that validation itself is relatively\nslow):\n\n lang:Perl\n package MooseX::Lexical::Types::TypedScalar;\n\n use Carp qw/confess/;\n use Variable::Magic qw/wizard cast/;\n use namespace::autoclean;\n\n my $wiz = wizard\n # store the type constraint in the data attached to the magic\n data => sub { $_[1]->get_type_constraint },\n # when assigning to the variable, fail if we can't validate the\n # new value ($_[0]) against the type constraint ($_[1])\n set => sub {\n if (defined (my $msg = $_[1]->validate(${ $_[0] }))) {\n confess $msg;\n }\n ();\n };\n\n sub TYPEDSCALAR {\n # cast $wiz on the variable in $_[1]. pass the type package name\n # in $_[0] to the wizard's data construction callback.\n cast $_[1], $wiz, $_[0];\n ();\n }\n\n 1;\n\nWith this, our example code now works. If someone wants to assign,\nsay, C<'foo'> to the variable declared as C our magic\ncallback will be invoked, try to validate the value against the type\nconstraint and fail loudly. B\n\nThe code for all this is available\nL and should also\nbe on CPAN shortly.\n\nYou might notice warnings about mismatching prototypes. Those are\ncaused by Class::MOP and fixed in the git version of it, so they'll go\naway with the next release.\n\nThere's still a couple of caveats, but please see L\nfor that.\n\n=cut\n-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1.4.6 (GNU/Linux)\n\niD8DBQFJ9qAgdC8qQo5jWl4RAni9AJoDwsG/8iNd2MlXvBLG6+1IOXCCnwCfZnys\nuUwBX0DArfYxN0EJf48Op2w=\n=xSW5\n-----END PGP SIGNATURE-----\n"}]