Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Type::Params(3)	      User Contributed Perl Documentation      Type::Params(3)

NAME
       Type::Params - Params::Validate-like parameter validation using
       Type::Tiny type constraints and coercions

SYNOPSIS
	use v5.10;
	use strict;
	use warnings;

	use Type::Params qw( compile );
	use Types::Standard qw(	slurpy Str ArrayRef Num	);

	sub deposit_monies
	{
	   state $check	= compile( Str,	Str, slurpy ArrayRef[Num] );
	   my ($sort_code, $account_number, $monies) = $check->(@_);

	   my $account = Local::BankAccount->new($sort_code, $account_number);
	   $account->deposit($_) for @$monies;
	}

	deposit_monies("12-34-56", "11223344", 1.2, 3, 99.99);

STATUS
       This module is covered by the Type-Tiny stability policy.

DESCRIPTION
       Type::Params uses Type::Tiny constraints	to validate the	parameters to
       a sub. It takes the slightly unorthodox approach	of separating
       validation into two stages:

       1.  Compiling the parameter specification into a	coderef; then

       2.  Using the coderef to	validate parameters.

       The first stage is slow (it might take a	couple of milliseconds), but
       you only	need to	do it the first	time the sub is	called.	The second
       stage is	fast; according	to my benchmarks faster	even than the XS
       version of Params::Validate.

       If you're using a modern	version	of Perl, you can use the "state"
       keyword which was a feature added to Perl in 5.10. If you're stuck on
       Perl 5.8, the example from the SYNOPSIS could be	rewritten as:

	my $deposit_monies_check;
	sub deposit_monies
	{
	   $deposit_monies_check ||= compile( Str, Str,	slurpy ArrayRef[Num] );
	   my ($sort_code, $account_number, $monies) = $deposit_monies_check->(@_);

	   ...;
	}

       Not quite as neat, but not awful	either.

       There's a shortcut reducing it to one step:

	use Type::Params qw( validate validate_named );

	sub deposit_monies
	{
	   my ($sort_code, $account_number, $monies) =
	      validate(	\@_, Str, Str, slurpy ArrayRef[Num] );

	   ...;
	}

       Type::Params has	a few tricks up	its sleeve to make sure	performance
       doesn't suffer too much with the	shortcut, but it's never going to be
       as fast as the two stage	compile/execute.

