Lifelines Emulation in GEDitCOM II

Introduction

Lifelines was written by Tom Wetmore in the early 1990's and is now available under an MIT-style license. The two most important features of Lifelines (in my opinion) are that it is based on the GEDCOM standard and it is scriptable. These are also two things Lifelines has in common with GEDitCOM II. Although Lifelines is still available, it is a Unix command line tool and has not developed much since the 1990's. Wouldn't it be nice to have all the reports written for Lifelines work in a more modern user interface? This documentation explains how to use a Lifelines emulator to run Lifelines scripts in GEDitCOM II.

Lifelines scripts are written using its internal scripting language. In contrast, GEDitCOM II scripts use different scripting languages. In other words, the Lifelines emulations is not a full emulation. Instead, you have to first convert any script written for Lifelines to a python script that can run in GEDitCOM II. The core of this emulator is a lifelines.py python module that allows many Lifelines commands to work the same way in converted python scripts, but you will need to make additional changes as well, such as those involving differences in syntax between python and the internal Lifelines language.

The Lifelines emulator was written to minimize the number of changes required to convert a Lifelines script to a GEDitCOM II script. It was not written to maximize efficiency. Once a Lifelines program is converted and running, it will commonly be possible to speed it up by factors of 10 or more by revising the script for efficiency. This process will sometimes be possible just by changing the logic of the script. For other scripts, it may be better to completely rewrite it in the GEDitCOM II scripting language rather than rely on Lifelines emulation..

Getting Started

The first step in using Lifelines emulation is to install the files downloaded in this package into their proper places in the GEDitCOM II application support folder. Details on this process are given in the included ReadMe.txt file and in an on-line tutorial. Once installed, you can run converted Lifelines script by selecting them from the new Lifelines submenu in the Extensions menu. The scripts you can run immediately will be in two submenus to the new Lifelines menu. Those two menus are:

• Emulation - scripts converted to run in GEDitCOM II with code as close as possible to the original Lifelines script. These conversions retain the name of the Lifelines script but change the extension to .py for python code
• GEDitCOM II Native - scripts converted to run in GEDitCOM II but that also make use of native GEDitCOM II features to either run more efficiently or to improve appearance of the output. These conversions insert _gc_tt or _gc after the Lifelines name and use extension .py, where _gc_tt versions uses fixed-width font (like Lifelines scripts) and _gc versions use more flexible fonts that resemble other GEDitCOM II reports and extensions.

Writing and Converting Lifelines Scripts

The remainder of this document gives details on converting (or writing) Lifelines scripts to python scripts that can run in GEDitCOM II using the lifelines.py python module. The documentation sections are:

• Conversion Tasks
  • Outline of Emulated Lifelines Scripts
• Lifelines Emulation Reference

For ideas on scripts to convert, you can refer to the original Lifelines scripts provided with this package. The scripts in the Reports Converted folder have already be converted and the corresponding scripts found in the Emulations folder give examples of the conversion process. The scripts in the Reports Unconverted folder can be used as ideas for creating new scripts for GEDitCOM II. Finally, an on-line tutorial gives a specific example of converting a Lifelines script to the GEDitCOM II python script.

Conversion Tasks

The following is an outline of the process for converting a Lifelines script into an emulated GEDitCOM II script:

1. Copy the text of the Lifelines report to a plain text file with extension .py and open in the GEDitCOM Editor. The script must start by loading the lifelines modules.
2. Change all Lifelines proc and func methods to python def methods:

   proc name ( params ) { statements }

   or

   func name ( params ) { statements return result }

   to

   def name ( params ) : statements return result

   Furthermore, the python defs have to be indented precisely to indicate the statements are part of that method. In other words, the leading spaces have to be the same for all statements at the same level. You can use tabs or spaces, but not both (e.g., 4 spaces is not the same as tab even if they look the same in the editor). Finally, any code that calls a proc should be changed to the python calling syntax:

   call name (args)

   to

   name (args)

