.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tangram::Type 3pm"
.TH Tangram::Type 3pm "2015-11-09" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Tangram::Type \- mapping individual fields
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Tangram's persistent type system is extensible, allowing you to mount
your own types and make them persistent. All you have to do is to
register your type and provide mapping code. See Tangram::Type::Extending.
.PP
Tangram comes with built-in support for the following types:
.IP "\fBSimple Scalar types\fR" 4
.IX Item "Simple Scalar types"
Supported are strings, integers, real numbers and dates.  More types
of this ilk are easily added.
.Sp
\&\f(CW\*(C`string\*(C'\fR, \f(CW\*(C`int\*(C'\fR, \f(CW\*(C`real\*(C'\fR: see Tangram::Type::Scalar
.Sp
\&\f(CW\*(C`date\*(C'\fR, \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`datetime\*(C'\fR, \f(CW\*(C`dmdatetime\*(C'\fR: see \*(L"Date/Type/Date/DateTime\*(R" in Tangram::Type
.IP "\fBCompound Structure types\fR" 4
.IX Item "Compound Structure types"
\&\f(CW\*(C`perl_dump\*(C'\fR: see Tangram::Type::Dump::Perl.  A \f(CW\*(C`perl_dump\*(C'\fR structure may
contain any structure which Data::Dumper can dump successfully.
.Sp
\&\f(CW\*(C`storable\*(C'\fR: see Tangram::Type::Dump::Storable.  Very much like \f(CW\*(C`perl_dump\*(C'\fR,
but implemented via the `Storable' serialisation engine.
.Sp
\&\f(CW\*(C`yaml\*(C'\fR: see Tangram::Type::Dump::YAML.  Very much like \f(CW\*(C`perl_dump\*(C'\fR, but
implemented via the `\s-1YAML\s0' serialisation engine.  Doesn't currently
work, due to inadequacies in the current Perl \s-1YAML\s0 implementation.
.Sp
\&\fB\s-1NEW\s0 in Tangram 2.08\fR:
.Sp
\&\f(CW\*(C`idbif\*(C'\fR: see Tangram::Type::Dump::Any.  Like the above, but can combine
multiple object properties into a single database column.
.IP "\fB`Flat' Array & Hash types\fR" 4
.IX Item "`Flat' Array & Hash types"
Note: these are only actually required if you need to be able to query
on individual fields inside the array/hash \- otherwise, the
\&\f(CW\*(C`perl_dump\*(C'\fR or \f(CW\*(C`idbif\*(C'\fR mapping is a lot faster and more flexible.
.Sp
\&\f(CW\*(C`flat_array\*(C'\fR: see \*(L"Array/Scalar\*(R" in Tangram::Type
.Sp
\&\f(CW\*(C`flat_hash\*(C'\fR: see \*(L"Hash/Scalar\*(R" in Tangram::Type
.IP "\fBReferences to other objects\fR" 4
.IX Item "References to other objects"
\&\f(CW\*(C`ref\*(C'\fR: see Tangram::Type::Ref::FromMany (implementing an \fBN to 1\fR relationship,
in which any object can be the referant)
.IP "\fBSets of other objects\fR" 4
.IX Item "Sets of other objects"
Set relationships are closest to the main type of relationship used in
an \s-1RDBMS. \s0 Avid CompSci students will know that the relational
database model is based heavily on `Set Theory', which is a subset of
a more general concept of `Categories' \- generic couplings of a number
of classes.
.Sp
In Perl space, these collections are represented via the Set::Object
module.  Sets may not have duplicate elements, and cannot contain
\&\fIundef\fR values.
.Sp
\&\f(CW\*(C`set\*(C'\fR: see Tangram::Type::Set::FromMany (implementing an \fIunordered\fR \fBN to N\fR
relationship, with all objects sharing a common base class)
.Sp
\&\f(CW\*(C`iset\*(C'\fR: see Tangram::Type::Set::FromOne (implementing an \fIunordered\fR \fB1 to
N\fR relationship, with all objects sharing a common base class)
.IP "\fBArrays of other objects\fR" 4
.IX Item "Arrays of other objects"
The addition to Sets, you can have `Arrays' of objects, represented by
a standard Perl array in memory.  Arrays may contain \fIundef\fR values
(in the middle of the list), and the \f(CW\*(C`array\*(C'\fR type may contain
duplicates (ie, the same element present in separate places in the
list).
.Sp
\&\f(CW\*(C`array\*(C'\fR : see Tangram::Type::Array::FromMany (implementing an \fIordered\fR \fBN to N\fR
relationship, with all objects sharing a common base class)
.Sp
\&\f(CW\*(C`iarray\*(C'\fR: see Tangram::Type::Array::FromOne (implementing an \fIordered\fR \fB1
to N\fR relationship, with all objects sharing a common base class)
.IP "\fBHashes of other objects\fR" 4
.IX Item "Hashes of other objects"
Much like the Array types, the Hash types are indexed via a string
value, and represented as a Perl hash in memory.  These hashes may not
contain \fIundef\fR values (those are dropped).  The \f(CW\*(C`hash\*(C'\fR type may
contain duplicate elements.
.Sp
\&\f(CW\*(C`hash\*(C'\fR : see Tangram::Type::Hash::FromMany (implementing a \fIkeyed\fR \fBN to N\fR
relationship, with all objects sharing a common base class)
.Sp
\&\f(CW\*(C`ihash\*(C'\fR: see Tangram::Type::Hash::FromOne (implementing a \fIkeyed\fR \fB1 to N\fR
relationship, with all objects sharing a common base class)