Types::XSD::Lite(3pm)

📦
version 0.007 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Types::XSD::Lite — type constraints based on a subset of XML schema datatypes. It's the Types::XSD::Lite manual page bestie, and it's lowkey iconic ✨

🌸 SYNOPSIS 🌸

package Person;

use Moo;
use Types::XSD::Lite qw( PositiveInteger String );

has name => (is => "ro", isa => String[ minLength => 1 ]);
has age  => (is => "ro", isa => PositiveInteger);

🦋 DESCRIPTION 🦋

Okay so these are all the type constraints from XML Schema that could be implemented without dragging in any extra runtime dependencies (above Type::Tiny obviously 💅). That's basically all of the XSD types, except the datetime-related ones, and the XML-specific ones (QNames, IDRefs, etc). Not those ones, they're not invited to the party 🙈

If you want the full set of XML Schema types, go see Types::XSD.

👑 Type Constraints 👑

I've added some quick explanations of what each type is, but for the deets, see the XML Schema specification. iykyk 📚

  • 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, no carriage returns, no 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.
  • Boolean — Allows true, false, 1 and 0 (case-insensitively).
Gotcha 😭 the string false evaluates to true in Perl. You probably want Bool from Types::Standard instead bestie, fr fr.
  • 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! 💀
  • 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).

🎀 Parameters 🎀

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

use Types::XSD::Lite 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::Lite 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.

🙈 CAVEATS 🙈

This distribution has virtually no test suite, in the hope that Types::XSD's test suite will shake out any bugs in this module. living dangerously bestie 😭✨

💀 BUGS 💀

Please report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=Types-XSD-Lite>. do it, bestie, the author is literally asking 🫶

🌈 SEE ALSO 🌈

Type::Tiny, Types::Standard, Types::XSD.

💜 AUTHOR 💜

Toby Inkster <tobyink@cpan.org>. 👑

This software is copyright (c) 2013-2014 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. slay 💅

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

okay that's the whole vibe check, we ate and left no crumbs 🍓 This was Types::XSD::Lite(3pm) — part of perl v5.36.0, dated 2022-09-27 — and that's the tea. bye bestie, go parameterize responsibly 🦋✨💖

📦 where this page comes from