NAME

Types::Serialiser - simple data types for common serialisation formats

SYNOPSIS

DESCRIPTION

This module provides some extra datatypes that are used by common serialisation formats such as JSON or CBOR. The idea is to have a repository of simple/small constants and containers that can be shared by different implementations so they become interoperable between each other.

SIMPLE SCALAR CONSTANTS

Simple scalar constants are values that are overloaded to act like simple Perl values, but have (class) type to differentiate them from normal Perl scalars. This is necessary because these have different representations in the serialisation formats.

BOOLEANS (Types::Serialiser::Boolean class)

This type has only two instances, true and false. A natural representation for these in Perl is 1 and 0, but serialisation formats need to be able to differentiate between them and mere numbers.

$Types::Serialiser::true, Types::Serialiser::true

This value represents the "true" value. In most contexts is acts like the number 1. It is up to you whether you use the variable form ($Types::Serialiser::true) or the constant form (Types::Serialiser::true).

The constant is represented as a reference to a scalar containing 1 - implementations are allowed to directly test for this.

$Types::Serialiser::false, Types::Serialiser::false

This value represents the "false" value. In most contexts is acts like the number 0. It is up to you whether you use the variable form ($Types::Serialiser::false) or the constant form (Types::Serialiser::false).

The constant is represented as a reference to a scalar containing 0 - implementations are allowed to directly test for this.

$is_bool = Types::Serialiser::is_bool $value

Returns true iff the $value is either $Types::Serialiser::true or $Types::Serialiser::false.

For example, you could differentiate between a perl true value and a Types::Serialiser::true by using this:

$value && Types::Serialiser::is_bool $value

$is_true = Types::Serialiser::is_true $value

Returns true iff $value is $Types::Serialiser::true.

$is_false = Types::Serialiser::is_false $value

Returns false iff $value is $Types::Serialiser::false.

ERROR (Types::Serialiser::Error class)

This class has only a single instance, error. It is used to signal an encoding or decoding error. In CBOR for example, and object that couldn't be encoded will be represented by a CBOR undefined value, which is represented by the error value in Perl.

$Types::Serialiser::error, Types::Serialiser::error

This value represents the "error" value. Accessing values of this type will throw an exception.

The constant is represented as a reference to a scalar containing undef - implementations are allowed to directly test for this.

$is_error = Types::Serialiser::is_error $value

Returns false iff $value is $Types::Serialiser::error.

NOTES FOR XS USERS

The recommended way to detect whether a scalar is one of these objects is to check whether the stash is the Types::Serialiser::Boolean or Types::Serialiser::Error stash, and then follow the scalar reference to see if it's 1 (true), 0 (false) or undef (error).

While it is possible to use an isa test, directly comparing stash pointers is faster and guaranteed to work.

BUGS

The use of overload makes this module much heavier than it should be (on my system, this module: 4kB RSS, overload: 260kB RSS).

SEE ALSO

Currently, JSON::XS and CBOR::XS use these types.

AUTHOR

Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/