Scripting Tutorials

Any user familiar with GEDitCOM II's internal scripting language, AppleScript, Python, or Ruby can write their own scripts, package then in an "Extension" and thereby add new features to GEDitCOM II. Besides writing your own extensions, you can check the GEDitCOM II extensions page for ready-made extensions you can download and use immediately. If you do write an extension that you would like to share with GEDitCOM II users through the extensions page, please submit your extension to geditcom.com

Getting Started

Writing scripts requires some ability for computer programming and some knowledge of GEDitCOM II's internal scripting language, Apple Scripting, Python scripting, or Ruby scripting (which ever language you prefer). If you have programmed, but never used these languages, 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.

The recommended language is GEDitCOM II's internal scripting language. Internal scripts run about 20 times faster than when using other languages and do not have to rely on Apple continuing to support use of languages like AppleScript. All documentation for learning and writing internal scripts can be found in the Help window for the GEDitCOM Editor application included with GEDitCOM II.

If you prefer to use AppleScript, Python, or Ruby, a good way to learn is to see sample code. Among these three, Python is a good choice. It has many options and GEDitCOM II 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 Internal scripts, Python scripts, or Ruby scripts right in the GEDitCOM Editor. In fact, to modify and existing extension (or script), select it from the GEDitCOM II Extensions menu while holding down the option key. The extension (or script) will open for editing in the GEDitCOM Editor. When using 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. When writing internal scripts, its equivalent to a "Dictionary" is provided in the GEDitCOM Editor help window.

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 "Writing Scripts" section of the GEDitCOM Editor help information (note: prior to GEDitCOM II, version 2.0, the scripting help was in the GEDitCOM II help information). 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 Internl scripts, Python scripts, or Ruby scripts instead of Apple Scripts.

Extensions

Prior to GEDitCOM II, version 2.0, scripts were stand alone files that GEDitCOM II would open and run. Version 2.0 added the "Extensions" option. Stand alone scripts still work (and therefore these tutorials can still be followed), but when your scripts are done, it is strongly recommended that you package them into an extension. The details on creating and editing extensions is given in the GEDitCOM Editor help. The advantages of an extension are:

• Extensions can contain multiple scripts to provide a suite of utilities.
• Extensions are easily installed and deleted.
• An extension can provide robust documentation on how to use the scripts in that extension.
• An extension can include other files (such as Python modules or text files) for a better scripting environment.
• An extension will automatically verify the current version of GEDitCOM II is new enough to run the scripts.

Tutorials Index

The following are the scripting tutorials. These tutorials assume you a familiar with the chosen 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 installation comes with a GEDitCOMII.py module to make it easier to script GEDitCOM IU using Python and to turn GEDitCOM II/GEDitCOM Editor into a genealogy programming platform. This tutorial describes 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.