=head1 NOM

DateTime::Format::Strptime - Modèles de formattage et d'analyse strp- et strftime

=head1 RÉSUMÉ

  use DateTime::Format::Strptime;

  my $Strp = new DateTime::Format::Strptime(
  				pattern     => '%T',
  				locale      => 'en_AU',
  				time_zone   => 'Australia/Melbourne',
  			);
  			
  my $dt = $Strp->parse_datetime('23:16:42');

  $Strp->format_datetime($dt);
	# 23:16:42

	
	
  # Message d'erreur si ça se passe mal

  my $Strp = new DateTime::Format::Strptime(
  				pattern 	=> '%T',
  				locale	    => 'en_AU',
  				time_zone	=> 'Australia/Melbourne',
  				on_error	=> 'croak',
  			);

  $newpattern = $Strp->pattern('%Q'); 
  # Spécification inconnue dans le schéma: %Q dans %Q à la ligne 34 de script.pl

  # Faire autre chose si ça se passe mal
  my $Strp = new DateTime::Format::Strptime(
  				pattern 	=> '%T',
  				locale	    => 'en_AU',
  				time_zone	=> 'Australia/Melbourne',
  				on_error	=> \&telephoner_a_la_police,
  			);

=head1 DESCRIPTION

Ce module implémente la plupart des fonctionnalités de C<strptime(3)>,
la fonction POSIX réciproque de C<strftime(3)>, pour
C<DateTime>. Alors que C<strftime> reçoit un objet C<DateTime> et un
schéma pour renvoyer une chaîne, C<strptime> reçoit une chaîne et un
schéma et renvoie l'objet C<DateTime> associé.

=head1 CONSTRUCTEUR

=over 4

=item * new( pattern=>$strptime_pattern )

Crée l'objet format. Vous devez spécifier un schéma, vous pouvez
également spécifier un fuseau horaire (paramètre C<time_zone>)
et un identifiant de localisation (C<locale>). Si vous spécifiez
un fuseau horaire, tout objet C<DateTime> obtenu à partir de l'objet
format dépendra de ce fuseau horaire. Si vous ne spécifiez pas
de fuseau horaire, mais que la chaîne analysée par C<parse_datetime>
en contienne un, alors l'objet C<DateTime> résultant utilisera
ce fuseau horaire.

Vous pouvez spécifier un paramètre C<on_error> optionnel pour le
comportement en cas d'erreur. Ce paramètre admet 3 S<valeurs :>

=over 4

=item * 'undef'