3. For the one main method, remove the proc main, remove its brackets ({}), move it to the end, and indent all lines for python needs starting with zero indent. In addition, the main method must begin with a preamble to set up the emulator and end with a finish() line to output the final report.
4. If the script declares globals, they must be changed from global(VAR) to VAR = None or give it an initial value. They can be declared in the beginning of the script and/or in the main method. If any globals are used in methods, that method has to declare them as globals using a python global VAR declaration.
5. Change all Lifelines comments (/* a comment ... */) to python comments (# a comment ...).
6. Change all Lifelines functions that set a variable passed to the method to the new forms documented here. The most common is to change set(VAR,VALUE) to VAR = VALUE. Other common ones that need changing are list(LISV_VAR) and table(TABLE_VAR), which are changed to LIST_VAR = list() and TABLE_VAR = table(). These changes are needed becase python cannot change the value of a variables passed as a parameter.
7. Change all conditionals from Lifelines syntax to python syntax:

   if ([varb,] expr) { statements } elsif ([varb], expr) { statements } else { statements }

   to

   if expr : statements elif expr : statements else : statements

   Notice that python cannot assign a variable and check an expression in the same line (as far as I know). Therefore Lifelines scripts that use the optional [varb,] above will need to assign that variable before the conditional.
8. Change all loops from Lifelines syntax to python syntax:

   while ([varb,] expr) { statements }

   to

   while expr : statements

   Notice that python cannot assign a variable and check an expression in the same line (as far as I know). Therefore Lifelines scripts that use the optional [varb,] above will need to initialize that variable before the loop, provide an appropriate test in the while line, and increment the variable someplace within the loop. Lifelines also provides many functions for looping (such as forindi()). Each of these will need a special conversion as documented below for each of those methods.
9. When the above steps are done, the converted script will follow the template described below.

With luck, the conversion will be complete. Try running in GEDitCOM II and see what happens. The most likely errors are python syntax errors (such as forgetting those ":" needed in many places or not indenting correctly). Once the python problems are fixed, it will start. The next class of errors will be if the script uses methods not yet implemented in the emulator or if their use requires modification. You will then have to revise the code as needed by the emulator, revise the code to use a different method (or use internal GEDitCOM II scripting methods), modify the emulator to support an unimplemented method, or decide this script will be too hard to convert.

Outline of Emulated Lifelines Scripts

Any Lifelines script converted to GEDitCOM II using the above methods should have sections found in the following template:

#!/usr/bin/python

# Import emulator modules
from lifelines load *
from operator import add,sub,mul,mod,neg,eq,ne,lt,gt,le,ge

# Globals

# Subroutines (python def methods)

# Preamble
linemode()
gdoc = ll_init("script title")

# Converted code from main method
out("Hello World!)

# Final Output
finish()

The first section imports methods from python modules. The lifelines.py module contains all the methods that implement the Lifelines emulation. The operator module has methods to support several Lifelines methods as listed above. If you need any of these methods, you need this import statement as well. You can omit ones not needed. Notice that the operator line does not import the div function. This omission is caused by changes in python 3.x (see below for more details). If you want to use native GEDitCOM II scripting methods within the translated script, you may need to import three more modules using:

from Foundation import *
from ScriptingBridge import *
from GEDitCOMII load *

The next two (optional) sections define global variables and procedures or functions used by the script.

The "Preamble" section selects the output mode and initializes the emulator. The ll_init() method verifies the script can run (which means the user has GEDitCOM II 1.6, build 2 or newer and that a document is open). It returns a reference to the current front document. If the script cannot run, a message will be printed and the script will quit. The one argument is the name of the script.

Note that unlike Lifelines, which can only have one data base open at a time, GEDitCOM II can have any number of open documents. As a consequence, a few emulated methods let you specify which document to use. When no document is specified, these methods all default to using the current front document.

The converted main method section contains the translation of the Lifelines main method, except that output mode settings are moved to the preamble.

Finally, call the finish() method, which outputs the results using the script's output mode (if you forget this command, a properly converted script will not show its output).

Lifelines Emulation Reference

The following sections list all methods from the Lifelines manual (which is available in pdf form or in a on-line translation). This reference does not define the behavior of the Lifelines functions (you should refer to the Lifelines documentation for that information). Instead, this reference lists all Lifelines methods, whether or not they are implemented, and whether or not they are identical or require some modification. Fully supported methods are in black; methods needing modification are in green, and methods not implemented are in red. The subsections are:

• Procedures and Functions
• Comments
• Statements
• Expressions
• Include Feature
• Built-in Functions
• Value Types
• Arithmetic and Logic Functions
• Person Functions
• Family Functions
• List Functions
• Table Functions
• GEDCOM Node Functions
• Event and Date Functions
• Value Extraction Functions
• User Interaction Functions
• String Functions
• Output Mode Functions
• Person Set Functions and GEDCOM Extraction
• Record Update Functions
• Record Linking Functions
• Miscellaneous Functions
• Additional GEDitCOM II Functions

Procedures and Functions

Convert these to python syntax as explain above.

(section index)

Comments

Convert these to python syntax as explain above.

(section index)

Statements

Conditionals, while loops, and procedure calls must all be converted to python syntax as explained above. Some additional statements also require minor changes:

(section index)

Expressions

All expression should be converted to python expressions, which are very similar to most programming languages. Most Lifelines functions used in expressions are supported for convenience.

(section index)

Include Feature

The include(string) statement is not supported in this translation. It can easily be replaced by putting the other script into a python module and then importing it with

import string
from string import *

Python will look for such modules in the same directory as the source script or in various other locations. When running in GEDitCOM II, python will look for modules in the "Modules" directory of the GEDitCOM II libraries in either the user or the system level "Application Support" folders.

(section index)

Built-in Functions

The follow sections list translations for Lifelines functions.

(section index)

Value Types

Many types are built-in python types. A few special types are implemented using python classes. Besides these types, you can extend the script with any other python types (e.g., longs (for unlimited integer precision) or floats).

(section index)

Arithmetic and Logic Functions

These Lifelines methods are mostly supported, but you can also convert to standard, simpler, and more powerful python expressions. The translations are:

To support the Lifelines style, you need to import them from the operator module at the beginning of the script using:

from operator import add,sub,mul,mod,neg,eq,ne,lt,gt,le,ge

Note the Lifelines is all integer calculations. In python you can enforce integer calculations or use floating point or longs (which have unlimited precision) as well.

Also notice that you should not import the python operator for div. The problem is that div was deleted in python 3.x. Thus, if you import it in a script, you will limited to using python 2.7. Furthermore, the results might vary depending on type of numbers passed to the operator function (i.e., integer or floating point numbers). Instead of importing div, you can use the div() function defined in the lifelines.py module. This module version always returns an integer division regardless of the variable types passed as arguments. To get floating-point divisions, use standard python divide expressions (e.g., x/y) instead of the div() function.

(section index)

Person Functions

The following functions retrieve information about an individual. When the function needs an INDI, you pass a reference to a GEDitCOM II individual record.

spouses(indi,sp,fam,num) {
    statements
}

(sp,fam,num,iter) = spouses(indi)
while sp :
    statements
    (sp,fam,num) = spouses(iter)

families(indi,fam,sp,num) {
    statements
}

(fam,sp,num,iter) = families(indi)
while fam :
    statements
    (fam,sp,num) = families(iter)

forindi(indi,num) {
    statements
}

for (num0,indi) in forindi() :
    num = num0+1
    statements

(section index)

Family Functions

The following functions retrieve information about a family. When the function needs an FAM, you pass a reference to a GEDitCOM II family record.

children(fam,chil,num) {
    statements
}

for (num0,chil) in children(fam) :
    num = num0+1
    statements

forfam(fam,num) {
    statements
}

for (num0,fam) in forfam() :
    num = num0+1
    statements

(section index)

List Functions

Lists are handled by standard python lists, which means you can make use of all the python list methods as well. The Lifelines methods are implemented as follows (some just for convenience):

forlist(alist,val,num) {
    statements
}

for (num0,val) in forlist() :
    num = num0+1
    statements

(section index)

Table Functions

Tables are handled by standard python dictionaries, which means you can make use of all the python dictionary methods. The Lifelines methods are implemented as follows (some just for convenience):

(section index)

GEDCOM Node Functions

Lifelines nodes are equivalent to GEDitCOM II structures. In addition, GEDitCOM II record objects can be used wherever a NODE is expected and it will be treated as the root or level 0 node for that record (a record's tag is its record type and its value is its record ID with the @ signs).

fornodes(node,nodev) {
    statements
}

for (num0,nodev) in fornodes(node) :
    statements

traverse(node,nodev,lev) {
    statements
}

(nodev,lev,iter) = traverse(node)
while nodev :
    statements
    (nodev,lev) = traverse(iter)

Note that traversing over all nodes can be slow in large files in both Lifelines and in GEDitCOM II. Scripts that use this method can often be made much faster by alternate methods. For example, you can grab the entire GEDCOM text of record or structure in a single GEDitCOM II record or structure property (e.g., indi.gedcom()). Once you have the GEDCOM string, you an step through the lines using python's built-in and powerful text tools.

(section index)

Event and Date Functions

A custom EVENT class handles the Lifelines style events.

(section index)

Value Extraction Functions

(section index)

User Interaction Functions

(section index)

String Functions

Strings are handled by standard python strings, which means you can make use of all the python string methods as well. The Lifelines methods are implemented as follows (some just for convenience):

(section index)

Output Mode Functions

In Lifelines scripts, elements that are not function calls are sent to the output. This method has to be modified in this emulator. The functions are listed here; the details as below the table.

Line Mode

The line mode is the default mode. In this mode strings are just appended to the output. Sections of Lifelines scripts that output content, however, must combine the content into strings and then pass the string to the out() command provided in this emulator to handle output. For example, a line such as:

"ANCESTORS OF -- " upper(name(i)) "    (" key(i) ") " nl() nl()

should be converted to

out("ANCESTORS OF -- "+upper(name(i))+"    ("+key(i)+") ")
nl()
nl()

which combines the strings (with +'s), sends the result to out(), and moves the nl() commands to their own lines. Alternatively, the nl() can be replaced with new line characters:

out("ANCESTORS OF -- "+upper(name(i))+"    ("+key(i)+") \n\n")

The line mode does not support the col() command. As a convenience, this emulator provides a cols() function to help rewrite Lifelines output in line mode that uses col(). For example, Linelines output such as:

col(1) name(i)
col(38) key(i)
col(49) stddate(birth(i))
col(64) stddate(death(i)) nl()

can be converted to

cols(name(i),38,key(),49,stddate(birth(i)),64,stddate(death(i)))
nl()

If the output is spread into separate statements, each call to cols() restarts at column 1 and you have to adjust the subsequent the column numbers. The above example could be converted to two statements using:

cols(name(i),38,key(),49)
cols(stddate(birth(i)),15,stddate(death(i)))
nl()

If the first item does not start in column 1, you can indent with:

cols("",5,name(i))

Finally, any column number can be negative of the desired column to right justify the preceding text in that output field.

Page Mode

Output in page mode is closer to Lifelines output except that all row(), col(), and pos() have to move to their own lines and all strings have to be sent to out(). For example, the Lifelines output:

pos(4,10)
"  FULL NAME:   " name(i) col(46) "(" key(i) ")" nl() nl()

can converted to

pos(4,10)
out("  FULL NAME:   "+name(i))
col(46)
out("("+key(i)+")")
nl()
nl()

Furthermore, you should use nl() to advance to next row in page mode and not simply output the character "\n".

Script Output

By default, the output is sent to a GEDitCOM II report with fixed-space font. To direct to a file instead of a report, use an outfile() command before the ll_init() command.

(section index)

Person Set Functions and GEDCOM Extraction

These functions are implemented with a custom SET class.

(i,v,n,iter) = forindiset(b)
while i :
    statements
    (i,v,n) = forindiset(iter)

(section index)

Record Update Functions

This Lifelines emulation does not support editing of the data. You can however, use other GEDitCOM II script-editing methods to make changes to the data in a script.

(section index)

Record Linking Functions

(section index)

Miscellaneous Functions

(section index)

Additional GEDitCOM II Functions

These methods were added as needed in various scripts and were used to keep the Lifelines emulation separate from all other GEDitCOM II modules.