=head1 NOM DateTime::Calendar::Hebrew - Dates dans le calendrier hébraïque =head1 RÉSUMÉ use DateTime::Calendar::Hebrew; $dt = DateTime::Calendar::Hebrew->new( year => 5782, month => 10, day => 4 ); =head1 DESCRIPTION C implémente le calendrier hébraïque. Voir ci-dessous pour les détails. =head1 LE CALENDRIER HÉBRAÏQUE (OU JUIF) Le calendrier héraïque / juif est un calendrier luni-solaire. La loi de la Torah exige que les mois soient lunaires. Le premier jour du mois coïncide avec la nouvelle Lune à Jérusalem. (Dans l'antiquité, l'observation était effectuée par des témoins. Cf. les livres de la bibliographie pour plus de détails). La Torah exige également que certaines fêtes se produisent lors d'une saison donnée. Les saisons sont déterminées par le soleil, il faut donc un calendrier qui puisse fonctionner avec des événements solaires et des événements lunaires. Le calendrier hébraïque utilise un mois intercalaire pour se synchroniser avec les saisons solaires. Une année normale comporte 12 mois. Chaque mois dure 29 ou 30 jours. Deux mois (Cheshvan & Kislev) oscillent entre 29 et 30 jours selon l'année. Lors d'une année dite S<« embolismique »>, un treizième mois est ajouté. Une remarque rapide sur la numérotation des mois. La plupart des gens pensent que l'année commence avec le mois numéro 1. En fait, le calendrier hébraïque a plusieurs jours de l'an. Le numéro de l'année change en automne (vu de l'hémisphère nord) lorsque commence le mois de Tishrei (numéro 7), mais les mois sont numérotés à partir du mois de Nissan (numéro 1) au printemps. Tishrei est le mois au cours duquel ont lieu les principales fêtes, I et I. Nissan, le début de l'année du printemps, commémore la sortie d'Egypte et l'Exode du peuple d'Israël. La Torah évoque uniquement les mois par leur numéro, en commençant par Nissan. Par exemple, elle indique que la date de I est S<« au> septième S. Ce système fonctionne bien pour nous, à cause du mois intercalaire. Avec le début de l'année au printemps, le mois intercalaire reçoit le numéro 13. Sinon, il aurait fallu renuméroter les mois qui suivent le mois intercalaire. Avec ce module, chaque mois a un numéro fixé. En voici la S =over 4 =item 1. Nissan =item 2. Iyar =item 3. Sivan =item 4. Tammuz =item 5. Av ou Menachem-Av =item 6. Elul =item 7. Tishrei =item 8. Cheshvan ou Mar-Cheshvan =item 9. Kislev =item 10. Teves =item 11. Shevat =item 12. AdarI =item 13. AdarII (seulement lors des années embolismiques) =back I<** UNE NOTE SUR L'ORTHOGRAPHE **> Si vous connaissez l'hébreu, vous serez peut-être en désaccord avec ma manière d'orthographier les mots hébreus. Désolé, j'utilise l'orthographe qui se rapproche le plus de la façon dont je les prononce. Appelez cela la S<« prononciation> ashknénaze de S< Brooklyn »> si cela vous chante. Revenons au calendrier. Le calendrier hébraïque comporte un cycle de 19 ans appelé I. Dans ce cycle, les années 3, 6, 8, 11, 14, 17 et 19 sont embolismiques. Les jours (et les fêtes) commencent au coucher du soleil, voir ci-dessous pour les détails. Les calculs pour le début et la longueur de l'année sont basés sur un certain nombre de facteurs, notamment le fait que certaines fêtes sont incompatibles avec certains jours de la semaine et autres critères de ce genre. Pour plus de détail sur le calendrier hébraïque et les algorithmes associés, prenez un livre dans la bibliographie ci-dessous. Je n'ai pas l'intention de les paraphraser dans la présente documentation. Bien sûr, une recherche dans Google sur les mots-clés S<« Jewish calendar »> ou S<« calendrier hébraïque »> vous conduira vers une abondance de pages web sur le sujet. =head1 SOURCES Voici quelques livres essentiels pour comprendre le calendrier hébraïque (ou juif). Soyez conscients qu'une connaissance de base des termes hébreux facilitera beaucoup la lecture. B Ce livre est super. En plus d'un calendrier hébraïque complet de 1900 à 2100, il comporte un exposé de 22 pages sur le calendrier hébraïque, histoire, méthodes de calcul, fêtes religieuses, la totale. B Un autre livre excellent. Explique le calendrier, les cycles de lunaison, etc. Plus axé sur l'astronomie que tous les autres. B Ce livre est axé sur les mathématiques des conversions de calendriers. J'utilise la première édition, remplie d'exemples en LISP. La seconde édition doit inclure des exemples dans d'autres langages. Le livre présente de nombreux calendriers différents, pas seulement le calendrier hébraïque. Voir leur page web en L Il existe d'autres livres, mais ce sont ceux que j'utilise le plus pour mon codage Perl. Le traducteur y ajoute deux livres en français. I, par Jean Lefort, collection I, ISBN 2-9029-003-5. I, par Paul Courderc, collection I>. =head1 MÉTHODES =over 4 =item * new(...) $dt = new Date::Calendar::Hebrew( year => 5782, month => 10, day => 5, ); Cette méthode de classe attend un paramètre pour chaque composant de date et d'S C pour l'année, C pour le mois, C pour le jour, C pour les heures, C pour les minutes, C pour les secondes et C pour les nanosecondes. Le paramètre C est obligatoire, les autres sont optionnels. La valeur par défaut de C et de C est 1, celle pour les éléments de l'heure est 0. Le constructeur vérifie la validité de tous les paramètres sauf l'année. month : 1 à 13 day : 1 à 30 hour : 0 à 23 minute/second : 0 à 59 nanosecond : 0 à 999_999_999 C ne tient pas compte des fuseaux horaires. Le module utilise le fuseau flottant. Les jours du calendrier hébraïque commencent au coucher du soleil. Si vous voulez connaître la date hébraïque exacte en fonction du coucher du soleil local, cf. la section COUCHER DU SOLEIL ci-dessous. =item * from_object(object => $object) Cette méthode de classe sert à construire un nouvel objet à partir d'un objet implémentant la méthode C. Tous les modules C doivent implémenter cette méthode pour permettre les conversions d'un calendrier à l'autre. =item * set(...) $dt->set( year => 5782, month => 1, day => 1, ); Cette méthode permet de modifier les valeurs de l'objet. Les champs valides sont C pour l'année, C pour le mois, C pour le jour, C pour les heures, C pour les minutes, C pour les secondes et C pour les nanosecondes. La méthode renvoie l'objet après modification. La valeur des paramètres est contrôlée de la même manière que par la méthode C. =item * utc_rd_values Renvoie une liste composée du jour I et des secondes I et des nanosecondes I. Cette méthode a essentiellement pour but de permettre à d'autres calendriers de créer une date à partir d'une date hébraïque. Le module ne supporte pas les fuseaux horaires, donc il s'agit des valeurs locales I. =item * utc_rd_as_seconds Renvoie la combinaison des jours UTC I et des secondes UTC I sous la forme d'un nombre de secondes. Pratique si vous devez représenter une date par un seul nombre. Le module ne supporte pas les fuseaux horaires, donc il s'agit des valeurs locales I. =item * clone Cette méthode d'instance crée un nouvel objet, réplique de l'objet de départ. =item * now Cette méthode de classe renvoie un objet C créé à partir de Cnow()>. =item * today Cette méthode de classe renvoie un objet C créé à partir de Ctoday()>. =item * year Renvoie l'année. =item * month Renvoie le mois de l'année, dans l'intervalle 1..13. =item * day_of_month, day, mday Renvoie le jour du mois, dans l'intervalle 1..30. =item * day_of_month_0, day_0, mday_0 Renvoie le jour du mois, dans l'intervalle 0..29. =item * hour Renvoie l'heure. =item * minute Renvoie les minutes. =item * second Renvoie les secondes. =item * month_name($month); Renvoie le nom du mois demandé. Si vous appelez cette méthode sur un objet (C<$dt-Emonth_name>), elle renvoie le nom du mois de l'objet. Les noms de mois hébreux sont Nissan, Iyar, Sivan, Tammuz, (Menachem)Av, Elul, Tishrei, (Mar)Cheshvan, Kislev, Teves, Shevat et Adar. Les années embolismiques comportent un mois "Adar II" ou Second-Adar. Si vous pensez que l'ordre des mois est mauvais, cf. la remarque au début de cette documentation. =item * day_of_week, wday, dow Renvoie le jour du mois sous la forme d'un nombre dans l'intervalle 1..7, 1 représentant le dimanche et 7 le samedi. =item * day_of_week_0, wday_0, dow_0 Renvoie le jour du mois sous la forme d'un nombre dans l'intervalle 0..6, 0 représentant le dimanche et 6 le samedi. =item * day_name Renvoie le nom du jour de la semaine. =item * day_of_year, doy Renvoie le jour de l'année. =item * day_of_year_0, doy_0 Renvoie le jour de l'année, la numérotation commençant à 0. =item * ymd($separateur_facultatif); =item * mdy($separateur_facultatif); =item * dmy($separateur_facultatif); Ces trois méthodes renvoient une chaîne comportant l'année (S<« y »>), le mois (S<« m »>) et le jour (S<« d »>) sous forme numérique et dans l'ordre indiqué par le nom de la méthode. Les années sont sur quatre chiffres, complétées par des zéros à gauche si nécessaire. De même, les mois et les jours sont cadrés sur deux chiffres, avec un zéro à gauche si nécessaire. Par défaut, les éléments sont séparés par un tiret, mais vous pouvez adopter un autre séparateur en le transmettant comme paramètre. =item * hms($separateur_facultatif); Renvoie l'heure, au format I. Par défaut, les éléments sont séparés par un caractère deux-points, mais vous pouvez adopter un autre séparateur en le transmettant comme paramètre. =item * hm($separateur_facultatif); Renvoie l'heure, au format I. Par défaut, les éléments sont séparés par un caractère deux-points, mais vous pouvez adopter un autre séparateur en le transmettant comme paramètre. =item * timezone Renvoie 'floating' pour indiquer le seul fuseau horaire possible, le fuseau flottant. =item * datetime Renvoie la date et l'heure au format IHH:MM:SS> =item * strftime($format, ...) Cette méthode fournit une fonctionnalité similaire à celle de C en C. Toutefois, si elle reçoit plusieurs chaînes de format, alors elle renvoie une liste d'éléments, un pour chaque format envoyé. Cf. L pour la liste de toutes les spécifications possibles dans un format. J'en ai implémenté autant que possible pour ce calendrier. =back =head2 FONCTIONS INTERNES =over 4 =item * _from_rd($RD); Calcule l'année hébraïque, le mois et le jour à partir des données I. =item * _to_rd($year, $month, $day); Calcule les données I à partir de l'année hébraïque, du mois et du jour. =item * _leap_year($year); Renvoie une valeur vraie si l'année est une année embolismique du calendrier hébraïque. =item * _LastMonthOfYear($year); Renvoie le numéro du dernier mois pour l'année en paramètre. Les années embolismiques ont 13 mois, les années normales en ont 12. =item * _CalendarElapsedDays($year); Renvoie le nombre de jours écoulés entre la date origine du calendrier hébraïque et le premier jour de l'année demandée. =item * _DaysInYear($year); Renvoie le nombre de jours dans l'année demandée. =item * _LongCheshvan($year); Renvoie une valeur vraie si le mois de Chesvan de l'année demandée est abondant. Un mois Chesvan normal a 29 jours, un mois Chesvan abondant a 30 jours. =item * _ShortKislev($year); Renvoie une valeur vraie si le mois de Kislev de l'année demandée est déficient. Un mois Kislev normal a 30 jours, un mois Kislev déficient a 29 jours. =item * _LastDayOfMonth($year, $month); Renvoie la longueur du mois demandé pour l'année demandée. =back =head2 SURCHARGE D'OPÉRATEUR ET RÈGLES DE CALCUL Il est possible de comparer des objets C avec les opérateurs C>, C>, C=E> et C. Vous pouvez également utiliser $dt->compare($autre_dt). Les opérations simples sont possibles sur des objets C, à l'aide d'objets C. Les champs supportés sont C pour les jours, C pour les heures, C pour les minutes, C pour les secondes et C pour les nanosecondes. Vous pouvez également utiliser la syntaxe $DT->add_duration($DUREE) et $DT->subtract_duration($DUREE) =over 4 =item * _compare_overload =item * _compare =item * _add_overload =item * _subtract_overload =item * add_duration =item * subtract_duration =item * _normalize =back =head1 LE COUCHER DU SOLEIL ET LES DATES HÉBRAÏQUES Dans le calendrier hébraïque, les jours commencent au coucher du soleil. Cela n'a d'intérêt que pour des questions religieuses et pour les programmeurs pointilleux. Cela pose de sérieux problèmes religieux dans les régions où le lever et le coucher du soleil ne sont pas clairement définis. Au-delà du Cercle Polaire, il y a des jours d'été où le soleil ne se couche pas et des jours d'hiver où il ne se lève pas. Dans d'autres régions (par exemple, Anchorage en Alaska, Stockholm en Suède, Oslo en Norvège), les jours sont très courts et les crépuscules durent très longtemps. (Je n'ai jamais expérimenté de telles situations, je le recopie d'une page web.) Tout d'abord, laissez moi dire que si vous êtes Juif et que vous avez des questions à propos du lever et du coucher du soleil et des prescriptions religieuses, posez-les à votre rabbin local. Je ne suis pas un expert. Si vous n'êtes pas Juif et que vous voulez avoir des informations sur les dates hébraïques dans ces régions (ou bien, si vous êtes Juif mais que vous n'habitez pas dans ces régions), contactez quelqu'un de Juif qui habite ces contrées et une fois que vous êtes amis, demandez-lui de poser la question à son rabbin local. Maintenant que mon avertissement laborieux est terminé, revenons aux questions de code. Si vous voulez qu'une date hébraïque tienne compte du coucher du soleil, vous devez fournir deux S un objet C, initialisé à la longitude et à la latitude de l'endroit qui vous intéresse, ET un fuseau horaire pour cet endroit. Sans fuseau horaire, je ne peux pas déterminer correctement le coucher du soleil. Ces attributs peuvent être initialisés à l'appel du constructeur ou positionnés par la méthode C. Vous pouvez configurer l'objet C pour l'altitude et l'interpolation si vous le souhaitez. =head2 NOTES À PROPOS DU COUCHER DU SOLEIL Cette fonctionnalité a été testée uniquement pour les régions pour lesquelles le jour demandé comporte un coucher du soleil. LES VALEURS I NE SONT PAS MODIFIÉES. Les champs internes pour le jour, le mois et l'années sont modifiés. Le changement de la date n'est visible qu'au travers des accesseurs de l'objet. C change uniquement à minuit. C ne supporte pas les fuseaux S Il continue d'utiliser le fuseau flottant. La méthode C<$obj-Eset_time_zone(...)> n'est pas implémentée et ne sera d'aucune utilité pour le calcul du coucher du soleil. Il faut définir un champ. Comme il m'a été signalé, il existe un bug ou une fonctionnalité qui crée une certaine confusion dans les conversions. J'ai agencé les calculs de sorte que la conversion de C vers C sera toujours correcte. Si vous donnez une date grégorienne avec une heure postérieure au coucher du soleil mais avant minuit, vous obtiendrez une heure hébraïque correspondant au jour suivant. La valeur RD n'est pas modifiée, mais la date hébraïque change. À l'inverse, si vous voulez une date-heure dans la nuit pour une certaine date hébraïque, vous devez utiliser la date du jour précédent. Le coucher du soleil S<« appartient »> à la date grégorienne. Par exemple, si vous dites S<« Nissan> 14 5764, après le coucher du S (le moment de la recherche du levain pour Pessa'h), le code convertit cette date en l'équivalent RD du lundi 5 avril 2004. Or, après le coucher du soleil du 5 avril, nous sommes le 15 S Pour obtenir la date-heure correspondant à la recherche du levain, il faut donc créer un objet correspondant au 13 Nissan, après le coucher du soleil, ce qui donnera à l'impression S<« Nissan> 14 5764, après le coucher du S. =head2 CODE D'EXEMPLE Voir C, inclus dans la distribution. =head1 SUPPORT Le support de ce module est assuré par la liste de diffusion C. Cf. http://lists.perl.org/ pour les détails. Si vous ne pensez pas maîtriser la langue anglaise suffisamment, faites-vous aider par l'un de vos proches ou éventuellement par le traducteur. =head1 CREDITS - Merci à mon ami Richie Sevrinsky qui m'a aidé à comprendre comment le pourquoi du comment des calculs. - Merci à tous les développeurs du projet DateTime et aux auteurs des autres modules de calendrier, qui m'ont permis de pomper... euh, de m'inspirer de leur code. - Merci à Arthur Spier, Rabbi Bushwick et MM. Dershowitz et Reingold pour avoir écrit d'excellents livres sur le sujet. =head1 AUTEUR Steven J. Weinberger (C arobase C point C) =head1 TRADUCTION Cette traduction concerne la version 0.xx de C. La traduction a été réalisée par Jean Forget (C arobase C point C) le 2004-07-28. =head1 COPYRIGHT Copyright (c) 2003 Steven J. Weinberger pour la version originale. Tous droits réservés. Ce logiciel est un logiciel S 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. =head1 VOIR ÉGALEMENT La liste de distribution C L L L http://datetime.perl.org/ http://datetime.mongueurs.net/ =cut