(pas undef, mais 'undef', c'est la chaîne de caractères, pas la valeur indéfinie)

C'est le comportement par défaut. Le module renverra C<undef> chaque
fois que quelque chose ne lui plaît pas. Vous pouvez savoir quelle est
l'erreur précise en utilisant la méthode C<$object-E<gt>errstr>.
C'est le comportement idéal pour une utilisation interactive
lorsqu'un utilisateur est susceptible de transmettre un schéma
illégal ou une date qui ne répond pas au schéma.

=item * 'croak'

(pas croak, 'croak', c'est une chaîne de caractères, pas une fonction)

C'était le comportement par défaut. Si quelque chose ne lui plaît pas,
le module s'arrête en envoyant un message d'erreur.

=item * sub{...} ou \&subname

Si le comportement est associé à une référence de code, le module
appellera cette routine si quelque chose ne lui plaît pas. Le
sous-programme reçoit deux S<paramètres :> l'objet et le message
d'erreur.  En utilisant ces deux paramètres, il est possible d'émuler
le comportement C<'undef'>. Si la routine renvoie une valeur vraie, la
méthode renvoie C<undef>.  Si la routine renvoie une valeur fausse, la
méthode continue vaille que vaille.

sub{$_[0]->{errmsg} = $_[1]; 1},

=back

=back

=head1 MÉTHODES

La classe fournit les méthodes suivantes.

=over 4

=item * parse_datetime($string)

En recevant une chaîne répondant au schéma spécifié à la construction,
la méthode renvoie un nouvel objet C<DateTime>.

Si la méthode reçoit une chaîne ne répondant pas au schéma, l'analyseur
s'arrêtera avec un message d'erreur ou renverra C<undef>, selon le
comportement spécifié dans le paramètre C<on_error> du constructeur.

=item * format_datetime($datetime)

En recevant un objet C<DateTime>, la méthode renvoie une chaîne
formattée en fonction du schéma de l'objet C<DateTime::Format::Strptime>.
Cette méthode donne le même résultat que la méthode C<strftime>
de C<DateTime>.

=item * locale($locale)

Lorsqu'elle reçoit une localisation, cette méthode associe la localisation
à l'objet. Si la méthode n'arrive pas à interprêter la localisation,
elle s'arrête avec un message d'erreur ou elle renvoie C<undef>
en fonction du paramètre C<on_error> du constructeur.

Si cette méthode aboutit, elle renvoie la localisation courante
(après avoir effectué les traitements ci-dessus).

=item * pattern($strptime_pattern)

Cette méthode, qui reçoit un schéma, met à jour l'objet pour lui
associer ce schéma. Si le schéma est invalide, la méthode s'arrêtera
avec un message d'erreur ou bien renverra C<undef> (en fonction
de la valeur du paramètre C<on_error>)

Si aucun problème ne survient, la méthode renvoie le schéma courant
(après avoir effectué les traitements ci-dessus).

=item * time_zone($time_zone)

Cette méthode reçoit un nom de fuseau horaire, un décalage horaire
ou un objet C<DateTime::TimeZone> et elle met à jour le fuseau
horaire de l'objet. Cette mise à jour se répercutera sur les objets
C<DateTime> renvoyés par la méthode C<parse_datetime>.

Si le fuseau horaire est invalide, la méthode s'arrêtera
avec un message d'erreur ou bien renverra C<undef> (en fonction
de la valeur du paramètre C<on_error>)

Si aucun problème ne survient, la méthode renvoie le fuseau horaire courant
(après avoir effectué les traitements ci-dessus).

=item * errmsg

Si le comportement C<on_error> de l'objet est C<'undef'>, vous pouvez
utiliser cette méthode pour obtenir le message d'erreur et essayer de
comprendre pour cela a mal tourné.

Le code suivant émule un objet C<$DateTime::Format::Strptime> pour
lequel le paramètre C<on_error> vaut C<'croak'>.

C<$Strp->pattern($pattern) or die $DateTime::Format::Strptime::errmsg>

=back

=head1 EXPORTS

Aucun symbole n'est exporté par défaut. Toutefois, les fonctions
suivantes sont S<disponibles :>

=over 4

=item * strptime($strptime_pattern, $string)

Cette fonction reçoit un schéma et une chaîne et renvoie un nouvel
objet C<DateTime>.

=item * strftime($strftime_pattern, $datetime)

Cette fonction reçoit un schéma et un objet C<DateTime> et renvoie
une chaîne formattée.

=back

=head1 SPÉCIFICATIONS POUR LES SCHÉMAS DE STRPTIME

Les éléments suivants sont autorisés dans les chaînes de schéma
pour C<strptime> (C<parse_datetime>):

=over 4

=item * %%

Le caractère C<%>.

=item * %a ou %A

Le nom abrégé ou complet du jour de la semaine pour la localisation courante.

=item * %b ou %B ou %h

Le nom abrégé ou complet du mois pour la localisation courante.

=item * %C

Les deux premiers chiffres de l'année, correspondant plus ou moins au
siècle (0-99).

=item * %d ou %e

Le jour du mois (1-31).

=item * %D

Équivalent à C<%m/%d/%y>. (C'est le style américain pour les dates, un
style qui prête à confusion pour le reste du monde, surtout
que le format C<%d/%m/%y> est largement utilisé en Europe.
Le format standard ISO 8601 est C<%Y-%m-%d>.)

=item * %g

Les deux derniers chiffres de l'année correspondant à la semaine ISO
(0-99).

=item * %G

L'année correspondant à la semaine ISO.

=item * %H

