File: README

package info (click to toggle)
libtypes-xsd-lite-perl 0.006-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, sid
  • size: 180 kB
  • sloc: perl: 381; makefile: 2; sh: 1
file content (222 lines) | stat: -rw-r--r-- 7,311 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
NAME
    Types::XSD::Lite - type constraints based on a subset of XML schema
    datatypes

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
    These are all the type constraints from XML Schema that could be
    implemented without introducing extra runtime dependencies (above
    Type::Tiny). That's basically all of the XSD types, except
    datetime-related ones, and XML-specific ones (QNames, IDRefs, etc).

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

  Type Constraints
    I've added some quick explanations 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.

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

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

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

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

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