perlx::maybe(3pm) [debian man page]

PerlX::Maybe(3pm)					User Contributed Perl Documentation					 PerlX::Maybe(3pm)

NAME

       PerlX::Maybe - return a pair only if they are both defined

SYNOPSIS

       You once wrote:

	my $bob = Person->new(
	   defined $name ? (name => $name) : (),
	   defined $age ? (age => $age) : (),
	   );

       Now you can write:

	my $bob = Person->new(
	   maybe name => $name,
	   maybe age  => $age,
	   );

DESCRIPTION

       Moose classes (and some other classes) distinguish between an attribute being unset and the attribute being set to undef. Supplying a
       constructor arguments like this:

	my $bob = Person->new(
	   name => $name,
	   age => $age,
	   );

       Will result in the "name" and "age" attributes possibly being set to undef (if the corresponding $name and $age variables are not defined),
       which may violate the Person class' type constraints.

       (Note: if you are the author of the class in question, you can solve this using MooseX::UndefTolerant. However, some of us are stuck using
       non-UndefTolerant classes written by third parties.)

       To ensure that the Person constructor does not try to set a name or age at all when they are undefined, ugly looking code like this is
       often used:

	my $bob = Person->new(
	   defined $name ? (name => $name) : (),
	   defined $age ? (age => $age) : (),
	   );

       or:

	my $bob = Person->new(
	   (name => $name) x!!(defined $name),
	   (age  => $age)  x!!(defined $age),
	   );

       A slightly more elegant solution is the "maybe" function:

   "maybe $x => $y, @rest"
       This function checks that $x and $y are both defined. If they are, it returns them both as a list; otherwise it returns the empty list.

       If @rest is provided, it is unconditionally appended to the end of whatever list is returned.

       The combination of these behaviours allows the following very sugary syntax to "just work".

	my $bob = Person->new(
		name	  => $name,
		address   => $addr,
	  maybe phone	  => $tel,
	  maybe email	  => $email,
		unique_id => $id,
	  );

       This function is exported by default.

BUGS

       Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=PerlX-Maybe <http://rt.cpan.org/Dist/Display.html?Queue=PerlX-Maybe>.

SEE ALSO

       Syntax::Feature::Maybe.

       MooseX::UndefTolerant, PerlX::Perform, Exporter.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

       This software is copyright (c) 2012 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES

       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

perl v5.14.2							    2012-05-03							 PerlX::Maybe(3pm)

MooseX::UndefTolerant(3pm)				User Contributed Perl Documentation				MooseX::UndefTolerant(3pm)

NAME

       MooseX::UndefTolerant - Make your attribute(s) tolerant to undef initialization

VERSION

       version 0.17

SYNOPSIS

	 package My::Class;

	 use Moose;
	 use MooseX::UndefTolerant;

	 has 'name' => (
	   is => 'ro',
	   isa => 'Str',
	   predicate => 'has_name'
	 );

	 # Meanwhile, under the city...

	 # Doesn't explode
	 my $class = My::Class->new(name => undef);
	 $class->has_name # False!

       Or, if you only want one attribute to have this behaviour:

	 package My:Class;
	 use Moose;

	 use MooseX::UndefTolerant::Attribute;

	 has 'bar' => (
	     traits => [ qw(MooseX::UndefTolerant::Attribute)],
	     is => 'ro',
	     isa => 'Num',
	     predicate => 'has_bar'
	 );

DESCRIPTION

       Loading this module in your Moose class makes initialization of your attributes tolerant of undef.  If you specify the value of undef to
       any of the attributes they will not be initialized, effectively behaving as if you had not provided a value at all.

       You can also apply the 'UndefTolerant' trait to individual attributes. See MooseX::UndefTolerant::Attribute for details.

       There will be no change in behaviour to any attribute with a type constraint that accepts undef values (for example "Maybe" types), as it
       is presumed that since the type is already "undef tolerant", there is no need to avoid initializing the attribute value with "undef".

       As of Moose 1.9900, this module can also be used in a role, in which case all of that role's attributes will be undef-tolerant.

MOTIVATION

       I often found myself in this quandry:

	 package My:Class;
	 use Moose;

	 has 'foo' => (
	   is => 'ro',
	   isa => 'Str',
	 );

	 # ... then

	 my $foo = ... # get the param from something

	 my $class = My:Class->new(foo => $foo, bar => 123);

       What if foo is undefined?  I didn't want to change my attribute to be Maybe[Str] and I still want my predicate ("has_foo") to work.  The
       only real solution was:

	 if(defined($foo)) {
	   $class = My:Class->new(foo => $foo, bar => 123);
	 } else {
	   $class = My:Class->new(bar => 123);
	 }

       Or some type of codemulch using ternary conditionals.  This module allows you to make your attributes more tolerant of undef so that you
       can keep the first example: have your cake and eat it too!

PER ATTRIBUTE

       See MooseX::UndefTolerant::Attribute.

CAVEATS

       This extension does not currently work in immutable classes when applying the trait to some (but not all) attributes in the class. This is
       because the inlined constructor initialization code currently lives in Moose::Meta::Class, not Moose::Meta::Attribute. The good news is
       that this is expected to be changing shortly.

ACKNOWLEDGEMENTS

       Many thanks to the crew in #moose who talked me through this module:

       Hans Dieter Pearcey (confound)

       Jesse Luehrs (doy)

       Tomas Doran (t0m)

       Dylan Hardison (dylan)

       Jay Shirley (jshirley)

       Mike Eldridge (diz)

AUTHOR

       Cory G Watson <gphat at cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011 by Cory G Watson.

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

perl v5.14.2							    2012-05-03						MooseX::UndefTolerant(3pm)