L'heure (0-23).

=item * %I

L'heure telle qu'elle apparaît sur le cadran d'une pendule (1-12).

=item * %j

Le numéro du jour dans l'année (1-366).

=item * %m

Le numéro du mois (1-12).

=item * %M

Les minutes (0-59).

=item * %n

Un caractère d'espacement quelconque.

=item * %N

Les nanosecondes. Pour d'autres valeurs inférieures à la seconde,
utilisez C<%[nombre]N>.

=item * %p

L'équivalent des mentions S<« AM »> et S<« PM »> pour la localisation
utilisée. (Cf. L<DateTime::Locale>)

=item * %r

Équivalent à C<%I:%M:%S %p>.

=item * %R

Équivalent à C<%H:%M>.

=item * %s

Le nombre de secondes depuis la date origine du système.

=item * %S

Les secondes (0-60 ; 60 peut se produire dans le cas des secondes
intercalaires. Cf. L<DateTime::LeapSecond>).

=item * %t

Un caractère d'espacement quelconque.

=item * %T

Équivalent à C<%H:%M:%S>.

=item * %U

Le numéro de semaine en adoptant dimanche comme premier jour de la
semaine (0-53). Le premier dimanche de janvier est le premier jour de
la semaine 1.

=item * %u

Le numéro du jour dans la semaine (1-7) avec lundi = 1. C'est le standard
de C<DateTime>.

=item * %w

Le numéro du jour dans la semaine (0-6) avec dimanche = 0.

=item * %W

Le numéro de semaine en adoptant lundi comme premier jour de la
semaine (0-53). Le premier lundi de janvier est le premier jour de
la semaine 1.

=item * %y

Les deux derniers chiffres de l'année (0-99). Si le siècle n'est pas
précisé ailleurs dans le schéma, les valeurs de l'intervalle
69-99 seront converties en 1969-1999 et les valeurs de l'intervalle
00-68 seront converties en 2000-2068.

=item * %Y

L'année sur quatre chiffres (par exemple, 1991).

=item * %z

Une spécification de décalage horaire conforme à la norme RFC-822/ISO
8601. (Par exemple +1100) [Cf. la note ci-dessous]

=item * %Z

Le nom du fuseau horaire. (Par exemple EST -- qui est ambigu) [Cf. la
note ci-dessous]

=back

=head1 NOTES

=over 4

=item * on_error

Le comportement par défaut de ce module est maintenant de renvoyer
C<undef> si une erreur est détectée.

=back

=head1 SUPPORT

Le support de ce module est assuré par la liste de diffusion
C<datetime@perl.org>. Cf. http://lists.perl.org/ pour les détails.

Merci de communiquer vos rapports de bugs au système RT de CPAN avec
le web ou par messagerie électronique à

	bug-datetime-format-strptime@rt.cpan.org

Cela me simplifiera la vie pour suivre les problèmes et cela
signifie que votre problème risquera moins de passer aux oubliettes.

=head1 LICENCE ET COPYRIGHT

Copyright E<169> Rick Measham, 2003. Tous droits réservés. Ce logiciel est
un logiciel S<libre ;> vous pouvez le redistribuer et le modifier aux
mêmes conditions que Perl lui-même.

Copyright (c) 2004 Jean Forget et les Mongueurs de Perl pour la
traduction française. Tous droits réservés.

Vous pouvez trouver le texte intégral de la licence en anglais
dans le fichier F<LICENSE> inclus dans la distribution de ce module.

=head1 AUTEUR

Rick Measham (adresse C<rickm> sur le site C<cpan> point C<org>)

=head1 TRADUCTION

La traduction concerne la version 1.05 de C<DateTime::Format::Strptime>

Traduit le 2004-08-10 par Jean Forget (adresse C<JFORGET> sur
le site C<cpan> point C<org>).

=head1 VOIR ÉGALEMENT

C<datetime@perl.org> mailing list.

http://datetime.perl.org/

L<perl>, L<DateTime>, L<DateTime::TimeZone>

http://datetime.mongueurs.net/

=cut