=head1 NOM DateTime::Fiction::JRRTolkien::Shire.pm =head1 RÉSUMÉ use DateTime::Fiction::JRRTolkien::Shire; # Constructeurs my $shire = DateTime::Fiction::JRRTolkien::Shire->new(year => 1419, month => 'Rethe', day => 25); my $shire = DateTime::Fiction::JRRTolkien::Shire->new(year => 1419, month => 3, day => 25); my $shire = DateTime::Fiction::JRRTolkien::Shire->new(year => 1419, holiday => '2 Lithe'); my $shire = DateTime::Fiction::JRRTolkien::Shire->from_epoch(epoch = $time); my $shire = DateTime::Fiction::JRRTolkien::Shire->today; # identique à from_epoch(epoch = time()); my $shire = DateTime::Fiction::JRRTolkien::Shire->from_object(object => $some_other_DateTime_object); my $shire = DateTime::Fiction::JRRTolkien::Shire->from_day_of_year(year => 1420, day_of_year => 182); my $shire2 = $shire->clone; # Accesseurs $year = $shire->year; $month = $shire->month; # 1 - 12, ou 0 pour une fête $month_name = $shire->month_name; $day = $shire->day; # 1 - 30, ou 0 pour une fête $dow = $shire->day_of_week; # 1 - 7, ou 0 pour certaines fêtes $day_name = $shire->day_name; $holiday = $shire->holiday; $holiday_name = $shire->holiday_name; $leap = $shire->is_leap_year; $time = $shire->epoch; @rd = $shire->utc_rd_values; # Méthodes Set $shire->set(year => 7463, month => 5, day => 3); $shire->set(year => 7463, holiday => 6); $shire->truncate(to => 'month'); # Comparaisons $shire < $shire2; $shire == $shire2; # Chaînes print "$shire1\n"; # Affiche Sunday 25 Rethe 1419 # A cette date dans l'histoire de la Terre du Milieu print $shire->on_date; =head1 DESCRIPTION Ce module est l'implémentation du calendrier utilisé par les hobbits dans le roman exceptionnel de J.R.R. Tolkien, I. Cette implémentation se base sur l'annexe D du roman, sauf mention du contraire. Le calendrier se compose de 12 mois de 30 jours et de 5 fêtes qui ne font partie d'aucun mois. Une sixième fête, I, s'ajoute à l'occasion des années bissextiles. I, le jour de la moitié de l'année (ainsi que I pour les années bissextiles) n'appartient à aucune semaine, ce qui fait qu'une année commence toujours un I. Ce module fait suite à C et en constitue une réécriture, de façon à être compatible avec les modules C de Dave Rolsky et compagnie. Il est nécessaire d'installer le module C pour que le présent module fonctionne. À l'inverse de C, qui traite les heures, le présent module ne possède aucun mécanisme pour donner l'heure de la Comté (principalement parce que je n'ai jamais réfléchi sur ce que cela pourrait donner). Toutefois, la notion d'heure est conservée, de sorte qu'une objet converti dans le calendrier de la Comté puis dans un autre calendrier conservera les éléments de l'heure intouchés. Il en va de même pour les fuseaux horaires. =head1 MÉTHODES La plupart de ces méthodes imitent la fonctionnalité des méthodes correspondantes de C. Pour plus de renseignements sur ces méthodes, voir la documentation de C. =over 4 =head2 Constructeurs =item * new( ... ) Cette méthode reçoit les paramètres pour l'année (C), le mois (C) et le jour (C), ou bien simplement pour l'année (C) et la fête (C). Le mois peut être spécifié par son nom, en donnant la valeur renvoyée par la méthode C ou bien par son numéro de 1 à 12. Le jour est donné par un numéro de 1 à 30. Si vous indiquez une fête, elle doit être spécifiée par son nom, ainsi qu'il est fourni par la méthode C, avec notamment une majuscule à chaque mot, ou bien par un numéro de 1 à 6, avec la correspondance S 1 => 2 Yule 2 => 1 Lithe 3 => Midyear's Day 4 => Overlithe # Année bissextiles uniquement 5 => 2 Lithe 6 => 1 Yule La méthode C accepte également des paramètres C, C, C, C, C et C. S'ils sont renseignés, il seront stockés en attendant de convertir l'objet vers une autre classe qui tiendra compte de ces paramètres. Si le jour n'est pas donné en paramètre, la valeur par défaut est 1. Si ni le mois ni le jours ne sont fournis, la date sera prise par défaut au 2 Yule, le premier jour de l'année. =item * from_epoch( epoch => $epoch, ... ) Identique à DateTime. =item * now( ... ) Identique à DateTime. Notez que cela revient à coder from_epoch( epoch => time() ); =item * today( ... ) Identique à DateTime. =item * from_object( object => $object, ... ) Identique à DateTime. Reçoit un objet d'un calendrier C et le convertit en un objet C. =item * last_day_of_month( ... ) Identique à DateTime. Semblable au constructeur C, mais sans paramètre C pour le jour. À la place, le jour est systématiquement fixé au 30 du mois, qui est le dernier jour de n'importe quel mois dans le calendrier de la Comté. Il n'est pas possible de créer un jour correspondant à une fête. Utilisez C à la place. =item * from_day_of_year( year => $year, day_of_year => $yday) Identique à DateTime. Crée une date en fonction de l'année et du numéro du jour dans l'année (C), les deux paramètres étant obligatoires. Il est possible de fournir des paramètres pour les heures, minutes, etc. qui seront stockés puis transmis à d'autres classes C, exactement comme avec C. =item * clone Crée un nouvel objet dans le calendrier de la Comté pour la même date (et le même temps implicite) que l'objet de départ. =head2 Méthodes de consultation =item * year Renvoie l'année. =item * month Renvoie le numéro du mois, de 1 à 12. Si la date est une fête, la méthode renvoie un numéro de mois à 0. =item * month_name Renvoie le nom du mois. Si la date est une fête, la méthode renvoie une chaîne vide. =item * day_of_month, day, mday Renvoie le numéro du jour, de 1 à 30. Si la date est une fête, la méthode renvoie un numéro de jour à 0. =item * day_of_week, wday, dow Renvoie le numéro du jour dans la semaine, de 1 à 7. Si le jour ne fait partie d'aucune semaine (I ou I), la méthode renvoie 0. =item * day_name Renvoie le nom du jour de la semaine, ou une chaîne vide si le jour n'appartient à aucune semaine. =item * day_name_trad Comme C, mais en utilisant les noms plus traditionnels ainsi qu'ils sont définis dans l'appendice D. =item * day_of year, doy Renvoie le numéro du jour dans l'année, de 1 à 366. =item * holiday Renvoie le numéro de la fête (voir la correspondance dans C). Si le jour n'est pas une fête, la méthode renvoie 0. =item * holiday_name Renvoie le nom de la fête. Si le jour n'est pas une fête, la méthode renvoie une chaîne vide. =item * is_leap_year Renvoie 1 pour une année bissextile, 0 pour une année régulière. Les années bissextiles suivent les mêmes règles que le calendrier grégorien. Il y a une année bissextile tous les quatre ans, sauf pour les années en "00" qui ne sont pas bissextiles. Toutefois, tous les quatre siècles (400 ans), l'année en "00" est bissextile. Il y a donc une légère différence par rapport au calendrier décrit dans l'annexe D, donnant la règle S<« une> fois tous les quatre ans, sauf une fois tous les cent S. Comme il existe une incertitude sur le nombre d'années écoulées depuis l'époque du Seigneur des Anneaux (cf. la note ci-dessous) et comme les gens s'attendent à se retrouver en terrain connu, j'ai adapté la règle pour ce module. Toutefois, il faut bien conserver à l'esprit que ce module n'obéit pas strictement à la description de l'annexe D. =item * week Un tableau à deux éléments, le premier étant la valeur de C et le deuxième étant C. =item * week_year Cette méthode renvoie toujours la même valeur que C pour le calendrier de la Comté, mais elle est présente pour assurer la compatibilité avec les autres classes C. =item * week_number Renvoie le numéro de la semaine dans l'année. =item * epoch Renvoie la valeur I de l'objet, exactement comme C. =item * hires_epoch Renvoie la valeur I de l'objet sous la forme d'un nombre flottant, la partie décimale correspondant aux fractions de secondes. Fonctionnement identique à C. =item * utc_rd_values Renvoie les valeurs UTC I pour les jours, les secondes et les nanosecondes. Ignore la partie décimale des secondes. C'est la méthode standard pour convertir une date dans le calendrier de la Comté vers un autre calendrier. Cf. la documentation de C pour plus de détails. =item * utc_rd_as_seconds Renvoie les valeurs UTC I pour le jour et les secondes combinées en un nombre de secondes. =item * on_date Affiche le jour courant. Si des événements se sont produits dans l'histoire de la Terre du Milieu à cette date (ainsi que c'est défini dans l'annexe B du I), ces événements sont affichés également. Cela fait bien dans un F<.bashrc> ou un F<.cshrc>. S perl -MDateTime::Fiction::JRRTolkien::Shire -le 'print DateTime::Fiction::JRRTolkien::Shire->now->on_date;' =head2 Méthodes de modification =item * Set( ... ) Permet de modifier le jour, le mois ou l'année. Les paramètres utilisés sont les mêmes que pour le constructeur C, y compris le paramètre C pour les fêtes et les paramètres qui ne sont utilisés que par C. Seule exception, le paramètre C ne peut pas être utilisé par C. Le résultat est le même que pour C, mis à part le fait que les paramètres qui ne sont pas renseignés conservent leur valeur précédente au lieu d'être initialisés à 0 ou 1. Tous les paramètres sont optionnels, sachant que l'on reprend l'ancienne valeur d'un paramètre qui n'est pas fourni. Toutefois, étant donné qu'une fête n'appartient pas à un mois, il est recommandé de fournir simultanément un jour et un mois. Sinon, la méthode peut donner des résultats inattendus. Comme pour le constructeur C, les paramètres de temps n'ont pas d'effet sur l'objet renvoyé pour la date de la Comté. Ils sont néanmoins pris en compte pour le cas où l'objet serait converti vers un calendrier qui tient compte de l'heure. =item * Truncate( ... ) Identique à DateTime. Si la date est une fête, la troncation au mois (C) ou au jour (C) a le même effet. Dans les autres cas, la méthode fonctionne comme pour un objet C. =item * set_time_zone( $tz ) Identique à DateTime. Cette méthode n'a pas d'effet visible sur une date de la Comté, mais le nouveau fuseau horaire est stocké dans l'objet et sera utilisé si l'objet est converti vers un calendrier qui tient compte des fuseaux horaires. =head2 Comparaisons et conversions en chaîne Tous les opérateurs de comparaison doivent fonctionner comme dans C. De plus, tous les objets C apparaîtront comme une date lisible s'ils sont interpolés dans une chaîne entre doubles quotes. =back =head1 DURÉES ET CALCULS DE DATE Les durées et les calculs sur les dates (autres que les comparaisons) ne sont pas supportés dans la version actuelle du module (mais j'accepte volontiers les patchs). Si le besoin s'en fait sentir, il existe quelques moyens de s'en sortir. Si vous travaillez dans le domaine de validité des valeurs I, vous pouvez convertir la date en I, faire les calculs et convertir en sens inverse. Également, quelle que soit la date, vous pouvez convertir en un objet C, faire les calculs avec cette classe et convertir en sens inverse en une date de la Comté. =head1 S CALCUL DE L'ANNÉE http://www.glyhweb.com/arda/f/fourthage.html fait référence à une lettre envoyée par Tolkien en 1958 dans laquelle il estimait qu'environ 6000 ans s'étaient écoulés depuis la Guerre de l'Anneau et la fin du Troisième Âge. (Merci à Danny O'Brien de m'avoir transmis ce lien). J'ai adopté cette valeur approximative comme étant la valeur exacte de l'écart entre la fin du Troisième Âge et la lettre de Tolkien et j'ai retranché 6000 ans de la date en 1958. Le résultat obtenu a été pris comme étant la date de début du Quatrième Âge (1422 dans le calendrier de la Comté). Donc, le Quatrième Âge a commencé en 4042 av. J.-C. selon notre manière de compter. Selon l'annexe D du I, les années bissextiles dans le calendrier hobbit ont lieu tous les 4 ans, sauf au changement de siècle, à l'occasion duquel il n'y a pas d'année bissextile. Notre calendrier (grégorien) utilise la règle S<« tous> les 4 ans, sauf tous les 100 ans, sauf tous les 400 S. Donc, s'il n'y a pas eu de réforme du calendrier depuis la fin du Troisième Âge, leur calendrier aurait accumulé un retard de 15 jours par rapport au nôtre depuis l'époque de la Guerre de l'Anneau. Implémenter une telle règle me semble en désaccord avec l'habitude de Tolkien de convertir les dates du roman en dates équivalentes pour notre calendrier, de manière à nous donner une meilleure compréhension du temps. Mon avis, au moins en ce moment, est qu'il est plus dans l'esprit du romans de faire correspondre les années, de sorte que le S<« jour> de la moitié de S (I) correspond à peu près au solstice d'été. J'ai donc modifié en conséquence la description du calendrier hobbit de sorte que les années bissextiles se produisent S<« tous> les 4 ans, sauf tous les 100 ans, sauf tous les 400 S, pour correspondre au calendrier grégorien. Les intervalles de 100 ans et de 400 ans du calendrier hobbit présentent un décalage par rapport à ceux du calendrier grégorien, ce qui fait que la correspondance entre les jours du calendrier hobbit et ceux du calendrier grégorien dépend de l'année, ce n'est pas dans l'absolu une correspondance un pour un. Toutefois, la correspondance suit un cycle de 400 ans. =head1 AUTEUR Tom Braun (adresse C sur le site C point C) =head1 TRADUCTION La traduction concerne la version 0.xx de C Traduit le 2004-07-20 par Jean Forget (adresse sur le site C point C). =head1 LICENSE ET COPYRIGHT Copyright (c) 2003 Tom Braun. 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. Le calendrier implémenté dans ce module a été créé par J.R.R. Tolkien et ses héritiers bénéficient du copyright sur ses oeuvres. La licence et le copyright donnés ci-dessus s'appliquent uniquement au code, pas au calendrier lui-même. Vous pouvez trouver le texte intégral de la licence en anglais dans le fichier F inclus dans la distribution de ce module. =head1 SUPPORT Vous pouvez obtenir un support à l'utilisation du module en m'envoyant un message électronique en anglais. Sachez toutefois que je ne suis le développeur d'aucun autre module du projet C. Pour le support sur ces autres modules, voir les options de support dans la documentation associée. Si vous ne pensez pas maîtriser suffisamment la langue anglaise, faites-vous aider par l'un de vos proches ou éventuellement par le traducteur. =head1 BIBLIOGRAPHIE Tolkien, J. R. R. I. New York: Houghton Mifflin Press, 1955. Traduit en français sous le titre I. http://www.glyphweb.com/arda/f/fourthage.html =head1 VOIR ÉGALEMENT La documentation du projet DateTime (perldoc DateTime, liste datetime@perl.org, et http://datetime.perl.org/). http://datetime.mongueurs.net/ =cut 1;