Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Serialiser(3)	      User Contributed Perl Documentation	 Serialiser(3)

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.

       In the following, functions with	zero or	one arguments have a prototype
       of "()" and "($)", respectively,	so act as constants and	unary
       operators.

   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.

       Types::Serialiser::as_bool $value
	   Converts a Perl scalar into a boolean, which	is useful syntactic
	   sugar. Strictly equivalent to:

	      $value ? $Types::Serialiser::true	: $Types::Serialiser::false

       $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.

       For historical reasons, the "Types::Serialiser::Boolean"	stash is just
       an alias	for "JSON::PP::Boolean". When printed, the classname with
       usually be "JSON::PP::Boolean", but isa tests and stash pointer
       comparison will normally	work correctly (i.e. Types::Serialiser::true
       ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).

A GENERIC OBJECT SERIALIATION PROTOCOL
       This section explains the object	serialisation protocol used by
       CBOR::XS. It is meant to	be generic enough to support any kind of
       generic object serialiser.

       This protocol is	called "the Types::Serialiser object serialisation
       protocol".

   ENCODING
       When the	encoder	encounters an object that it cannot otherwise encode
       (for example, CBOR::XS can encode a few special types itself, and will
       first attempt to	use the	special	"TO_CBOR" serialisation	protocol), it
       will look up the	"FREEZE" method	on the object.

       Note that the "FREEZE" method will normally be called during encoding,
       and MUST	NOT change the data structure that is being encoded in any
       way, or it might	cause memory corruption	or worse.

       If it exists, it	will call it with two arguments: the object to
       serialise, and a	constant string	that indicates the name	of the data
       model. For example CBOR::XS uses	"CBOR",	and the	JSON and JSON::XS
       modules (or any other JSON serialiser), would use "JSON"	as second
       argument.

       The "FREEZE" method can then return zero	or more	values to identify the
       object instance.	The serialiser is then supposed	to encode the class
       name and	all of these return values (which must be encodable in the
       format) using the relevant form for Perl	objects. In CBOR for example,
       there is	a registered tag number	for encoded perl objects.

       The values that "FREEZE"	returns	must be	serialisable with the
       serialiser that calls it. Therefore, it is recommended to use simple
       types such as strings and numbers, and maybe array references and
       hashes (basically, the JSON data	model).	You can	always use a more
       complex format for a specific data model	by checking the	second
       argument, the data model.

       The "data model"	is not the same	as the "data format" - the data	model
       indicates what types and	kinds of return	values can be returned from
       "FREEZE". For example, in "CBOR"	it is permissible to return tagged
       CBOR values, while JSON does not	support	these at all, so "JSON"	would
       be a valid (but too limited) data model name for	"CBOR::XS". similarly,
       a serialising format that supports more or less the same	data model as
       JSON could use "JSON" as	data model without losing anything.

   DECODING
       When the	decoder	then encounters	such an	encoded	perl object, it	should
       look up the "THAW" method on the	stored classname, and invoke it	with
       the classname, the constant string to identify the data model/data
       format, and all the return values returned by "FREEZE".

   EXAMPLES
       See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
       details,	an example implementation, and code examples.

       Here is an example "FREEZE"/"THAW" method pair:

	  sub My::Object::FREEZE {
	     my	($self,	$model)	= @_;

	     ($self->{type}, $self->{id}, $self->{variant})
	  }

	  sub My::Object::THAW {
	     my	($class, $model, $type,	$id, $variant) = @_;

	     $class->new (type => $type, id => $id, variant => $variant)
	  }

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/

perl v5.32.1			  2020-12-01			 Serialiser(3)

NAME | SYNOPSIS | DESCRIPTION | SIMPLE SCALAR CONSTANTS | NOTES FOR XS USERS | A GENERIC OBJECT SERIALIATION PROTOCOL | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Types::Serialiser&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help