.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Types::XSD 3pm"
.TH Types::XSD 3pm "2021-02-07" "perl v5.32.1" "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"
Types::XSD \- type constraints based on XML schema datatypes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   package Person;
\&   
\&   use Moo;
\&   use Types::XSD qw( PositiveInteger String );
\&   
\&   has name => (is => "ro", isa => String[ minLength => 1 ]);
\&   has age  => (is => "ro", isa => PositiveInteger);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Types::XSD is a type constraint library inspired by \s-1XML\s0 Schema, and built
with Type::Library. It can be used as a type constraint library for
Moo, Mouse or Moose, or used completely independently of any \s-1OO\s0
framework.
.PP
This module is an extension of Types::XSD::Lite (which has fewer type
constraints, but fewer dependencies). For completeness, the type constraints
and other features inherited from Types::XSD::Lite are documented below
too.
.SS "Type Constraints"
.IX Subsection "Type Constraints"
This module defines the following type constraints based on the data types
defined in \s-1XML\s0 Schema <http://www.w3.org/TR/xmlschema-2/>. (The names of
the type constraints are the same as the \s-1XML\s0 Schema data types, but
capitalization often differs.)
.PP
I've added some quick explainations of what each type is, but for details,
see the \s-1XML\s0 Schema specification.
.ie n .IP """AnyType""" 4
.el .IP "\f(CWAnyType\fR" 4
.IX Item "AnyType"
As per \f(CW\*(C`Any\*(C'\fR from Types::Standard.
.ie n .IP """AnySimpleType""" 4
.el .IP "\f(CWAnySimpleType\fR" 4
.IX Item "AnySimpleType"
As per \f(CW\*(C`Value\*(C'\fR from Types::Standard.
.ie n .IP """String""" 4
.el .IP "\f(CWString\fR" 4
.IX Item "String"
As per \f(CW\*(C`Str\*(C'\fR from Types::Standard.
.ie n .IP """NormalizedString""" 4
.el .IP "\f(CWNormalizedString\fR" 4
.IX Item "NormalizedString"
A string containing no line breaks, carriage returns or tabs.
.ie n .IP """Token""" 4
.el .IP "\f(CWToken\fR" 4
.IX Item "Token"
Like \f(CW\*(C`NormalizedString\*(C'\fR, but also no leading or trailing space, and no
doubled spaces (i.e. not \f(CW\*(C`/\es{2,}/\*(C'\fR).
.ie n .IP """Language""" 4
.el .IP "\f(CWLanguage\fR" 4
.IX Item "Language"
An \s-1RFC 3066\s0 language code.
.ie n .IP """Name""" 4
.el .IP "\f(CWName\fR" 4
.IX Item "Name"
Something that could be a valid \s-1XML\s0 element or attribute name. These roughly
correspond to Perl identifiers but may also contain colons, hyphens and stops.
(Digits, hyphens and stops are not allowed as the first character.)
.ie n .IP """NmToken""" 4
.el .IP "\f(CWNmToken\fR" 4
.IX Item "NmToken"
Slightly looser version of \f(CW\*(C`Name\*(C'\fR; allows digits, hyphens and stops in the
first character.
.ie n .IP """NmTokens""" 4
.el .IP "\f(CWNmTokens\fR" 4
.IX Item "NmTokens"
Space-separated list of \f(CW\*(C`NmToken\*(C'\fR.
.ie n .IP """NCName""" 4
.el .IP "\f(CWNCName\fR" 4
.IX Item "NCName"
Slightly tighter vesion of \f(CW\*(C`Name\*(C'\fR; disallows colons.
.ie n .IP """Id""" 4
.el .IP "\f(CWId\fR" 4
.IX Item "Id"
Effectively the same as \f(CW\*(C`NCName\*(C'\fR.
.ie n .IP """IdRef""" 4
.el .IP "\f(CWIdRef\fR" 4
.IX Item "IdRef"
Effectively the same as \f(CW\*(C`NCName\*(C'\fR.
.ie n .IP """IdRefs""" 4
.el .IP "\f(CWIdRefs\fR" 4
.IX Item "IdRefs"
Space-separated list of \f(CW\*(C`IdRef\*(C'\fR.
.ie n .IP """Entity""" 4
.el .IP "\f(CWEntity\fR" 4
.IX Item "Entity"
Effectively the same as \f(CW\*(C`NCName\*(C'\fR.
.ie n .IP """Entities""" 4
.el .IP "\f(CWEntities\fR" 4
.IX Item "Entities"
Space-separated list of \f(CW\*(C`Entity\*(C'\fR.
.ie n .IP """Boolean""" 4
.el .IP "\f(CWBoolean\fR" 4
.IX Item "Boolean"
Allows \f(CW"true"\fR, \f(CW"false"\fR, \f(CW"1"\fR and \f(CW"0"\fR
(case-insensitively).
.Sp
Gotcha: The string \f(CW"false"\fR evaluates to true in Perl. You probably
want to use \f(CW\*(C`Bool\*(C'\fR from Types::Standard instead.
.ie n .IP """Base64Binary""" 4
.el .IP "\f(CWBase64Binary\fR" 4
.IX Item "Base64Binary"
Strings which are valid Base64 data. Allows whitespace.
.Sp
Gotcha: If you parameterize this with \f(CW\*(C`length\*(C'\fR, \f(CW\*(C`maxLength\*(C'\fR or \f(CW\*(C`minLength\*(C'\fR,
it is the length of the \fIdecoded\fR string which will be checked.
.ie n .IP """HexBinary""" 4
.el .IP "\f(CWHexBinary\fR" 4
.IX Item "HexBinary"
Strings which are valid hexadecimal data. Disallows whitespace; disallows
leading \f(CW\*(C`0x\*(C'\fR.
.Sp
Gotcha: If you parameterize this with \f(CW\*(C`length\*(C'\fR, \f(CW\*(C`maxLength\*(C'\fR or \f(CW\*(C`minLength\*(C'\fR,
it is the length of the \fIdecoded\fR string which will be checked.
.ie n .IP """Float""" 4
.el .IP "\f(CWFloat\fR" 4
.IX Item "Float"
As per \f(CW\*(C`Num\*(C'\fR from Types::Standard.
.ie n .IP """Double""" 4
.el .IP "\f(CWDouble\fR" 4
.IX Item "Double"
As per \f(CW\*(C`Num\*(C'\fR from Types::Standard.
.ie n .IP """AnyURI""" 4
.el .IP "\f(CWAnyURI\fR" 4
.IX Item "AnyURI"
Any absolute \fIor relative\fR \s-1URI.\s0 Effectively, any string at all!
.ie n .IP """QName""" 4
.el .IP "\f(CWQName\fR" 4
.IX Item "QName"
An \s-1XML\s0 QName; something that could be used as a valid element name in a
namespaced \s-1XML\s0 document.
.Sp
Gotcha: while \f(CW\*(C`length\*(C'\fR, \f(CW\*(C`maxLength\*(C'\fR and \f(CW\*(C`minLength\*(C'\fR are allowed facets for
parameterization, they are silently ignored, as per the specification!
.ie n .IP """Notation""" 4
.el .IP "\f(CWNotation\fR" 4
.IX Item "Notation"
Effectively the same as \f(CW\*(C`QName\*(C'\fR. According to \s-1XML\s0 Schema, this is \fIalways\fR
supposed to be parameterized with an enumeration. But we don't enforce that.
.Sp
Gotcha: while \f(CW\*(C`length\*(C'\fR, \f(CW\*(C`maxLength\*(C'\fR and \f(CW\*(C`minLength\*(C'\fR are allowed facets for
parameterization, they are silently ignored, as per the specification!
.ie n .IP """Decimal""" 4
.el .IP "\f(CWDecimal\fR" 4
.IX Item "Decimal"
Numbers possibly including a decimal point, but not allowing exponential
notation (e.g. \f(CW"3.14e\-3"\fR).
.ie n .IP """Integer""" 4
.el .IP "\f(CWInteger\fR" 4
.IX Item "Integer"
As per \f(CW\*(C`Int\*(C'\fR from Types::Standard.
.ie n .IP """NonPositiveInteger""" 4
.el .IP "\f(CWNonPositiveInteger\fR" 4
.IX Item "NonPositiveInteger"
An \f(CW\*(C`Integer\*(C'\fR 0 or below.
.ie n .IP """NegativeInteger""" 4
.el .IP "\f(CWNegativeInteger\fR" 4
.IX Item "NegativeInteger"
An \f(CW\*(C`Integer\*(C'\fR \-1 or below.
.ie n .IP """Long""" 4
.el .IP "\f(CWLong\fR" 4
.IX Item "Long"
An \f(CW\*(C`Integer\*(C'\fR between \-9223372036854775808 and 9223372036854775807 (inclusive).
.ie n .IP """Int""" 4
.el .IP "\f(CWInt\fR" 4
.IX Item "Int"
An \f(CW\*(C`Integer\*(C'\fR between \-2147483648 and 2147483647 (inclusive).
.ie n .IP """Short""" 4
.el .IP "\f(CWShort\fR" 4
.IX Item "Short"
An \f(CW\*(C`Integer\*(C'\fR between \-32768 and 32767 (inclusive).
.ie n .IP """Byte""" 4
.el .IP "\f(CWByte\fR" 4
.IX Item "Byte"
An \f(CW\*(C`Integer\*(C'\fR between \-128 and 127 (inclusive).
.ie n .IP """NonNegativeInteger""" 4
.el .IP "\f(CWNonNegativeInteger\fR" 4
.IX Item "NonNegativeInteger"
An \f(CW\*(C`Integer\*(C'\fR 0 or above.
.ie n .IP """PositiveInteger""" 4
.el .IP "\f(CWPositiveInteger\fR" 4
.IX Item "PositiveInteger"
An \f(CW\*(C`Integer\*(C'\fR 1 or above.
.ie n .IP """UnsignedLong""" 4
.el .IP "\f(CWUnsignedLong\fR" 4
.IX Item "UnsignedLong"
A \f(CW\*(C`NonNegativeInteger\*(C'\fR between 0 and 18446744073709551615 (inclusive).
.ie n .IP """UnsignedInt""" 4
.el .IP "\f(CWUnsignedInt\fR" 4
.IX Item "UnsignedInt"
A \f(CW\*(C`NonNegativeInteger\*(C'\fR between 0 and 4294967295 (inclusive).
.ie n .IP """UnsignedShort""" 4
.el .IP "\f(CWUnsignedShort\fR" 4
.IX Item "UnsignedShort"
A \f(CW\*(C`NonNegativeInteger\*(C'\fR between 0 and 65535 (inclusive).
.ie n .IP """UnsignedByte""" 4
.el .IP "\f(CWUnsignedByte\fR" 4
.IX Item "UnsignedByte"
A \f(CW\*(C`NonNegativeInteger\*(C'\fR between 0 and 255 (inclusive).
.ie n .IP """Duration""" 4
.el .IP "\f(CWDuration\fR" 4
.IX Item "Duration"
An \s-1ISO 8601\s0 duration.
.ie n .IP """YearMonthDuration""" 4
.el .IP "\f(CWYearMonthDuration\fR" 4
.IX Item "YearMonthDuration"
An \s-1ISO 8601\s0 duration restricted to cover only years and months.
.ie n .IP """DayTimeDuration""" 4
.el .IP "\f(CWDayTimeDuration\fR" 4
.IX Item "DayTimeDuration"
An \s-1ISO 8601\s0 duration restricted to cover only days, hours, minutes and
seconds. (Note that this still permits durations of many years, as the
days component is an arbitrary non-negative integer.)
.ie n .IP """DateTime""" 4
.el .IP "\f(CWDateTime\fR" 4
.IX Item "DateTime"
An \s-1ISO 8601\s0 datetime with optional timezone.
.ie n .IP """DateTimeStamp""" 4
.el .IP "\f(CWDateTimeStamp\fR" 4
.IX Item "DateTimeStamp"
An \s-1ISO 8601\s0 datetime with required timezone.
.ie n .IP """Time""" 4
.el .IP "\f(CWTime\fR" 4
.IX Item "Time"
An \s-1ISO 8601\s0 time with optional timezone.
.ie n .IP """Date""" 4
.el .IP "\f(CWDate\fR" 4
.IX Item "Date"
An \s-1ISO 8601\s0 date with optional timezone.
.ie n .IP """GYearMonth""" 4
.el .IP "\f(CWGYearMonth\fR" 4
.IX Item "GYearMonth"
An year-month pair with optional timezone.
.ie n .IP """GYear""" 4
.el .IP "\f(CWGYear\fR" 4
.IX Item "GYear"
An year with optional timezone.
.ie n .IP """GMonthDay""" 4
.el .IP "\f(CWGMonthDay\fR" 4
.IX Item "GMonthDay"
An month-day pair with optional timezone.
.ie n .IP """GDay""" 4
.el .IP "\f(CWGDay\fR" 4
.IX Item "GDay"
An day with optional timezone.
.ie n .IP """GMonth""" 4
.el .IP "\f(CWGMonth\fR" 4
.IX Item "GMonth"
An month with optional timezone.
.SS "Parameters"
.IX Subsection "Parameters"
Datatypes can be parameterized using the facets defined by \s-1XML\s0 Schema. For
example:
.PP
.Vb 1
\&   use Types::XSD qw( String Decimal PositiveInteger Token );
\&   
\&   my @sizes = qw( XS S M L XL XXL );
\&   
\&   has name   => (is => "ro", isa => String[ minLength => 1 ]);
\&   has price  => (is => "ro", isa => Decimal[ fractionDigits => 2 ]);
\&   has rating => (is => "ro", isa => PositiveInteger[ maxInclusive => 5 ]);
\&   has size   => (is => "ro", isa => Token[ enumeration => \e@sizes ]);
.Ve
.PP
The following facets exist, but not all facets are supported for all
datatypes. (The module will croak if you try to use an unsupported facet.)
.ie n .IP """enumeration""" 4
.el .IP "\f(CWenumeration\fR" 4
.IX Item "enumeration"
An arrayref of allowable values. You should probably use Type::Tiny::Enum
instead.
.ie n .IP """pattern""" 4
.el .IP "\f(CWpattern\fR" 4
.IX Item "pattern"
A regular expression that the value is expected to conform to. Use a normal
Perl quoted regexp:
.Sp
.Vb 1
\&   Token[ pattern => qr{^[a\-z]+$} ]
.Ve
.ie n .IP """whiteSpace""" 4
.el .IP "\f(CWwhiteSpace\fR" 4
.IX Item "whiteSpace"
The \f(CW\*(C`whiteSpace\*(C'\fR facet is ignored as I'm not entirely sure what it should
do. It perhaps makes sense for coercions, but this module doesn't define any
coercions.
.ie n .IP """assertions""" 4
.el .IP "\f(CWassertions\fR" 4
.IX Item "assertions"
An arrayref of arbitrary additional restrictions, expressed as strings of
Perl code or coderefs operating on \f(CW$_\fR.
.Sp
For example:
.Sp
.Vb 6
\&   Integer[
\&      assertions => [
\&         \*(Aq$_ % 3 == 0\*(Aq,            # multiple of three, and...
\&         sub { is_nice($_) },      # is nice (whatever that means)
\&      ],
\&   ],
.Ve
.Sp
Strings of Perl code will result in faster-running type constraints.
.ie n .IP """length"", ""maxLength"", ""minLength""" 4
.el .IP "\f(CWlength\fR, \f(CWmaxLength\fR, \f(CWminLength\fR" 4
.IX Item "length, maxLength, minLength"
Restrict the length of a value. For example \f(CW\*(C`Integer[length=>2]\*(C'\fR allows
\&\f(CW10\fR, \f(CW99\fR and \f(CW\*(C`\-1\*(C'\fR, but not \f(CW100\fR, \f(CW9\fR or \f(CW\*(C`\-10\*(C'\fR.
.Sp
Types::XSD won't prevent you from making ridiculous constraints such as
\&\f(CW\*(C`String[ maxLength => 1, minLength => 2 ]\*(C'\fR.
.Sp
Note that on \f(CW\*(C`HexBinary\*(C'\fR and \f(CW\*(C`Base64Binary\*(C'\fR types, the lengths apply to
the decoded string. Length restrictions are silently ignored for \f(CW\*(C`QName\*(C'\fR
and \f(CW\*(C`Notation\*(C'\fR because the W3C doesn't think you should care what length
these datatypes are.
.ie n .IP """maxInclusive"", ""minInclusive"", ""maxExclusive"", ""minExclusive""" 4
.el .IP "\f(CWmaxInclusive\fR, \f(CWminInclusive\fR, \f(CWmaxExclusive\fR, \f(CWminExclusive\fR" 4
.IX Item "maxInclusive, minInclusive, maxExclusive, minExclusive"
Supported for numeric types and datetime/duration\-related types.
.Sp
Note that to be super-correct, the \f(CW\*(C`{max,min}{Inclusive,Exclusive}\*(C'\fR
facets for numeric types are performed by passing the numbers through
Math::BigInt or Math::BigFloat, so may be a little slow.
.ie n .IP """totalDigits""" 4
.el .IP "\f(CWtotalDigits\fR" 4
.IX Item "totalDigits"
For a decimal (or type derived from decimals) specifies that the total number
of digits for the value must be at most this number. Given
\&\f(CW\*(C`Decimal[ totalDigits => 3 ]\*(C'\fR, \f(CW1.23\fR, \f(CW12.3\fR, \f(CW123\fR, \f(CW1.2\fR and \f(CW1\fR
are all allowable; \f(CW1.234\fR is not. \f(CW1.230\fR is also not, but this may change
in a future version.
.ie n .IP """fractionDigits""" 4
.el .IP "\f(CWfractionDigits\fR" 4
.IX Item "fractionDigits"
Like \f(CW\*(C`totalDigits\*(C'\fR but ignores digits before the decimal point.
.ie n .IP """explicitTimezone""" 4
.el .IP "\f(CWexplicitTimezone\fR" 4
.IX Item "explicitTimezone"
May be \f(CW"optional"\fR, \f(CW"prohibited"\fR or \f(CW"required"\fR. For
example:
.Sp
.Vb 1
\&   Time[ explicitTimezone => "prohibited" ]
.Ve
.SS "Functions"
.IX Subsection "Functions"
This module also exports some convenience functions:
.ie n .IP """dur_parse($str)""" 4
.el .IP "\f(CWdur_parse($str)\fR" 4
.IX Item "dur_parse($str)"
Parse an xsd:duration string, returning a DateTime::Duration.
.ie n .IP """dur_cmp($a, $b)""" 4
.el .IP "\f(CWdur_cmp($a, $b)\fR" 4
.IX Item "dur_cmp($a, $b)"
Compare two strings conforming to the xsd:duration datatype to indicate
which is the longer duration.
.Sp
Returns \-1 if \f(CW$a\fR is shorter. Returns 1 if \f(CW$b\fR is shorter. Returns 0 if the
durations are identical. Returns undef if the comparison is indeterminate;
for example, \*(L"P1Y\*(R" (one year) and \*(L"P365D\*(R" (365 days) are not necessarily
identical \- in leap years \*(L"P365D\*(R" is shorter.
.ie n .IP """dt_cmp($type, $a, $b)""" 4
.el .IP "\f(CWdt_cmp($type, $a, $b)\fR" 4
.IX Item "dt_cmp($type, $a, $b)"
Compare two datetime-like strings. For example, two \f(CW\*(C`gYearMonth\*(C'\fR strings
can be compared using:
.Sp
.Vb 1
\&   dt_cmp(GYearMonth, "2009\-02", "2010\-10");
.Ve
.Sp
Both strings are expected to conform to the same datatype. It doesn't make
much sense to compare them otherwise.
.ie n .IP """dt_parse($type, $str)""" 4
.el .IP "\f(CWdt_parse($type, $str)\fR" 4
.IX Item "dt_parse($type, $str)"
Parse a datetime-like string, returning a DateTime::Incomplete object.
Note that DateTime::Incomplete objects are always returned, even if the
datetime is potentially complete.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs to
<http://rt.cpan.org/Dist/Display.html?Queue=Types\-XSD>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Type::Tiny, Types::XSD::Lite, Types::Standard.
.IP "\(bu" 4
<http://www.w3.org/TR/xmlschema\-2/> Datatypes in \s-1XML\s0 Schema 1.0
.IP "\(bu" 4
<http://www.w3.org/TR/xmlschema11\-2/> Datatypes in \s-1XML\s0 Schema 1.1
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2013\-2014, 2021 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0