NAME
    Perl::Types - the Perl data type system

SYNOPSIS
        # the following three styles are functionally equivalent,
        # only choose one:
        use Perl::Types;  # OO style
        # OR
        use perltypes;    # pragma style
        # OR
        use types;        # pragma style, shortened

        # declare a typed scalar
        my integer $i = 42;

        # declare a typed compound reference
        my arrayref::integer $arr = [1, 2, 3];

DESCRIPTION
    Perl::Types defines package namespaces for core Perl data types and
    nested compound reference types using the "::" scope resolution
    operator. It enables explicit typing of scalars, arrays, and hashes in
    your Perl code.

    Note that `use Perl::Types;` and `use perltypes;` and `use types;` all
    have the exact same effect; these options are provided to please both OO
    and pragma style preferences. Please choose one and use it throughout
    your entire codebase, to avoid confusion.

    Use of the Perl data type system also provides the added benefit of
    pre-emptively preparing your Perl source code for future optimization by
    the Perl compiler.

    Perl::Types is currently in a beta release phase, and is considered
    stable enough for monitored use in commercial or production code.

  Data Types vs Type Constraints
    Do not confuse the Perl data type system with any of Perl's numerous
    type constraint libraries. If you are using any software other than
    Perl::Types to access or manage data types, then you are actually using
    type constraints.

    Data type systems access the real underlying data types, which are
    linked to the actual computer hardware resources and are not subjective
    in any way. On the other hand, type contraints access the transient data
    values and attempt to guess what the real data types might be, which is
    an entirely subjective process. While these may seem similar on the
    surface, and are often purposefully conflated due to Perl's checkered
    history with data type support, they are in fact very different
    approaches to software development and should be clearly understood as
    such.

    TL;DR: Type systems should be utilized instead of type contraints.

  Scalar Types
    Scalars contain a single piece of data, and are the foundation of all
    other data types.

    The five basic scalar data types are:

    *   boolean

    *   integer

    *   number

    *   character

    *   string

  Compound Reference Types
    Compound types are comprised of scalar types contained inside one or
    more nested references, such as:

    *   arrayref::integer

    *   arrayref::number

    *   arrayref::string

    *   hashref::integer

    *   hashref::number

    *   hashref::string

    *   arrayref::arrayref::integer

    *   hashref::hashref::arrayref::number

    *   hashref::arrayref::hashref::string

EXAMPLES
  Scalar Types
    Declaring & defining scalar variables:

        my boolean   $b = 1;
        my integer   $i = -123;
        my number    $n = 3.14;
        my character $c = 'a';
        my string    $s = 'hello';

  One-Dimensional Array References
    Declaring & defining array references:

        my arrayref::integer $ai = [1, 2, 3];
        my arrayref::number  $an = [3.14, 2.718];
        my arrayref::string  $as = ['foo', 'bar'];

  Two-Dimensional Array References
    Declaring & defining nested array references:

        my arrayref::arrayref::integer $a2i = [[1, 2], [3, 4]];
        my arrayref::arrayref::string  $a2s = [['a', 'b'], ['c', 'd']];

  One-Dimensional Hash References
    Declaring & defining hash references:

        my hashref::integer $hi = { a => 1, b => 2 };
        my hashref::number  $hn = { pi => 3.14 };
        my hashref::string  $hs = { foo => 'bar' };

  Two-Dimensional Hash References
    Declaring & defining nested hash references:

        my hashref::hashref::string $hhs = {
            out1 => { in1a => 'howdy', in1b => 'pardner' },
            out2 => { in2a => 'adios', in2b => 'amigo' }
        };

  Nested Hash/Array Structures
    Declaring & defining mixed nested structures:

        my hashref::arrayref::integer $hai = {
            arr1 => [1, 2, 3],
            arr2 => [4, 5, 6]
        };

        my arrayref::hashref::string $ahs = [
            { in1a => 'howdy', in1b => 'pardner' },
            { in2a => 'adios', in2b => 'amigo'   }
        ];

  Constants
    Declaring & defining scalar constants:

        use constant P   => my integer $TYPED_P   = 23;
        use constant PI  => my number  $TYPED_PI  = 3.141_59;
        use constant PIE => my string  $TYPED_PIE = 'pecan';

  Subroutines
    Declaring subroutine input parameters & output return values:

        sub pies_are_round {
            { my void $RETURN_TYPE };
            print 'in pies_are_round(), having PIE() = ', PIE(), "\n";
            return;
        }

        sub pi_r_squared {
            { my number $RETURN_TYPE };
            ( my number $r ) = @ARG;
            my number $area = PI() * $r ** 2;
            print 'in pi_r_squared(), have $area = PI() * $r ** 2 = ', $area, "\n";
            return $area;
        }

        sub p_is_pentagonal {
            { my string $RETURN_TYPE };
            ( my string $base_text, my integer $repeat_count ) = @ARG;
            my string $repeated_text = $base_text x $repeat_count;
            print 'in p_is_pentagonal(), have $repeated_text = \'', $repeated_text, '\'', "\n";
            return $repeated_text;
        }

  Object-Orientation
    Declaring & instantiating objects:

        my Some::Class $my_object = Some::Class->new();
        $my_object->some_method(5);

COMING SOON
    Documentation:

    *   More details & examples

    *   Type-checking instructions

    *   Arrays & hashes by value

    *   Arrays & hashes of objects

    *   Class definitions

    The following data types are partially implemented and planned for
    future releases:

    *   nonsigned_integer

    *   gmp_integer

    *   filehandleref

    *   void

    *   unknown

    *   scalartype

SEE ALSO
    The Perl Compiler

    The Perl::Types Committee <https://perlcommunity.org/types>

AUTHOR
    William N. Braswell, Jr.

    <mailto:wbraswell@NOSPAM.cpan.org>