From Code to Community: Sponsoring The Perl and Raku Conference 2025 Learn more

 / 
Type-TinyX-Facets-1.3
River stage one • 1 direct dependent • 8 total dependents
/ Type::TinyX::Facets

NAME

Type::TinyX::Facets - Easily create a facet parameterized Type::Tiny type

VERSION

version 1.3

SYNOPSIS


            

              
              
package My::Types;
use Carp;
use Type::Utils;
use Type::Library -base,
  -declare => 'MinMax',
  'Bounds', 'Positive';
use Types::Standard -types, 'is_Num';
use Type::TinyX::Facets;
# independent facets
facet 'min', sub {
    my ( $o, $var ) = @_;
    return unless exists $o->{min};
    croak( "argument to 'min' facet must be a number\n" )
      unless is_Num( $o->{min} );
    sprintf( '%s >= %s', $var, delete $o->{min} );
};
facet 'max', sub {
    my ( $o, $var ) = @_;
    return unless exists $o->{max};
    croak( "argument to 'max' facet must be a number\n" )
      unless is_Num( $o->{max} );
    sprintf( '%s <= %s', $var, delete $o->{max} );
};
declare MinMax, as Num, with_facets [ 'min', 'max' ];
# related facets
facet bounds => sub {
    my ( $o, $var ) = @_;
    return unless exists $o->{max} || exists $o->{min};
    croak( "constraint fails condition: max >= min\n" )
      if exists $o->{max} && exists $o->{min} && $o->{max} < $o->{min};
    my @code;
    if ( exists $o->{min} ) {
        croak( "argument to 'min' facet must be a number\n" )
          unless is_Num( $o->{min} );
        push @code, sprintf( '%s >= %s', $var, delete $o->{min} );
    }
    if ( exists $o->{max} ) {
        croak( "argument to 'max' facet must be a number\n" )
          unless is_Num( $o->{max} );
        push @code, sprintf( '%s <= %s', $var, delete $o->{max} );
    }
    return join( ' and ', @code );
};
declare Bounds, as Num, with_facets ['bounds'];
# on-the-fly creation of a facet
declare Positive, as Num, with_facets [
    'min', 'max',
    positive => sub {
        my ( $o, $var ) = @_;
        return unless exists $o->{positive};
        delete $o->{positive};
        sprintf( '%s > 0', $var );
    },
];
1;

And in some other code:


            

              
              
use My::Types -types;
use Type::Params qw[ validate ];
validate( [5], MinMax [ min => 2 ] );              # passes
validate( [5], MinMax [ min => 2, max => 6 ] );    # passes
validate( [5], Bounds [ min => 2 ] );              # passes
validate( [5], Bounds [ min => 2, max => 6 ] );    # passes
validate( [5], Bounds [ min => 5, max => 2 ] )
  ;    # fails to construct as min > max
validate( [0], Positive [ positive => 1 ] );    # fails!
validate( [1], Positive [ positive => 1 ] );    # passes

DESCRIPTION

Type::TinyX::Facets make it easy to create parameterized types with facets.

Type::Tiny allows definition of types which can accept parameters:


            

              
              
use Types::Standard -types;
my $t1 = Array[Int];
my $t2 = Tuple[Int, HashRef];

This defines $t1 as an array of integers. and $t2 as a tuple of two elements, an integer and a hash.

Parameters are passed as a list to the parameterized constraint generation machinery, and there is great freedom in how they may be interpreted.

This module makes it easy to create a parameterized type which takes name - value pairs or,facets. (The terminology is taken from Types::XSD::Lite, to which this module owes its existence.)

Alternate Names

Type::TinyX::Facets uses Exporter::Tiny, so one might correct(!?) the spelling of "facetize" thusly:


            

              
              
use Type::TinyX::Facets facetize => { -as => "facetise" };

SUBROUTINES

facet( $name, $coderef )

Declare a facet with the given name and code generator. $coderef will be called as


            

              
              
$coderef->( $options, $name, $facet_name );

where $options is a hash of the parameters passed to the type, and $name is the name of the variable to check against.

The code should return if the passed options are of no interest (and thus the facet should not be applied), otherwise it should return a string containing the validation code. It must delete the parameters that it uses from $o.

For example, to implement a minimum value check:


            

              
              
facet 'min',
  sub { my ( $o, $var ) = @_;
        return unless exists $o->{min};
        croak( "argument to 'min' facet must be a number\n" )
          unless is_Num( $o->{min} );
        sprintf('%s >= %s', $var, delete $o->{min} );
    };

with_facets


            

              
              
..., with_facets \@facets, ...

Add a facet to the type being declared. with_facets takes an arrayref of one or more facet names or coderefs to apply to the type, e.g.


            

              
              
declare BoundedEvenInt, as Int,
with_facets [ 'min', 'max',
   even => sub {  my ($o, $var) = @_;
                  return unless exists $o->{even};
                  delete $o->{even};
                  "! ( ${var} % 2 )";
               },
],
message { "This failed" }
;

facetize( @facets, $type )

DEPRECATED. This function currently pokes at "Type::Tiny"'s innards, and future compatibility cannot be guaranteed.

Use "with_facets" instead.

Add the specified facets to the given type. The type should not have any constraints other than through inheritance from a parent type.

@facets is a list of facets. If a facet was previously created with the "facet" subroutine, only the name (as a string) need be specified. A facet may also be specified as a name, coderef pair, e.g.


            

              
              
@facets = (
    'min',
    positive => sub {  my ($o, $var) = @_;
                       return unless exists $o->{positive};
                       delete $o->{positive};
                       sprintf('%s > 0', $var);
                   }
);

Typically facetize is applied directly to a "declare" in Type::Utils statement, e.g.:


            

              
              
facetize @facets,
  declare T1, as Num;

LIMITATIONS

Facets defined in one package are not available to another package.

THANKS

TOBYINK

The idea and most of the code was lifted from Types::XSD::Lite. Any bugs are definitely mine.

SOURCE

The development version is on GitLab at https://gitlab.com/djerius/type-tinyx-facets.

SUPPORT

Bugs

Please report any bugs or feature requests to or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Type-TinyX-Facets

Source

Source is available at


            

              
              
https://gitlab.com/djerius/type-tinyx-facets

and may be cloned from


            

              
              
https://gitlab.com/djerius/type-tinyx-facets.git

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Smithsonian Astrophysical Observatory.

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