Date Handler

From Gramps
Revision as of 04:38, 1 April 2012 by Romjerome (Talk | contribs)

Jump to: navigation, search

Rationale and requirements for the localized Date Handler module for GRAMPS.

Why have different date handlers?

Different cultures and regions tend to have specific and different conventions for parsing and displaying dates. For example, the month and day order is different between most european coutries and the US. Also, each language has its own set of acceptable modifiers and qualifiers for the date: things like "from X to Y" or "between X and Y" may have different word order in different languages. Same with "around", "calculated", "estimated". Add to this calendar names and you have a compelling need for a dedicated date handler.

By providing date handlers, several problems are resolved.

  • Dates entered by users of that language in almost any form can be parsed by GRAMPS.
  • The displayed dates will look clear and correct to the users.
  • Translators do not have to worry about translating regular expressions like (from|before|between).

How to write a date handler

The framework for date handler plugins is in place. Here are the rules the language-specific plugins must obey to be compatible with the framework:

  • The plugin must define two classes: one for parsing and one for displaying dates.
  • The parser class must derive from the DateParser class:
   from _DateParser import DateParser
   class MyDateParser(DateParser):
       ...
The parser class must provide parse() method. In fact, since the base class already defines such method, it is most likely that you will only need to re-define class constants and, maybe, the init_string() method.
  • The displayer class must derive from the DateDisplay class:
   from _DateDisplay import DateDisplay
   class MyDateParser(DateDisplay):
       ...
The displayer class mus provide display() method. Again, the base class already provides such method, but you may need to redefine it for your language, it is not that hard.
  • The module must register itself as the date handler. This is done by inserting the following code at the end of your _Date_xx.py file:
   from _DateHandler import register_datehandler
   register_datehandler(('xx_XX','xx','xxxxx','xx_YY'),
                        MyDateParser,MyDateDisplay)
where MyDateParser and MyDateDisplay are the classes defined for parsing and displaying, and the items in quotes are language identifiers that may possibly be associated with your language. For example, different systems use ru, RU, ru_RU, koi8r, ru_koi8r, russian, Russian, ru_RU.koi8r, etc. to identify the Russian language.

Then you need to import the parser to GRAMPS by adding

   import _Date_xx

line to __init__.py file located in the same directory.

That's it for the requirements. The example date handling plugins can be found in _Date_xx.py under the src/DateHandler directory.

Classes and relations

A quick overview of current classes and relations between Date handlers.

Calendars

Gramps uses Gregorian calendar by-default, but also supports Julian calendar, Hebrew calendar, Islamic calendar, Persian calendar, French Republican calendar and Swedish calendar.

It is possible to add new one, like Chinese calendar, Indian Civil calendar, Bahá'í calendar, Mayan calendar, Zoroastrian calendar or Japonese calendar ... into gen/lib/calendar. We need to have rules which properly convert this new calendar to sdn (serial date number) and from sdn to calendar.

How to test a date handler for your locale

Testing into GRAMPS

You could have a look at DateParserDisplayTest debug tool on SVN and available under Menu -> Tools -> Debug ->.

  1. Add this debug tool under your .gramps/plugins34 directory
  2. Create a new empty Family Tree.
  3. Go on Menu -> Tools -> Debug -> test for date parser and displayer.
  4. Compare entries on Events View.

Tests with command-line

  • Download python script, copy the file under src (or gramps) directory, then under a console:
$ python src/date_test.py
$ export PYTHONPATH={path_to_/src}

It returns false positive/negative with modifier, calendar, quality, span, range dates, because it does not use translated words! You can try to generate a localized testing module by translating english words:

en: ("between 1750 and 1752", "between 1749 and 1750", True),
fr: ("entre 1750 et 1752", "entre 1749 et 1750", True),

See also