=head1 NAME

XML::Compile::Schema::BuiltInTypes - Define handling of built-in data-types

=head1 INHERITANCE

 XML::Compile::Schema::BuiltInTypes
   is a Exporter

=head1 SYNOPSIS

 # Not for end-users
 use XML::Compile::Schema::BuiltInTypes qw/%builtin_types/;

=head1 DESCRIPTION

Different schema specifications specify different available types,
but there is a lot over overlap.  The L<XML::Compile::Schema::Specs|XML::Compile::Schema::Specs>
module defines the availability, but here the types are implemented.

This implementation certainly does not try to be minimal in size: using
the restriction rules and inheritance structure defined in the schema
specification would be too slow.

=head1 FUNCTIONS

The functions named in this chapter are all used at compile-time
by the translator.  At that moment, they will be placed in the
kind-of opcode tree which will process the data at run-time.
You B<cannot call> these functions yourself.

=head2 Any

B<anySimpleType>

=over 4

=back

B<anyType>

=over 4

Both any*Type built-ins can contain any kind of data.  Perl decides how
to represent the passed values.

=back

=head2 Ungrouped types

B<boolean>

=over 4

Contains C<true>, C<false>, C<1> (is true), or C<0> (is false).
When the writer sees a value equal to 'true' or 'false', those are
used.  Otherwise, the trueth value is evaluated into '0' or '1'.

The reader will return '0' (also when the XML contains the string
'false', to simplify the Perl code) or '1'.

=back

B<pattern>

=over 4

=back

=head2 Big Integers

Schema's define integer types which are derived from the C<decimal>
type.  These values can grow enormously large, and therefore can only be
handled correctly using Math::BigInt.  When the translator is
built with the C<sloppy_integers> option, this will simplify (speed-up)
the produced code considerably: all integers then shall be between
-2G and +2G.

B<integer>

=over 4

An integer with an undertermined (but possibly large) number of
digits.

=back

B<long>

=over 4

A little bit shorter than an integer, but still up-to 19 digits.

=back

B<negativeInteger>

=over 4

=back

B<nonNegativeInteger>

=over 4

=back

B<nonPositiveInteger>

=over 4

=back

B<positiveInteger>

=over 4

=back

B<unsignedInt>

=over 4

Just too long to fit in Perl's ints.

=back

B<unsignedLong>

=over 4

Value up-to 20 digits.

=back

=head2 Integers

B<byte>

=over 4

Signed 8-bits value.

=back

B<int>

=over 4

=back

B<precissionDecimal>

=over 4

PARTIAL IMPLEMENTATION.  Special values INF and NaN not handled.

=back

B<short>

=over 4

Signed 16-bits value.

=back

B<unsigned>(Short)

=over 4

unsigned 16-bits value.

=back

B<unsignedByte>

=over 4

Unsigned 8-bits value.

=back

=head2 Floating-point

PARTIAL IMPLEMENTATION: INF, NaN not handled.  The C<float> is not limited
in size, but mapped on double.

B<decimal>

=over 4

Decimals are painful: they can be very large, much larger than Perl's
internal floats.  The value is therefore kept as string.
Use Math::BigFloat when you need calculations.  You can also pass such
object here.

=back

B<double>

=over 4

A floating-point value.

=back

B<float>

=over 4

A small floating-point value.

=back

=head2 Encoding

B<base64Binary>

=over 4

In the hash, it will be kept as binary data.  In XML, it will be
base64 encoded.

=back

B<hexBinary>

=over 4

In the hash, it will be kept as binary data.  In XML, it will be
hex encoded, two hex digits per byte.

=back

=head2 Dates

B<date>

=over 4

A day, represented in localtime as C<YYYY-MM-DD> or C<YYYY-MM-DD[-+]HH:mm>.
When a decimal value is passed, it is interpreted as C<time> value in UTC,
and will be formatted as required.  When reading, the date string will
not be parsed.

=back

B<dateTime>

=over 4

A moment, represented in localtime as "date T time tz", where date is
C<YYYY-MM-DD>, time is C<HH:MM:SS> and optional, and time-zone tz
is either C<-HH:mm>, C<+HH:mm>, or C<Z> for UTC.

When a decimal value is passed, it is interpreted as C<time> value in UTC,
and will be formatted as required.  When reading, the date string will
not be parsed.

