Les Mongueurs de Perl

NOM

Date::Convert - Conversion de dates d'un calendrier à un autre

RÉSUMÉ

        use Date::DateCalc;


        $date=new Date::Convert::Gregorian(1997, 11, 27);
        @date=$date->date;
        convert Date::Convert::Hebrew $date;
        print $date->date_string, "\n";

Les classes définies pour l'instant sont : 

        Date::Convert::Absolute
        Date::Convert::Gregorian
        Date::Convert::Hebrew
        Date::Convert::Julian

Date::Convert vous permet de convertir des dates entre deux calendriers arbitraires (pour l'instant, vous avez le choix entre : Grégorien, Julien, Hébreu, absolu, ainsi que d'autres qui aurait pu être ajoutés depuis). Pour ce faire, le module définit une sous-classe pour chaque calendrier, chaque classe devant définir un certain nombre de méthodes standardisées pour les conversions entre le format de base et le format de la sous-classe. De la sorte, il n'y a pas besoin de définir une routine de conversion pour chaque couple de calendrier, et la fonction enchaîne une conversion foo vers format de base, puis format de base vers bar. Exemple 

        Grégorien <--> Base <--> Hébreu

La classe de base comporte une méthode Convert pour effectuer cette opération de façon transparente.

Le module n'exporte aucun symbole, car aucun symbole ne le mérite. :-)

DESCRIPTION

Il est possible de classer les fonctions en plusieurs catégories :

Voici la liste des fonctions par catégorie :

Fonctions définies pour toutes les sous-classes

new

Crée une nouvelle instance de l'objet, spécifiée par le format, et avec des valeurs initiales (par exemple, $date = new Date::Convert::Gregorian(1974, 11, 27)). Les valeurs initiales dépendent de la sous-classe. Je préfère spécifier dans l'ordre d'importance décroissant (par exemple, l'année d'abord, puis le mois, et enfin le jour ; ou bien, l'année, puis la semaine, etc.).

Il est possible de prévoir une valeur par défaut, qui serait ``aujourd'hui''.

date

Extrait la date dans un format approprié à la sous-classe. Il est préférable que ce format coïncide avec le format utilisé pour new, de sorte que 

        (new date::Convert::Uncalendrier(@a))->date;

soit la fonction identité pour @a, en supposant que @a contienne des valeurs correctes.

date_string

Renvoie la date dans un format agréable.

convert

Convertit la date dans un nouveau format.

Fonctions spécifiques

year

Renvoie uniquement l'élément année de la date.

month

Idem, avec le mois.

day

Pareil, avec le jour.

is_leap

Booléen indiquant si la date figure dans une année bissextile. À noter que cette méthode peut également être appelée en tant que méthode statique. C'est-à-dire, vous pouvez coder $date->is_leap ou bien is_leap Date::Convert::Hebrew 5757

Fonctions privées requises pour toutes les sous-classes

Vous ne devriez pas les utiliser, mais si vous créez une nouvelle sous-classe, vous devez les définir ! Ou plutôt la définir, car pour l'instant il y en a une seule.

initialize

Reçoit des arguments, et initialise l'objet avec ces valeurs. S'il n'y a pas d'arguments, initialise l'objet avec la méthode d'initialisation de la classe de base (qui initialisera avec des valeurs par défaut, comme décrit pour new). À noter l'orthographe américaine de ``initialize'' : ``z'' au lieu de ``s''.

NOTES SPÉCIFIQUES AUX CLASSES DÉRIVÉES

Absolute (absolu)

Le calendrier ``absolu'' est simplement le nombre de jours écoulés par rapport à un point de référence. Ceux qui ont étudié les calendriers reconnaîtront le ``Jour Julien'' avec une adaptation mineure : le calendrier absolu compte les jours de minuit à minuit, le JJ les compte de midi à midi. Les deux notions coïncident l'après-midi.

Etant donné que le calendrier absolu n'a aucune notion d'année, il est très pratique pour les traitements de conversion. J'ai pompé le calendrier absolu sur le mode calendrier d'emacs, écrit par Reingold, et il m'est utile pour le débuggage.

La classe dérivée ne contient pas grand chose de plus que la classe de base. Elle n'a pas de fonction spécifique.

Gregorian (grégorien)

Le calendrier grégorien est un calendrier purement solaire, dans lequel le mois est une approximation grossière du mois lunaire. Il est basé sur le vieux calendrier julien (romain). Ce calendrier est utilisé par la quasi-totalité du monde occidental depuis quelques siècles. L'année d'adoption varie d'un pays à l'autre. La classe ::Gregorian permet d'extrapoler le calendrier jusqu'en 1 après J.C. même si le calendrier n'était pas en vigueur.