COOKBOOK
   Positional Parameters
	  sub nth_root
	  {
	     state $check = compile( Num, Num );
	     my	($x, $n) = $check->(@_);

	     return $x ** (1 / $n);
	  }

   Method Calls
       Type::Params exports an additional keyword "Invocant" on	request. This
       is a type constraint accepting blessed objects and also class names.

	  use Types::Standard qw( ClassName Object Str Int );
	  use Type::Params qw( compile Invocant	);

	  # a class method
	  sub new_from_json
	  {
	     state $check = compile( ClassName,	Str );
	     my	($class, $json)	= $check->(@_);

	     $class->new( from_json($json) );
	  }

	  # an object method
	  sub dump
	  {
	     state $check = compile( Object, Int );
	     my	($self,	$limit)	= $check->(@_);

	     local $Data::Dumper::Maxdepth = $limit;
	     print Data::Dumper::Dumper($self);
	  }

	  # can	be called as either and	object or class	method
	  sub run
	  {
	     state $check = compile( Invocant );
	     my	($proto) = $check->(@_);

	     my	$self =	ref($proto) ? $proto : $default_instance;
	     $self->_run;
	  }

       Of course, some people like to use "shift" for the invocant:

	  sub dump
	  {
	     my	$self =	shift;

	     state $check = compile( Int );
	     my	($limit) = $check->(@_);

	     local $Data::Dumper::Maxdepth = $limit;
	     print Data::Dumper::Dumper($self);
	  }

   Optional Parameters
	  use Types::Standard qw( Object Optional Int );

	  sub dump
	  {
	     state $check = compile( Object, Optional[Int] );
	     my	($self,	$limit)	= $check->(@_);
	     $limit //=	0;

	     local $Data::Dumper::Maxdepth = $limit;
	     print Data::Dumper::Dumper($self);
	  }

	  $obj->dump(1);      #	ok
	  $obj->dump();	      #	ok
	  $obj->dump(undef);  #	dies

   Slurpy Parameters
	  use Types::Standard qw( slurpy ClassName HashRef );

	  sub new
	  {
	     state $check = compile( ClassName,	slurpy HashRef );
	     my	($class, $ref) = $check->(@_);
	     bless $ref	=> $class;
	  }

	  __PACKAGE__->new(foo => 1, bar => 2);

       The following types from	Types::Standard	can be made slurpy:
       "ArrayRef", "Tuple", "HashRef", "Map", "Dict". Hash-like	types will die
       if an odd number	of elements are	slurped	in.

       A check may only	have one slurpy	parameter, and it must be the last
       parameter.

       Having a	slurpy parameter will slightly slow down your checks.

   Named Parameters
       You can use "compile_named" to accept a hash of named parameters

	  use Type::Params qw(compile_named);
	  use Types::Standard qw( slurpy Dict Ref Optional Int );

	  sub dump
	  {
	     state $check = compile_named(
		var    => Ref,
		limit  => Optional[Int],
	     );
	     my	$arg = $check->(@_);

	     local $Data::Dumper::Maxdepth = $arg->{limit};
	     print Data::Dumper::Dumper($arg->{var});
	  }

	  dump({ var =>	$foo, limit => 1 });	# ok (hashref)
	  dump(	 var =>	$foo, limit => 1  );	# ok (hash)
	  dump(	 var =>	$foo  );		# ok (no optional parameter)
	  dump(	 limit => 1  );			# dies

       Prior to	Type::Tiny 1.002000, the recommendation	was to use a slurpy
       "Dict". This still works, though	the error messages you get might not
       be quite	so nice, and you don't get the automatic detection of hash
       versus hashref in the input @_. Oh, and it's usually slower.

	  use Type::Params qw(compile);
	  use Types::Standard qw( slurpy Dict Ref Optional Int );

	  sub dump
	  {
	     state $check = compile(
		slurpy Dict[
		   var	  => Ref,
		   limit  => Optional[Int],
		],
	     );
	     my	($arg) = $check->(@_);

	     local $Data::Dumper::Maxdepth = $arg->{limit};
	     print Data::Dumper::Dumper($arg->{var});
	  }

	  dump(	 var =>	$foo, limit => 1  );	# ok (hash)
	  dump(	 var =>	$foo  );		# ok (no optional parameter)
	  dump(	 limit => 1  );			# dies

   Mixed Positional and	Named Parameters
       For this, you can still use the "slurpy Dict" hack...

	  use Types::Standard qw( slurpy Dict Ref Optional Int );

	  sub my_print
	  {
	     state $check = compile(
		Str,
		slurpy Dict[
		   colour => Optional[Str],
		   size	  => Optional[Int],
		],
	     );
	     my	($string, $arg)	= $check->(@_);

	     ...;
	  }

	  my_print("Hello World", colour => "blue");

   Coercions
       Coercions will automatically be applied for all type constraints	that
       have a coercion associated.

	  use Type::Utils;
	  use Types::Standard qw( Int Num );

	  my $RoundedInt = declare as Int;
	  coerce $RoundedInt, from Num,	q{ int($_) };

	  sub set_age
	  {
	     state $check = compile( Object, $RoundedInt );
	     my	($self,	$age) =	$check->(@_);

	     $self->{age} = $age;
	  }

	  $obj->set_age(32.5);	 # ok; coerced to "32".

       Coercions carry over into structured types such as "ArrayRef"
       automatically:

	  sub delete_articles
	  {
	     state $check = compile( Object, slurpy ArrayRef[$RoundedInt] );
	     my	($db, $articles) = $check->(@_);

	     $db->select_article($_)->delete for @$articles;
	  }

	  # delete articles 1, 2 and 3
	  delete_articles($my_db, 1.1, 2.2, 3.3);

       If type "Foo" has coercions from	"Str" and "ArrayRef" and you want to
       prevent coercion, then use:

	  state	$check = compile( Foo->no_coercions );

       Or if you just want to prevent coercion from "Str", use:

	  state	$check = compile( Foo->minus_coercions(Str) );

       Or maybe	add an extra coercion:

	  state	$check = compile(
	     Foo->plus_coercions(Int, q{ Foo->new_from_number($_) }),
	  );

       Note that the coercion is specified as a	string of Perl code. This is
       usually the fastest way to do it, but a coderef is also accepted.
       Either way, the value to	be coerced is $_.

       Having any coercions will slightly slow down your checks.

   Alternatives
       Type::Params can	export a "multisig" function that compiles multiple
       alternative signatures into one,	and uses the first one that works:

	  state	$check = multisig(
	     [ Int, ArrayRef ],
	     [ HashRef,	Num ],
	     [ CodeRef ],
	  );

	  my ($int, $arrayref) = $check->( 1, [] );
	  my ($hashref,	$num)  = $check->( {}, 1.1 );
	  my ($code)	       = $check->( sub { 1 } );

	  $check->( sub	{ 1 }, 1.1 );  # throws	an exception

       Coercions, slurpy parameters, etc still work.

       The magic global	"${^TYPE_PARAMS_MULTISIG}" is set to the index of the
       first signature which succeeded.

       The present implementation involves compiling each signature
       independently, and trying them each (in their given order!) in an
       "eval" block. The only slightly intelligent part	is that	it checks if
       "scalar(@_)" fits into the signature properly (taking into account
       optional	and slurpy parameters),	and skips evals	which couldn't
       possibly	succeed.

       It's also possible to list coderefs as alternatives in "multisig":

	  state	$check = multisig(
	     [ Int, ArrayRef ],
	     sub { ... },
	     [ HashRef,	Num ],
	     [ CodeRef ],
	     compile_named( needle => Value, haystack => Ref ),
	  );

       The coderef is expected to die if that alternative should be abandoned
       (and the	next alternative tried), or return the list of accepted
       parameters. Here's a full example:

	  sub get_from {
	     state $check = multisig(
		[ Int, ArrayRef	],
		[ Str, HashRef ],
		sub {
		   my ($meth, $obj);
		   die unless is_Object($obj);
		   die unless $obj->can($meth);
		   return ($meth, $obj);
		},
	     );

	     my	($needle, $haystack) = $check->(@_);

	     for (${^TYPE_PARAMS_MULTISIG) {
		return $haystack->[$needle] if $_ == 0;
		return $haystack->{$needle} if $_ == 1;
		return $haystack->$needle   if $_ == 2;
	     }
	  }

	  get_from(0, \@array);	     # returns $array[0]
	  get_from('foo', \%hash);   # returns $hash{foo}
	  get_from('foo', $obj);     # returns $obj->foo

   Defaults
       Type::Params does not currently offer a built-in	way to set defaults
       for a parameter.	Setting	defaults manually is not especially difficult.

	  sub print_coloured {
	     state $check = compile( Str, Optional[Str]	);

	     my	($text,	$colour) = $check->(@_);
	     $colour //= "black";

	     ...;
	  }

       I occasionally get requests for this to work:

	  sub print_coloured {
	     state $check = compile( Str, Default[Str, "black"]	);

	     my	($text,	$colour) = $check->(@_);

	     ...;
	  }

       But honestly, I don't find that any clearer.

COMPARISON WITH	PARAMS::VALIDATE
       Type::Params is not really a drop-in replacement	for Params::Validate;
       the API differs far too much to claim that. Yet it performs a similar
       task, so	it makes sense to compare them.

       o   Type::Params	will tend to be	faster if you've got a sub which is
	   called repeatedly, but may be a little slower than Params::Validate
	   for subs that are only called a few times. This is because it does
	   a bunch of work the first time your sub is called to	make
	   subsequent calls a lot faster.

       o   Params::Validate doesn't appear to have a particularly natural way
	   of validating a mix of positional and named parameters.

       o   Type::Utils allows you to coerce parameters.	For example, if	you
	   expect a Path::Tiny object, you could coerce	it from	a string.

       o   Params::Validate allows you to supply defaults for missing
	   parameters; Type::Params does not, but you may be able to use
	   coercion from Undef.

       o   If you are primarily	writing	object-oriented	code, using Moose or
	   similar, and	you are	using Type::Tiny type constraints for your
	   attributes, then using Type::Params allows you to use the same
	   constraints for method calls.

       o   Type::Params	comes bundled with Types::Standard, which provides a
	   much	richer vocabulary of types than	the type validation constants
	   that	come with Params::Validate. For	example, Types::Standard
	   provides constraints	like "ArrayRef[Int]" (an arrayref of
	   integers), while the	closest	from Params::Validate is "ARRAYREF",
	   which you'd need to supplement with additional callbacks if you
	   wanted to check that	the arrayref contained integers.

	   Whatsmore, Type::Params doesn't just	work with Types::Standard, but
	   also	any other Type::Tiny type constraints.

COMPARISON WITH	PARAMS::VALIDATIONCOMPILER
       Params::ValidationCompiler does basically the same thing	as
       Type::Params.

       o   Params::ValidationCompiler and Type::Params are likely to perform
	   fairly similarly. In	most cases, recent versions of Type::Params
	   seem	to be slightly faster, but except in very trivial cases,
	   you're unlikely to notice the speed difference. Speed probably
	   shouldn't be	a factor when choosing between them.

       o   Type::Params's syntax is more compact:

	      state $check = compile(Object, Optional[Int], slurpy ArrayRef);

	   Versus:

	      state $check = validation_for(
		 params	=> [
		    { type => Object },
		    { type => Int,	optional => 1 },
		    { type => ArrayRef,	slurpy => 1 },
		 ],
	      );

       o   Params::ValidationCompiler offers defaults.

       o   Params::ValidationCompiler probably has slightly better exceptions.

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

SEE ALSO
       Type::Tiny, Type::Coercion, Types::Standard.

AUTHOR
       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
       This software is	copyright (c) 2013-2014, 2017 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.24.1			  2017-06-08		       Type::Params(3)

NAME | SYNOPSIS | STATUS | DESCRIPTION | COOKBOOK | COMPARISON WITH PARAMS::VALIDATE | COMPARISON WITH PARAMS::VALIDATIONCOMPILER | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENCE | DISCLAIMER OF WARRANTIES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Type::Params&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help