=back

B<gDay>

=over 4

Format C<---12> or C<---12+09:00> (12 days, optional time-zone)

=back

B<gMonth>

=over 4

Format C<--09> or C<--09+07:00> (9 months, optional time-zone)

=back

B<gMonthDay>

=over 4

Format C<--09-12> or C<--09-12+07:00> (9 months 12 days, optional time-zone)

=back

B<gYear>

=over 4

Format C<2006> or C<2006+07:00> (year 2006, optional time-zone)

=back

B<gYearMonth>

=over 4

Format C<2006-11> or C<2006-11+07:00> (november 2006, optional time-zone)

=back

B<time>

=over 4

An moment in time, as can happen every day.

=back

=head2 Duration

B<dayTimeDuration>

=over 4

Format C<-PnDTnHnMnS>, where optional starting C<-> means negative.
The C<P> is obligatory, and the C<T> indicates start of a time part.
All other C<n[DHMS]> are optional.

=back

B<duration>

=over 4

Format C<-PnYnMnDTnHnMnS>, where optional starting C<-> means negative.
The C<P> is obligatory, and the C<T> indicates start of a time part.
All other C<n[YMDHMS]> are optional.

=back

B<yearMonthDuration>

=over 4

Format C<-PnYnMn>, where optional starting C<-> means negative.
The C<P> is obligatory, the C<n[YM]> are optional.

=back

=head2 Strings

B<ID>(, IDREF, IDREFS)

=over 4

A label, reference to a label, or set of references.

PARTIAL IMPLEMENTATION: the validity of used characters is not checked.

=back

B<NCName>(, ENTITY, ENTITIES)

=over 4

A name which contains no colons (a non-colonized name).

=back

B<Name>

=over 4

=back

B<language>

=over 4

An RFC3066 language indicator.

=back

B<normalizedString>

=over 4

String where all sequence of white-spaces (including new-lines) are
interpreted as one blank.  Blanks at beginning and the end of the
string are ignored.

=back

B<string>

=over 4

(Usually utf8) string.

=back

B<token>(, NMTOKEN, NMTOKENS)

=over 4

=back

=head2 URI

B<NOTATION>

=over 4

NOT IMPLEMENTED, so treated as string.

=back

B<QName>

=over 4

A qualified type name: a type name with optional prefix.  The prefix notation
C<prefix:type> will be translated into the C<{$ns}type> notation.

For writers, this translation can only happen when the C<$ns> is also
in use on some other place in the message: the name-space declaration
can not be added at run-time.  In other cases, you will get a run-time
error.  Play with L<XML::Compile::Schema::compile(prefixes)|XML::Compile::Schema/"Compilers">,
predefining evenything what may be used, setting the C<used> count to C<1>.

=back

B<anyURI>

=over 4

You may pass a string or, for instance, an URI object which will be
stringified into an URI.  When read, the data will not automatically
be translated into an URI object: it may not be used that way.

=back

=head2 only in 1999 and 2000/10 schemas

B<binary>

=over 4

Perl strings can contain any byte, also nul-strings, so can
contain any sequence of bits.  Limited to byte length.

=back

B<timeDuration>

=over 4

'Old' name for L<duration()|XML::Compile::Schema::BuiltInTypes/"Duration">.

=back

B<uriReference>

=over 4

Probably the same rules as L<anyURI()|XML::Compile::Schema::BuiltInTypes/"URI">.

=pod how to do these constants?

$builtin_types{century}       = {                     period => 'P100Y' }
$builtin_types{recurringDate} = { duration => 'P24H', period => 'P1Y'   }
$builtin_types{recurringDay}  = { duration => 'P24H', period => 'P1M'   }
$builtin_types{timeInstant}   = { duration => 'P0Y',  period => 'P0Y'   }
$builtin_types{timePeriod}    = { duration => 'P0Y' }
$builtin_types{year}          = {                     period => 'P1Y'   }
$builtin_types{recurringDuration} = ??

=back

=head1 SEE ALSO

This module is part of XML-Compile distribution version 0.94,
built on August 26, 2008. Website: F<http://perl.overmeer.net/xml-compile/>

All modules in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Rewrite>,
L<XML::Compile::Dumper>.

Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile>
For life contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.

=head1 LICENSE

Copyrights 2006-2008 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>