En plus des méthodes obligatoires, la classe Gregorian prévoit les méthodes year, month, day, et is_leap. Ainsi qu'il a été signalé ci-dessus, la méthode is_leap peut être utilisée comme une méthode statique.

Hebrew (hébreu)

C'est le calendrier judaïque traditionnel. Il se base sur l'année solaire, sur le mois lunaire, et sur un certain nombre de règles supplémentaires établies par les rabbins pour compliquer la tâche de ceux qui calculent les calendriers. :-) Si vous examinez le source, vous pourrez noter que le septième mois est placé juste avant le premier mois. Ce n'est pas un bug.

Les méthodes supplémentaires sont : year, month, day, is_leap, rosh, part_add, et part_mult. rosh renvoie le jour absolu correspondant à ``Rosh HaShana'' (nouvel an) pour une année donnée, et il est possible de l'utiliser comme une méthode statique. part_add et part_mult sont des fonctions utiles pour le calendrier hébraïque, et n'ont pas réellement d'autre utilité ; si vous n'êtes pas habitués au calendrier hébraïque, inutile de vous appesantir sur ces fonctions.

Islamic (Islamique)

Le calendrier musulman traditionnel, un calendrier purement lunaire, dont l'année est une approximation grossière de l'année solaire. Il n'est pas encore implémenté.

Julian (julien)

L'ancien calendrier romain, ainsi nommé à cause de Jules César. Purement solaire, avec un mois dont la durée est approximativement celle du mois solaire. C'était le calendrier de tout le monde occidental il y a encore quelques siècles, mais progressivement les différents pays occidentaux ont adopté le calendrier grégorien, plus précis. A l'heure actuelle, pour autant que je sache, seule l'Église Orthodoxe Orientale l'utilise encore.

COMMENT AJOUTER DE NOUVELLES CLASSES DÉRIVÉES

Cette section décrit comment étendre Date::Convert pour ajouter de nouveaux calendriers. Si cela ne vous intéresse pas, vous pouvez très bien sauter cette partie. :-)

Il suffit d'écrire trois fonctions pour ajouter une classe dérivée. Ces fonctions sont initialize, date, et date_string. Bien entendu, il peut être utile d'ajouter des fonctions utilitaires... Vous n'êtes pas obligés d'écrire une fonction new ou une fonction convert, celles de la classe de base conviennent fort bien.

