Scripting Tutorials

Any user familiar with AppleScript, Python, or Ruby can write their own scripts and add new features to GEDitCOM II. Besides writing your own scripts, you can check the GEDitCOM II scripts page for ready-made scripts you can download and use immediately. If you do write a script that you would like to share with GEDitCOM II users through the scripts page, please submit your script to geditcom.com

Getting Started

Writing scripts requires some ability for computer programming and some knowledge of Apple Scripting, Python scripting, or Ruby scripting (which ever language you prefer). If you have programmed, but never used Apple Script, Python, or Ruby, it is an easy to get started. The basic structures of these languages are simple. It takes a little more effort, however, to understand the finer points of each one. A good way to learn all the tricks is to see sample code. These tutorials provide sample code specifically for writing scripts for GEDitCOM II.

If you are new to scripting and deciding between Apple Script, Python, and Ruby, the clear choice is Python. This language has many options and GEDitCOM II (version 1.6, build 2 or newer) comes with a Python module for GEDitCOM II that turns the scripting process into a fairly robust genealogy programming platform.

Here are some references for learning AppleScript, Python, or Ruby:

• Python Language Documentation - the official Python web site's documentation page with tutorials and more.
• "AppleScript: The Comprehensive Guide to Scripting and Automation on Mac OS X," Hanaan Rosenthal, Apress; 2nd Rev edition (September 25, 2006). This 800 page book has most of what you need for novice to professional programmers (Buy on Amazon.com).
• "AppleScript: The Definitive Guide: Scripting and Automating Your Mac," Matt Neuberg, O'Reilly Media, Inc.; 2 edition (January 1, 2006). This book explains many of the complexities of AppleScript that are not described elsewhere (Buy on Amazon.com).
• AppleScript Language Guide - Apple's developer documentation on the AppleScript language. It is a good reference but is not very good for learning AppleScript.
• Ruby Language Documentation - the official Ruby web site's documentation page with tutorials and more.

You can edit and run Python or Ruby scripts right in the GEDitCOM Editor. In fact, to modify and existing script, select it from the GEDitCOM II menu while holding down the option key. The script will open for editing in the GEDitCOM Editor. To learn or use AppleScript, you write scripts using Apple's "Script Editor", which you will find in your Applications folder on all new Macs. You can write, compile, and run scripts all within the "Script Editor".

All applications that are scriptable (like GEDitCOM II) come with a "Dictionary" that describes all the objects in the application and all the commands supported by the application. Whenever writing scripts for a new application, the first thing you need to do is open its "Dictionary" and explore its scripting options. These "Dictionaries" are notoriously too brief. When the information is incomplete, you might need to experiment to see what works. Once you get some things working for an application, the "Dictionary" will start to make sense. You can open any application's "Dictionary" by using the "Script Editor". Choose the "Open Dictionary..." menu command and select an application from the list of those with dictionaries.

You can open GEDitCOM II's "Dictionary" in the "Script Editor" to see all its options. To get more important information, you should also refer to the "Scripting Features" section of the GEDitCOM II help information (from the "Help" menu). It gives extra details on objects in GEDitCOM II's "Dictionary," particularly on the supported commands. It also gives details on changes that are needed when writing Python or Ruby scripts instead of Apple Scripts (the dictionaries are written for Apple Scripts).

Tutorials Index

The following are the scripting tutorials. These tutorials assume you a familiar with the choosen scripting language and are familiar with scripting "Dictionaries" for applications. You can download the scripts in the tutorials and run them in GEDitCOM II them while reading the tutorials.

Running Lifelines Programs in GEDitCOM II (Python)

This tutorial explains how to get started converted Lifelines programs into python scripts for GEDitCOM II. The process is controlled by a lifelines.py modules that can be download (along with documentation and sample scripts) from the tutorial.

GEDitCOM II Scripting Module (Python)

A powerful feature of Python is its support for modules for defining libraries of classes and functions that can be used in other scripts. Starting with GEDitCOM II, version 1.6, build 2, the standard installion comes with a GEDitCOMII.py module to mae it easier to script GEDitCOM IU using Python and to turn GEDitCOM II/GEDitCOM Editor into a genealogy programming platform. This tutorial describeds all the options available in this evolving module.

Creating a Custom Report (Python)

One great use of GEDitCOM II scripts is to design your own custom genealogy reports. This tutorial shows a basic report that calculates husbands' and wives' average ages at marriage and when their children were born. By changing selected sections of the sample scripts, you can create your own report scripts for any other information you want to extract from your data.

Creating a Custom Report (AppleScript)

Same as the previous Python report tutorial but shows how to do the script using Apple Script.

Creating a Custom Report (Ruby)

Same as the previous Python report tutorial but shows how to do the script using Ruby.

Customizing the "Create Web Site" Script (AppleScript)

GEDitCOM II is provided with a script for creating web site content. This tutorial explains some options you have for editing that script to customize the type of web site that gets created.

Scripting Utility Subroutines (AppleScript)
Scripting Utility Subroutines (Ruby)

These two sections describe a series of utility subroutines for Apple Script or Ruby scripts. They are used in the tutorial scripts. When writing your own scripts, you can copy and paste them to add common GEDitCOM II functions to your scripts. These utilities are not need when writing Python scripts because all their functions and much, much more are available in the Python module for GEDitCOM II.