NAME

Bubblegum::Constraints - Type and Constraints Library for Bubblegum

VERSION

version 0.30

SYNOPSIS

package Server;

use Bubblegum::Class;
use Bubblegum::Constraints -typing;

has typeof_object, config => sub {
    # build config data
};

DESCRIPTION

Bubblegum::Constraints is the standard type-checking library for Bubblegum applications with a focus on minimalism and data integrity.

By default, no functions are exported when using this package, all functionality desired will need to be explicitly requested, and because many functions belong to a particular group of functions there are export tags which can be used to export sets of functions by group name. Any function can also be exported individually. The following are a list of functions and groups currently available:

EXPORTS

-attr

The attr export group currently exports a single functions which overrides the has accessor maker in the calling class and implements a more flexible interface specification. If the has function does not exist in the caller's namespace then override will be aborted, otherwise, the has function will now support the following:

has 'attr1';

is the equivalent of:

has 'attr1' => (
    is => 'ro',
);

and if type validators are exported via -typesof, or -typing:

use Bubblegum::Constraints -typesof;

has typeof_object, 'attr2';

is the equivalent of:

has 'attr2' => (
    is  => 'ro',
    isa => typeof_object,
);

and/or including a default value, for example:

use Bubblegum::Constraints -typesof;

has 'attr1' => sub {
    # define lazy builder attr1
};

has typeof_object, 'attr2' => sub {
    # define lazy builder attr2
};

is the equivalent of:

has 'attr1' => (
    is      => 'ro',
    lazy    => 1,
    builder => '_build_attr1',
);

sub _build_attr1 {
    # ...
}

has 'attr2' => (
    is      => 'ro',
    isa     => typeof_object,
    lazy    => 1,
    builder => '_build_attr2',
);

sub _build_attr2 {
    # ...
}

also note, attribute builders are implied if a method is discovered with a name matching the pattern _build_${attribute_name}, for example:

use Bubblegum::Constraints -attr;

has 'attr1';

sub _build_attr1 {
    # ...
}

is the equivalent of:

has 'attr1' => (
    is      => 'ro',
    lazy    => 1,
    builder => '_build_attr1',
);

sub _build_attr1 {
    # ...
}

-constraints

The constraints export group exports all functions which have the _ prefix and provides functionality similar to importing the "-types" and "-typesof" export groups except that the functions it emits are abbreviated multi-purpose versions of the functions emitted by the -types and -typesof export groups. These functions take a single argument and perform fatal type checking, or, if invoked with no arguments returns a code reference to the fatal type checking routine. The following is a list of functions exported by this group:

• _aref

• _arrayref

• _bool

• _boolean

• _class

• _classname

• _cref

• _coderef

• _def

• _defined

• _fh

• _filehandle

• _glob

• _globref

• _href

• _hashref

• _int

• _integer

• _num

• _number

• _obj

• _object

• _ref

• _reference

• _rref

• _regexpref

• _sref

• _scalarref

• _str

• _string

• _nil

• _null

• _undef

• _undefined

-isas

The isas export group exports all functions which have the isa_ prefix. These functions take a single argument and perform non-fatal type checking and return true or false. The following is a list of functions exported by this group:

• isa_aref

• isa_arrayref

• isa_bool

• isa_boolean

• isa_class

• isa_classname

• isa_cref

• isa_coderef

• isa_def

• isa_defined

• isa_fh

• isa_filehandle

• isa_glob

• isa_globref

• isa_href

• isa_hashref

• isa_int

• isa_integer

• isa_num

• isa_number

• isa_obj

• isa_object

• isa_ref

• isa_reference

• isa_rref

• isa_regexpref

• isa_sref

• isa_scalarref

• isa_str

• isa_string

• isa_nil

• isa_null

• isa_undef

• isa_undefined

-minimal

The minimal export group exports all functions from the "-constraints", "-isas", and "-nots" export groups as well as the functionality provided by the "-attr" tag. It is a means to export the simplest type-related functionality.

-nots

The nots export group exports all functions which have the not_ prefix. These functions take a single argument and perform non-fatal negated type checking and return true or false. The following is a list of functions exported by this group:

• not_aref

• not_arrayref

• not_bool

• not_boolean

• not_class

• not_classname

• not_cref

• not_coderef

• not_def

• not_defined

• not_fh

• not_filehandle

• not_glob

• not_globref

• not_href

• not_hashref

• not_int

• not_integer

• not_num

• not_number

• not_obj

• not_object

• not_ref

• not_reference

• not_rref

• not_regexpref

• not_sref

• not_scalarref

• not_str

• not_string

• not_nil

• not_null

• not_undef

• not_undefined

-types

The types export group exports all functions which have the type_ prefix. These functions take a single argument/expression and perform fatal type checking operation returning the argument/expression if successful. The follow is a list of functions exported by this group:

• type_aref

• type_arrayref

• type_bool

• type_boolean

• type_class

• type_classname

• type_cref

• type_coderef

• type_def

• type_defined

• type_fh

• type_filehandle

• type_glob

• type_globref

• type_href

• type_hashref

• type_int

• type_integer

• type_num

• type_number

• type_obj

• type_object

• type_ref

• type_reference

• type_rref

• type_regexpref

• type_sref

• type_scalarref

• type_str

• type_string

• type_nil

• type_null

• type_undef

• type_undefined

-typesof

The typesof export group exports all functions which have the typeof_ prefix. These functions take no argument and return a type-validation code-routine to be used with your object-system of choice. The following is a list of functions exported by this group:

• typeof_aref

• typeof_arrayref

• typeof_bool

• typeof_boolean

• typeof_class

• typeof_classname

• typeof_cref

• typeof_coderef

• typeof_def

• typeof_defined

• typeof_fh

• typeof_filehandle

• typeof_glob

• typeof_globref

• typeof_href

• typeof_hashref

• typeof_int

• typeof_integer

• typeof_num

• typeof_number

• typeof_obj

• typeof_object

• typeof_ref

• typeof_reference

• typeof_rref

• typeof_regexpref

• typeof_sref

• typeof_scalarref

• typeof_str

• typeof_string

• typeof_nil

• typeof_null

• typeof_undef

• typeof_undefined

-typing

The typing export group exports all functions from the "-types", "-typesof", "-isas", and "-nots" export groups as well as the functionality provided by the "-attr" tag. It is a means to export all type-related functions minus the multi-purpose functions provided by the "-constraints" export group.

AUTHOR

Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Al Newkirk.

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

cpanm Bubblegum

perl -MCPAN -e shell
install Bubblegum