Commençons par un survol du concept. La classe de base utilise un ``format de jour absolu'' (quasiment le format de jour julien) emprunté à emacs. Ce n'est rien d'autre que le nombre de jours écoulé depuis une date très loin dans le passé. C'est très facile à utiliser, surtout si vous avez emacs et son mode calendrier. Chaque objet de Date::Convert est la référence d'un hash (comme d'habitude en Perl OO), et comporte une valeur indexée par la clé réservée ``absol''. Lorsque initialize initialise un objet, par exemple une date grégorienne, la méthode stocke les données transmises en paramètres, calcule l'équivalent ``absol'' de la date, et stocke cette valeur dans le hash. Si l'utilisateur convertit la date dans un autre format, la méthode convert nettoie l'objet, supprimant tous les attributs sauf ``absol''. Ensuite, l'appel de la méthode date du nouveau format calcule les attributs nécessaires en fonction de la valeur de l'attribut ``absol''.

Et maintenant que je vous ai bien embrouillé l'esprit, voici une version un peu plus découpée.

initialize

La fonction reçoit une date en argument, dont la valeur doit être compatible avec le format. Puis elle convertit la date au format ``absol'', et la mémorise dans $$self{'absol'}. Vous pouvez également stocker d'autres données. Par exemple, ::Gregorian mémorise $$self{'year'}, $$self{'month'}, et $$self{'day'}. Si la fonction ne reçoit aucun argument, elle doit alors appeler explicitement la fonction initialize de la classe parente, c'est-à-dire Date::Convert::initialize, pour initialiser l'objet avec une date par défaut au format 'absol', et rien d'autre.

NB : Il est possible que, dans une prochaine version, ce comportement par défaut soit implémenté dans le constructeur new.

date

Renvoie la date dans un format approprié. La seule hypothèse que la fonction date puisse faire, c'est que $$self{'absol'} est alimenté. Cela signifie que l'objet peut fort bien ne pas avoir été initialisé par la méthode initialize de la classe de l'objet. Par exemple, vous pouvez être amené à vérifier que $$self{'year'} est bien défini. Dans l'affirmative, cela vous donne l'année de la date, sinon, cela vous oblige à recalculer l'année à partir de $$self{'absol'}.

date_string

Facile. Il suffit d'appeler date, puis de renvoyer une jolie chaîne de caractères incorporant les valeurs.

NB : La sous-classe ::Absolute est un cas particulier, puisqu'elle est quasiment vide (en fait, c'est une classe vide, à laquelle j'ai ajouté les méthodes obligatoires). N'utilisez pas cette classe comme exemple ! La plus simple aurait été ::Julian, sauf que cette sous-classe dérive de ::Gregorian. Je vais peut-être changer cela dans une prochaine version...

EXEMPLES

        #!/usr/local/bin/perl5 -w


        use Date::Convert;


        $date=new Date::Convert::Gregorian(1974, 11, 27);
        convert Date::Convert::Hebrew $date;
        print $date->date_string, "\n";

Ma date de naissance est le 27 novembre 1974 dans le calendrier grégorien. Les lignes de code ci-dessus impriment ma naissance en Hébreu. 

        convert Date::Convert::Gregorian $date;
        print $date->date_string, "\n";

Et ces lignes font la conversion inverse, pour imprimer la date en grégorien. 

        $guy = new Date::Convert::Hebrew (5756, 7, 8);
        print $guy->date_string, " -> ";
        convert Date::Convert::Gregorian $guy;
        print $guy->date_string, "\n";

Une autre date, introduite en Hébreu, et imprimée en grégorien. 

        @a=(5730, 3, 2);
        @b=(new Date::Convert::Hebrew @a)->date;
        print "@a\n@b\n";

Le code ci-dessus devrait être la fonction identité, à condition que les valeurs de la liste @a représentent une date valide dans le calendrier hébreu. 

        #!/usr/local/bin/perl -an


        use Date::Convert;


        $date = new Date::Convert::Gregorian @F;
        convert Date::Convert::Hebrew $date;
        print $date->date_string, "\n";

Et finalement un bref programme de conversion grégorien -> Hébreu.

VOIR ÉGALEMENT

perl(1), Date::DateCalc(3)

VERSION

Date::Convert 0.16 (pre-alpha)

AUTEUR

Mordechai T. Abzug <morty@umbc.edu>

TRADUCTEUR

Jean FORGET <J-FORGET@wanadoo.fr>

REMERCIEMENTS ET SOURCES DOCUMENTAIRES

L'idée de base, utiliser les dates astronomiques comme intermédiaire entre tous les calculs, est due à Dershowitz et Reingold. Le code de Reingold sert de base au mode calendar de Emacs. Les deux articles décrivant leur travail (que j'avais, mais que j'ai égarés !) sont :

``Calendrical Calculations'' par Nachum Dershowitz et Edward M. Reingold, Software--Practice and Experience, Volume 20, Numéro 9 (septembre 1990), pages 899-928. ``Calendrical Calculations, Part II: Three Historical Calendars'' par E. M. Reingold, N. Dershowitz, et S. M. Clamen, Software--Practice and Experience, Volume 23, Numéro 4 (avril 1993), pages 383-404.

Ils avaient également prévu d'écrire un livre sur les calculs de calendrier, livre qui devait sortir en décembre 1996, mais nous somme en mars 1997 et le livre n'est toujours pas paru.

Les calculs associés au calendrier hébreu sont en grande partie basés sur un chouette petit livre en Anglais, intitulé The Hebrew Calendar (si je me souviens bien), et qui se trouve dans une boîte quelque part dans la maison de mes parents (voyez comme je suis organisé !). Il va falloir que je fasse des fouilles la prochaine fois que j'y retournerai. Si vous voulez consulter les sources originelles en Hébreu, voici quelques conseils. Il y a Hilchos Kiddush HaChodesh dans la Mishneh Torah, mais ce n'est pas le texte le plus clair sur le sujet. Il y a une petite brochure appelée ``MaAmar HaEibur'', qui est à la fois plus complète et plus facile à comprendre. Elle est incluse dans ``Mich't'vei HaRambam'' (ou quelque chose d'approchant), réimprimé il y a quelques années.

Steffen Beyer et son module Date::DateCalc m'ont montré comment utiliser MakeMaker et comment écrire de la documentation POD. Néanmoins, s'il y a des erreurs, je les assume, ne vous en prenez pas à lui !

COPYRIGHT

Copyright 1997 par Mordechai T. Abzug pour la version originale,

Copyright 2001 par Jean Forget pour la traduction française.

BARATIN LÉGAL

Vous pouvez distribuer, modifier et triturer Date::Convert sous les mêmes conditions que Perl.

© Les Mongueurs de Perl, 2001-2024 Contact - HTML 5 - CSS v3 - 19 septembre 2020