/ 
TUI-Vision-v2.0.1
/ TUI::toolkit::Types

NAME

TUI::toolkit::Types - Type constraints without non-core Perl dependencies

SYNOPSIS

Simple type check

use TUI::toolkit::Types qw( Int );

my $t = Int;
say $t->check(42);      # true
say $t->check("no");    # false

Parametric usage

use TUI::toolkit::Types qw( ArrayRef Int );

my $t = ArrayRef([ Int ]);
$t->check([1,2,3]);    # ok
$t->check([1,"x"]);    # fails

Using types with TUI::toolkit::Params signatures

use TUI::toolkit::Types qw( :Int );
use Type::Params qw( signature );

sub add_numbers {
  state $sig = signature(
    pos => [
      Int,                # our Type::API compatible type object
      sub { /^\d+$/ },    # custom CODE
    ],
  );

  my ($x, $y) = $sig->(@_);
  return $x + $y;
}

say add_numbers(40, 2);  # 42

DESCRIPTION

TUI::toolkit::Types provides a set of lightweight type constraints that are compatible with Type::API and mimic much of the behavior of MooseX::Types and Types::Standard, but without depending on XS or any non-core Perl modules.

All types behave as true type objects: they support checking a value, generating error messages, stringification, and executable-code overloading. The implementation avoids all non-core modules.

For each type, two function forms may exist:

  • Constructor - returns a type object (e.g. Int)

  • Predicate - low-level boolean checker (e.g. is_Int)

Beside that collection of primitive, reference, and numeric type constraints, this module including basic support for parameterized types such as ArrayRef[Int] or Maybe[Str].

INCLUDED TYPES

The following types correspond closely to the types found in Types::Standard and MooseX::Types::Common::Numeric.

Primitive Types

  • Any

    Accepts any Perl value.

  • Item

    Synonym for Any; matches any single Perl value.

  • Undef

    Accepts only undef.

  • Defined

    Accepts any defined value.

  • Value

    Accepts defined, non-reference scalar values.

  • Bool

    Accepts undef, the empty string "", "0", or "1".

  • Str

    Accepts normal Perl strings; excludes globs and v-strings.

  • ClassName

    Accepts valid Perl package names, either because @ISA or $VERSION exist, or because it exists with at least one subroutine in the symbol table.

  • Num

    Accepts values for which looks_like_number is true.

  • Int

    Accepts integer values (including negative numbers and zero).

Numeric Special Types

Modeled after MooseX::Types::Common::Numeric:

  • PositiveInt

    Integer strictly greater than zero.

  • PositiveOrZeroInt

    Integer greater than or equal to zero.

Reference Types

  • Ref

    Any reference.

  • ArrayRef

    Array reference. Parameterizable.

  • HashRef

    Hash reference. Parameterizable.

  • ScalarRef

    Accepts scalar references. Parameterizable.

  • CodeRef

    Subroutine reference.

  • GlobRef

    Glob reference.

  • FileHandle

    Matches Perl filehandle-like entities or IO::Handle-based objects.

  • Object

    Any blessed reference.

  • HashLike

    Accepts hash and blessed hash references.

  • ArrayLike

    Accepts array and blessed array references.

Parameterized Types

The following parameterized types accept exactly one constraint as parameter:

  • Maybe[$type]

    Accepts undef or a value satisfying $type.

  • Ref[$type]

    Checks each referenced element (useful for array-like structures).

  • ArrayRef[$type]

    Checks each array element.

  • HashRef[$type]

    Checks each hash value (keys are not verified).

  • ScalarRef[$type]

    Checks the referent.

Additional parameterized types:

  • Instance[$packages]

    Checks whether at least one package is an object instance of these classes.

TYPE RELATIONSHIPS

A simplified, Types::Tiny-compatible parent-child hierarchy is used:

Any
 +-- Item
      +-- Undef
      +-- Defined
      |    +-- Value
      |    |    +-- Bool
      |    |    +-- Str
      |    |    |    +-- ClassName
      |    |    +-- Num
      |    |         +-- Int
      |    |              +-- PositiveInt
      |    |              +-- PositiveOrZeroInt
      |    +-- Ref
      |         +-- ScalarRef
      |         +-- ArrayRef
      |         +-- HashRef
      |         +-- CodeRef
      |         +-- GlobRef
      |         +-- Object
      |              +-- InstanceOf
      |         +-- FileHandle
      |         +-- ArrayLike
      |         +-- HashLike
      +-- Maybe

Note: Although conceptually similar, Item and Any are implemented in a parent-child relationship.

PREDICATE FUNCTIONS

Every type also has a low-level predicate function is_*.

Predicates:

  • accept a single value,

  • return a boolean,

  • do not throw exceptions.

Predicate example

Predicate functions are well-suited for assertion frameworks or any situation where a simple boolean check is needed without throwing exceptions.

For example, using PerlX::Assert or Devel::Assert:

use PerlX::Assert -check;
# use Devel::Assert 'on';
use TUI::toolkit::Types qw( is_Int );

my $value = 123;

# predicate types inside an assertion
assert ( is_Int $value );    # passes

$value = 'x';
assert ( is_Int $value );    # fails with an assertion error

EXPORT TAGS

This module supports the following export groups:

  • :types

    Exports all type constructor functions.

  • :is

    Exports all is_* low-level predicate functions.

  • :all

    Exports everything this module provides.

  • Type-specific (e.g. :Str, :Object, ...)

    Each individual type constructor also has its own export group containing:

    Type constructor, Checker, Predicate

    For example:

    :Str       # exports Str, is_Str
:Object    # exports Object, is_Object
:Int       # exports Int, is_Int
:ArrayRef  # exports ArrayRef, is_ArrayRef

    This allows importing exactly one type without its siblings.

LIMITATIONS

Despite being conceptually similar to Types::Standard, this module intentionally keeps its feature set simple:

Only single-parameter parametric types are supported

No multi-parameter types such as Map[Key,Value] or Tuple[A,B,C].

No coercion system

No coercions are implemented. All checks are strict boolean validations.

Parameterized validation is shallow

ArrayRef and HashRef validate elements only one level deep unless the user nests parameterized types manually.

Keys of HashRef are not validated

Only values are checked.

ClassName detection is minimalistic

It relies on:

  • package has been loaded, or

  • symbol table existence,

  • presence of @ISA, $VERSION, or any subroutine.

No advanced object or meta introspection is performed.

FileHandle detection is conservative

User-defined file handle-like objects must be based on IO::Handle.

Overloading is not interpreted as a type hint

Overloaded stringification, boolean context, or code reification does not influence type acceptance. Only concrete Perl data types are recognized.

Compared to other, this module is intentionally smaller but slower

Type::Tiny provides many advanced features such as:

  • comprehensive type libraries

  • deep coercion systems

  • complex parameterized types (Tuple, Dict, Map, etc.)

  • fully integration with Moose, Moo, and other ecosystems

  • performance optimizations

Because Type::Tiny uses XS for many fast paths, it is significantly faster than this module in most scenarios. However, this also introduces additional installation requirements and non-core dependencies.

In contrast, TUI::toolkit::Types is:

  • fully pure-Perl

  • dependency-free

  • deliberately minimalistic

  • optimized for portability over raw speed

    If maximum performance or advanced type features are required, Type::Tiny is the more capable option.

REQUIRES

Only core modules are used:

SEE ALSO

AUTHOR

J. Schneider <brickpool@cpan.org>

CONTRIBUTORS

Toby Inkster <tobyink@cpan.org>

LICENSE

Copyright (c) 2013-2014, 2017-2026 the "AUTHORS" and "CONTRIBUTORS" as listed above.

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