Installing Python

Before you can run a .py script, Python needs to be installed on your system. Mac OS X users don't need to do anything because Python is already installed (but see below for how to force Golly to use a newer version of Python). Windows and Linux users can download a Python installer from www.python.org/download. Note that a 32-bit version of Golly requires a 32-bit version of Python, and a 64-bit Golly requires a 64-bit Python.

On Windows and Linux, the Python library is loaded at runtime (the first time you try to run a script). Golly initially attempts to load a particular version of the Python library: python27.dll on Windows or libpython2.7.so on Linux. The numbers correspond to Python version 2.7. If that library can't be found then you'll be prompted to enter a different library name matching the version of Python installed on your system. A successfully loaded library is remembered (in your GollyPrefs file) so you won't get the prompt again unless you remove Python or install a new version. If Python isn't installed then you'll have to hit Cancel and you won't be able to run any .py scripts.

 
Example scripts

The Scripts folder supplied with Golly contains a number of example Python scripts:

To run one of these scripts, tick the Show Scripts item in the File menu and then simply click on the script's name. You can also select one of the Run items in the File menu. For a frequently used script you might like to assign a keyboard shortcut to run it (see Preferences > Keyboard).

When Golly starts up it looks for a script called golly-start.py in the same directory as the Golly application and then in a user-specific data directory (see the getdir command for the likely path on your system). If the script is found then it is automatically executed.

There are a number of ways to abort a running script. Hit the escape key, or click on the stop button in the tool bar, or select the Stop item in the Control menu.

 
Golly's scripting commands

This section describes all the commands that can be used in a script after importing the golly module. Commands are grouped by function (filing, editing, control, viewing, layers and miscellaneous) or you can search for individual commands alphabetically:

 
FILING COMMANDS

 
EDITING COMMANDS

 
CONTROL COMMANDS

 
VIEWING COMMANDS

 
LAYER COMMANDS

 
MISCELLANEOUS COMMANDS

 
Cell lists

Some scripting commands manipulate patterns in the form of cell lists. Golly supports two types of cell lists: one-state and multi-state. A one-state cell list contains an even number of integers specifying the x,y coordinates for a set of cells, all of which are assumed to be in state 1:

A multi-state cell list contains an odd number of integers specifying the x,y,state values for a set of cells. If the number of cells is even then a padding integer (zero) is added at the end of the list to ensure the total number of integers is odd:

All scripting commands that input cell lists use the length of the list to determine its type. When writing a script to handle multi-state cell lists you may need to allow for the padding integer, especially if accessing cells within the list. See tile.py for example.

Note that all scripting commands return [] if the resulting cell list has no cells. They never return [0], although this is a perfectly valid multi-state cell list and all commands can input such a list. For example, newlist = golly.join(list1,[0]) can be used to convert a non-empty one-state list to multi-state.

One-state cell lists are normally used in a two-state universe, but they can also be used in a universe with more than two states. A multi-state cell list can be used in a two-state universe, but only if the list's cell states are 0 or 1.

The ordering of cells within either type of list doesn't matter. Also note that positive y values increase downwards in Golly's coordinate system.

 
Rectangle lists

Some commands manipulate rectangles in the form of lists. An empty rectangle is indicated by a list with no items; ie. []. A non-empty rectangle is indicated by a list containing four integers:

The first two items specify the cell at the top left corner of the rectangle. The last two items specify the rectangle's size (in cells). The width and height must be greater than zero.

 
Using the glife package

The glife folder included in the Scripts/Python folder is a Python package that provides a high-level interface to some of Golly's scripting commands (it's based on Eugene Langvagen's life package included in PLife). When a script imports glife or any of its submodules, Python automatically executes the __init__.py module. This module defines the pattern and rect classes as well as a number of useful synonyms and helper functions. For example, consider this script:

Here is the equivalent script without using glife:

Here are some helper functions defined in glife:

Most of the examples in the Scripts folder import glife, but it isn't compulsory. You might prefer to create your own high-level interface for the scripts you write.

 
Potential problems

1. The Python interpreter's memory allocator never releases memory back to the operating system. If you run a complicated or buggy script that uses lots of (Python) memory then that memory is no longer available for use by Golly, so you might need to quit Golly and restart. Python 2.5 has a smarter memory allocator that does release memory in some stuations, but it's still far from ideal.

2. The first time you run a script that imports a particular module, the Python interpreter caches the results so it won't need to reload that module the next time it is imported. This is good for efficiency, but it's a problem if you've modified an imported module and you want to test your changes. One solution is to quit Golly and restart. Another solution is to force the module to be reloaded by inserting a line like

at the start of each script that imports the module. When the module is stable you can remove or comment out the reload command.

3. The escape key check to abort a running script is not done by Python but by each Golly scripting command. This means that very long Python computations should call an occasional "no-op" command like doevent("") to allow the script to be aborted in a timely manner.

4. When writing a script that creates a pattern, make sure the script starts with a new command (or, less useful, an open command) otherwise the script might create lots of temporary files or use lots of memory. From the undo history's point of view there are two types of scripts:

• A script that calls new or open is assumed to be creating some sort of pattern, so when Golly sees these commands it clears any undo history and sets an internal flag that says "don't mark this layer as dirty and don't bother recording any further changes".
• A script that doesn't call new or open is assumed to modify the current pattern. Golly must record all the script's changes so that when it finishes you can select "Undo Script Changes" from the Edit menu. Generating changes (due to run calls) are stored in temporary files, while other changes are stored in memory.

 
Python on Mac OS X

Even though Apple supply Python with OS X, it is usually not the latest version. Golly is linked against the Python 2.6 framework stored in /System/Library/Frameworks. If you have Python 2.7 installed in your system you can tell Golly to use it by quitting Golly, opening Terminal.app and entering this command (on one line):

If you ever need to switch back to the older Python then just run the command again with the framework paths swapped. To verify which version of Python Golly is using, copy the following code, start up Golly and select Run Clipboard from the File menu:

 
Python copyright notice

Golly uses an embedded Python interpreter to execute scripts. The Python license agreement is included in Golly's LICENSE file. Here is the official Python copyright notice: