NAME
    Types::XSD - type constraints based on XML schema datatypes

SYNOPSIS
       package Person;
   
       use Moo;
       use Types::XSD qw( PositiveInteger String );
   
       has name => (is => "ro", isa => String[ minLength => 1 ]);
       has age  => (is => "ro", isa => PositiveInteger);

DESCRIPTION
    Types::XSD is a type constraint library inspired by XML 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 OO framework.

    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.

  Type Constraints
    This module defines the following type constraints based on the data types
    defined in XML Schema <http://www.w3.org/TR/xmlschema-2/>. (The names of
    the type constraints are the same as the XML Schema data types, but
    capitalization often differs.)

    I've added some quick explainations of what each type is, but for details,
    see the XML Schema specification.

    `AnyType`
        As per `Any` from Types::Standard.

    `AnySimpleType`
        As per `Value` from Types::Standard.

    `String`
        As per `Str` from Types::Standard.

    `NormalizedString`
        A string containing no line breaks, carriage returns or tabs.

    `Token`
        Like `NormalizedString`, but also no leading or trailing space, and no
        doubled spaces (i.e. not `/\s{2,}/`).

    `Language`
        An RFC 3066 language code.

    `Name`
        Something that could be a valid XML 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.)

    `NmToken`
        Slightly looser version of `Name`; allows digits, hyphens and stops in
        the first character.

    `NmTokens`
        Space-separated list of `NmToken`.

    `NCName`
        Slightly tighter vesion of `Name`; disallows colons.

    `Id`
        Effectively the same as `NCName`.

    `IdRef`
        Effectively the same as `NCName`.

    `IdRefs`
        Space-separated list of `IdRef`.

    `Entity`
        Effectively the same as `NCName`.

    `Entities`
        Space-separated list of `Entity`.

    `Boolean`
        Allows "true", "false", "1" and "0" (case-insensitively).

        Gotcha: The string "false" evaluates to true in Perl. You probably
        want to use `Bool` from Types::Standard instead.

    `Base64Binary`
        Strings which are valid Base64 data. Allows whitespace.

        Gotcha: If you parameterize this with `length`, `maxLength` or
        `minLength`, it is the length of the *decoded* string which will be
        checked.

    `HexBinary`
        Strings which are valid hexadecimal data. Disallows whitespace;
        disallows leading `0x`.

        Gotcha: If you parameterize this with `length`, `maxLength` or
        `minLength`, it is the length of the *decoded* string which will be
        checked.

    `Float`
        As per `Num` from Types::Standard.

    `Double`
        As per `Num` from Types::Standard.

    `AnyURI`
        Any absolute *or relative* URI. Effectively, any string at all!

    `QName`
        An XML QName; something that could be used as a valid element name in
        a namespaced XML document.

        Gotcha: while `length`, `maxLength` and `minLength` are allowed facets
        for parameterization, they are silently ignored, as per the
        specification!

    `Notation`
        Effectively the same as `QName`. According to XML Schema, this is
        *always* supposed to be parameterized with an enumeration. But we
        don't enforce that.

        Gotcha: while `length`, `maxLength` and `minLength` are allowed facets
        for parameterization, they are silently ignored, as per the
        specification!

    `Decimal`
        Numbers possibly including a decimal point, but not allowing
        exponential notation (e.g. "3.14e-3").

    `Integer`
        As per `Int` from Types::Standard.

    `NonPositiveInteger`
        An `Integer` 0 or below.

    `NegativeInteger`
        An `Integer` -1 or below.

    `Long`
        An `Integer` between -9223372036854775808 and 9223372036854775807
        (inclusive).

    `Int`
        An `Integer` between -2147483648 and 2147483647 (inclusive).

    `Short`
        An `Integer` between -32768 and 32767 (inclusive).

    `Byte`
        An `Integer` between -128 and 127 (inclusive).

    `NonNegativeInteger`
        An `Integer` 0 or above.

    `PositiveInteger`
        An `Integer` 1 or above.

    `UnsignedLong`
        A `NonNegativeInteger` between 0 and 18446744073709551615 (inclusive).

    `UnsignedInt`
        A `NonNegativeInteger` between 0 and 4294967295 (inclusive).

    `UnsignedShort`
        A `NonNegativeInteger` between 0 and 65535 (inclusive).

    `UnsignedByte`
        A `NonNegativeInteger` between 0 and 255 (inclusive).

    `Duration`
        An ISO 8601 duration.

    `YearMonthDuration`
        An ISO 8601 duration restricted to cover only years and months.

    `DayTimeDuration`
        An ISO 8601 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.)

    `DateTime`
        An ISO 8601 datetime with optional timezone.

    `DateTimeStamp`
        An ISO 8601 datetime with required timezone.

    `Time`
        An ISO 8601 time with optional timezone.

    `Date`
        An ISO 8601 date with optional timezone.

    `GYearMonth`
        An year-month pair with optional timezone.

    `GYear`
        An year with optional timezone.

    `GMonthDay`
        An month-day pair with optional timezone.

    `GDay`
        An day with optional timezone.

    `GMonth`
        An month with optional timezone.

  Parameters
    Datatypes can be parameterized using the facets defined by XML Schema. For
    example:

       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 => \@sizes ]);

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

    `enumeration`
        An arrayref of allowable values. You should probably use
        Type::Tiny::Enum instead.

    `pattern`
        A regular expression that the value is expected to conform to. Use a
        normal Perl quoted regexp:

           Token[ pattern => qr{^[a-z]+$} ]

    `whiteSpace`
        The `whiteSpace` 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.

    `assertions`
        An arrayref of arbitrary additional restrictions, expressed as strings
        of Perl code or coderefs operating on $_.

        For example:

           Integer[
              assertions => [
                 '$_ % 3 == 0',            # multiple of three, and...
                 sub { is_nice($_) },      # is nice (whatever that means)
              ],
           ],

        Strings of Perl code will result in faster-running type constraints.

    `length`, `maxLength`, `minLength`
        Restrict the length of a value. For example `Integer[length=>2]`
        allows 10, 99 and -1, but not 100, 9 or -10.

        Types::XSD won't prevent you from making ridiculous constraints such
        as `String[ maxLength => 1, minLength => 2 ]`.

        Note that on `HexBinary` and `Base64Binary` types, the lengths apply
        to the decoded string. Length restrictions are silently ignored for
        `QName` and `Notation` because the W3C doesn't think you should care
        what length these datatypes are.

    `maxInclusive`, `minInclusive`, `maxExclusive`, `minExclusive`
        Supported for numeric types and datetime/duration-related types.

        Note that to be super-correct, the `{max,min}{Inclusive,Exclusive}`
        facets for numeric types are performed by passing the numbers through
        Math::BigInt or Math::BigFloat, so may be a little slow.

    `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
        `Decimal[ totalDigits => 3 ]`, 1.23, 12.3, 123, 1.2 and 1 are all
        allowable; 1.234 is not. 1.230 is also not, but this may change in a
        future version.

    `fractionDigits`
        Like `totalDigits` but ignores digits before the decimal point.

    `explicitTimezone`
        May be "optional", "prohibited" or "required". For example:

           Time[ explicitTimezone => "prohibited" ]

  Functions
    This module also exports some convenience functions:

    `dur_parse($str)`
        Parse an xsd:duration string, returning a DateTime::Duration.

    `dur_cmp($a, $b)`
        Compare two strings conforming to the xsd:duration datatype to
        indicate which is the longer duration.

        Returns -1 if $a is shorter. Returns 1 if $b is shorter. Returns 0 if
        the durations are identical. Returns undef if the comparison is
        indeterminate; for example, "P1Y" (one year) and "P365D" (365 days)
        are not necessarily identical - in leap years "P365D" is shorter.

    `dt_cmp($type, $a, $b)`
        Compare two datetime-like strings. For example, two `gYearMonth`
        strings can be compared using:

           dt_cmp(GYearMonth, "2009-02", "2010-10");

        Both strings are expected to conform to the same datatype. It doesn't
        make much sense to compare them otherwise.

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

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=Types-XSD>.

SEE ALSO
    Type::Tiny, Types::XSD::Lite, Types::Standard.

    *   <http://www.w3.org/TR/xmlschema-2/> Datatypes in XML Schema 1.0

    *   <http://www.w3.org/TR/xmlschema11-2/> Datatypes in XML Schema 1.1

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2013-2014, 2021 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

