README

GEDCOM-Ruby
-----------

This is a module for the Ruby language that defines a callback GEDCOM parser.
It does not do any validation of a GEDCOM file, but, using application-defined
callback hooks, can traverse any well-formed GEDCOM.

The module also includes a sophisticated date parser that can parse any
standard GEDCOM-formatted date (see the GEDCOM spec for details on the
format).


Installation
------------

To install, you will need a Ruby interpreter. 

You can try the samples by typing:

  ruby samples/count.rb samples/royal.ged
  ruby samples/birthdays.rb samples/royal.ged


Alternately, a C extension version of the date parser can be built. In order to
build you will need a C compiler (gcc is preferred).

  cd lib/
  ruby extconf.rb
  make
  make install

And then uncomment the line in gedcom.rb 
   #require '_gedcom'

and comment out
   require 'gedcom_date'

Usage
-----

To use this module in your own programs, you can either inherit from
the GEDCOM::Parser class (in which case the initialize method should
call 'super' before doing anything else), or you can instantiate the
GEDCOM::Parser class directly.

Either way, the before() and after() methods should then be used to
register callbacks for specified contexts.  A "context" is simply an
array of strings, where each element of the array specifies a GEDCOM
row type.  For example:

  [ "INDI" ] -> this context defines a row on which an individual is
  introduced.
  [ "INDI", "BIRT", "DATE" ] -> this context defines the birthdate of
  an individual.

Callbacks are registered using a proc, a method name, or a block:

  before( context, proc )
  after( context, proc )

  before( context, :method )
  after( context, :method )

  before( context ) do ... end
  after( context ) do ... end

The 'before' handler is called as soon as the context is recognized,
before anything else is done.  The 'after' handler is called when the
given context is about to expire.  For example, if the context were
["INDI"], the before handler would be called as soon as a row of type
'INDI' at level 0 was encountered, while the after handler would be
called as soon as another row of level 0 was encountered, before that
row's before handler was invoked.  This allows you do perform
initialization and commit operations.

Callbacks should take a single parameter, which will be the data portion of each row:

  def callbackFunction( data, cookie, parm )
    ...
  end

To parse a file, simply call the parser's 'parse' method, passing the
name of the file to parse.  The 'parse' method will take a filename,
or an IO instance.


API Reference
-------------

  module GEDCOM

    class Parser

      def initialize( &block )
        :: Constructor.  Can optionally be called with a block, which is
        used to define the before and after callbacks.

      def before( context, proc=nil, &block )
        :: Registers the given proc or block to be called
        as soon as the given context is recognized.

      def after( context, proc=nil, &block )
        :: Registers the given proc or block to be called as soon as
        the given context expires.
      
      def auto_concat= boolean
        :: Sets the auto-concatenation mode (defaults to true/on).
        When auto-concatenation is enabled, any CONT tags in the input
        will be appended to the previous tag, and the 'after' callback
        for that tag will include all of the concatenated data.  No
        callbacks for CONT tags will be made in this case.  When
        auto-concatenation is disabled, each CONT tag will be treated
        as normal, with before and after callbacks.

      def parse( file_or_io )
        :: Opens and parses the file with the given name, or an existing
        IO instance, invoking callbacks as the registered contexts are
        recognized.

      def context
        :: Gives the current context during the parse.  Intended to be
        used by callbacks to determine the context when the same
        callback method is used to handle multiple contexts.


    class Date

      def initialize( date_str, calendar=DateType::DEFAULT )
      def initialize( date_str, calendar=DateType::DEFAULT ) { |err_msg| ... }
        :: Creates a new GEDCOM Date object from the given string.  In the first form, if
           the string does not define a valid date, a GEDCOM::DateFormatException is raised.
           In the second form, an exception is not raised, but the given block is called
           when there is an error.  Also, in the second form, a Date object is still returned,
           but it will contain nothing except the string that was passed to it.

      def Date.safe_new( date_str )
        :: Creates a new GEDCOM Date object, but never throws a DateFormatException.

      def format
        :: Returns one of the following constants, indicating what the format of the date is:
             NONE, ABOUT, CALCULATED, ESTIMATED, BEFORE, AFTER, BETWEEN, FROM, TO, FROMTO,
             INTERPRETED, CHILD, CLEARED, COMPLETED, INFANT, PRE1970, QUALIFIED, STILLBORN,
             SUBMITTED, UNCLEARED, BIC, DNS, DNSCAN, DEAD

      def first
        :: Returns a GEDCOM::DatePart object that defines the first part of the date.

      def last
        :: Returns a GEDCOM::DatePart object that defines the last part of the date.  This
           will only be valid for a date format of BETWEEN or FROMTO (indicating a range
           of dates).

      def to_s
        :: Returns the date formatted as a string.

      def is_date?
        :: Returns true if the Date object defines a date, but returns false if it
           defines some non-date value (ie, there was an error parsing the date, or if the
           date format is one of CHILD, CLEARED, COMPLETED, INFANT, PRE1970, QUALIFIED,
           STILLBORN, SUBMITTED, UNCLEARED, BIC, DNS, DNSCAN, or DEAD).

      def is_range?
        :: Returns true if the Date object defines a date range (ie, format is either
           BETWEEN or FROMTO).  If this is true, then Date.last will return the end of
           the range.

      def <=>( date )
        :: Compares this date with the parameter, and returns -1, 0, or 1.


    class DatePart

      def calendar
        :: Returns the calendar that was used to represent the given date.  Valid values
           are DateType::GREGORIAN, DateType::JULIAN, DateType::HEBREW, DateType::FRENCH,
           DateType::FUTURE, DateType::UNKNOWN, and DateType::DEFAULT.

      def compliance
        :: Returns the compliance of the date (ie, whether it is a valid date or not).
           Valid values are DatePart::NONE (meaning it is a valid date), DatePart::PHRASE
           (meaning the date contains a phrase, not a date) and DatePart::NONSTANDARD
           (meaning there was an error parsing the date).

      def phrase
        :: If the compliance is DatePart::PHRASE, this will return the phrase value.
           Otherwise, this will raise a DateFormatException.

      def has_day?
        :: Returns true if the date contains a day value.

      def has_month?
        :: Returns true if the date contains a month value.

      def has_year?
        :: Returns true if the date contains a year value.

      def has_year_span?
        :: Returns true if the date contains a span of years (valid only for
           DateType::GREGORIAN calendars).  This means the date was formatted
           like '25 Jul 1974-1980'.

      def day
        :: Returns the day portion of the date, if it has a day.  If it does not
           have a day, a DateFormatException is raised.

      def month
        :: Returns the month portion of the date, if it has a month.  If it does not
           have a month, a DateFormatException is raised.  (The month value will
           be an integer, with 1 being the first month of the year.)

      def year
        :: Returns the year portion of the date, if it has a year.  If it does not
           have a year, a DateFormatException is raised.

      def to_year
        :: Returns the second year portion of the date, if it has a year span.  If
           it does not contain a year span, a DateFormatException is raised.
      
      def epoch
        :: Returns either "BC" or "AD", as appropriate.

      def to_s
        :: Converts the DatePart object to a string.

      def <=>( date_part )
        :: Compares this date_part with the parameter, and returns -1, 0, or 1.