Installing Perl
Example scripts
Golly's scripting commands
Cell arrays and rectangle arrays
Potential problems
Perl copyright notice

 
Installing Perl

Before you can run a .pl script, Perl needs to be installed on your system. Mac OS X users don't need to do anything because Perl is already installed. If you are running Linux then you probably have Perl installed; if not, visit www.perl.org and download a suitable installer. Windows users are advised to download the ActivePerl installer.

On Windows, the Perl library is loaded at runtime (the first time you try to run a .pl script). Golly initially attempts to load perl58.dll where the numbers correspond to Perl version 5.8.x. If that library can't be found then you'll be prompted to enter a different library name matching the version of Perl 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 Perl or install a new version. If Perl isn't installed then you'll have to hit Cancel and you won't be able to run any .pl scripts.

 
Example scripts

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

density.pl — calculates the density of the current pattern
envelope.pl — uses multiple layers to remember a pattern's live cells
giffer.pl — creates an animated GIF using the current selection
goto.pl — goes to a given generation
invert.pl — inverts all cell states in the current selection
oscar.pl — detects oscillating patterns, including spaceships
pop-plot.pl — displays a plot of population versus time
shift.pl — shifts the current selection by given x y amounts
tile.pl — tiles the current selection with the pattern inside it
tile-with-clip.pl — tiles the current selection with the clipboard pattern

The easiest way to run one of these scripts is to tick the Show Scripts item in the File menu and then simply click on the script you wish to run. You can also select one of the Run items in the File menu.

If a script called golly-start.pl exists in the same folder as the Golly application then it is automatically executed when Golly starts up.

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 Golly-specific scripting commands that can be used in a Perl script. Commands are grouped by function (filing, editing, control, viewing, layers and miscellaneous) or you can search for individual commands alphabetically:

g_addlayer
g_advance
g_appdir
g_autoupdate
g_check
g_clear
g_clone
g_copy
g_cut
g_datadir
g_dellayer
g_dokey
g_duplicate
g_empty
g_error
g_evolve
g_exit
g_fit
g_fitsel
g_flip
g_getbase
g_getcell
g_getcells
g_getclip
g_getcolor
g_getcursor
g_getgen
g_getkey
g_getlayer
g_getmag
g_getname
g_getoption
g_getpop
g_getpos
g_getrect
g_getrule
g_getselrect
g_getstep
g_getstring
g_hash
g_help
g_load
g_maxlayers
g_movelayer
g_new
g_note
g_numlayers
g_open
g_parse
g_paste
g_putcells
g_randfill
g_reset
g_rotate
g_run
g_save
g_select
g_setbase
g_setcell
g_setcolor
g_setcursor
g_setgen
g_setlayer
g_setmag
g_setname
g_setoption
g_setpos
g_setrule
g_setstep
g_show
g_shrink
g_step
g_store
g_transform
g_update
g_visrect
g_warn

 
FILING COMMANDS

g_open($filename, $remember=0)
Open the given pattern file. A non-absolute path is relative to the location of the script. The 2nd parameter is optional (default = 0) and specifies if the file should be remembered in the Open Recent submenu.
Example: g_open("my-patterns/foo.rle");

g_save($filename, $format, $remember=0)
Save the current pattern in a given file using the specified format ("rle" or "mc"). A non-absolute path is relative to the location of the script. The 3rd parameter is optional (default = 0) and specifies if the file should be remembered in the Open Recent submenu. If the savexrle option is 1 then extended RLE format is used (see the Save Extended RLE item for details).
Example: g_save("foo.rle", "rle", 1);

g_load($filename)
Read the given pattern file and return a cell array reference.
Example: $blinker = g_load("blinker.rle");

g_store($cellarray, $filename)
Write the pattern in the given cell array reference to the specified file in RLE format. If the savexrle option is 1 then extended RLE format is used (see the Save Extended RLE item for details).
Example: g_store($cellarray, "foo.rle");

g_appdir()
Return the Golly application directory as a string.
Example: g_open(g_appdir()."Patterns/Breeders/breeder.lif");

g_datadir()
Return Golly's user-specific data directory as a string:

On Linux: ~/.golly/
On Mac OS X: ~/Library/Application Support/Golly/
On Windows: C:\Documents and Settings\username\Application Data\Golly\

Example: g_store($cellarray, g_datadir()."foo.rle");

 
EDITING COMMANDS

g_new($title)
Create a new, empty universe and set the window title. If the given title is empty then the current title won't change.
Example: g_new("test-pattern");

g_cut()
Cut the current selection to the clipboard.

g_copy()
Copy the current selection to the clipboard.

g_clear($where)
Clear inside (where = 0) or outside (where = 1) the current selection.
Example: g_clear(1);

g_paste($x, $y, $mode)
Paste the clipboard pattern at x,y using the given mode ("copy", "or" or "xor").
Example: g_paste(0, 0, "or");

g_shrink()
Shrink the current selection to the smallest rectangle enclosing all of the selection's live cells.

g_randfill($percentage)
Randomly fill the current selection to a density specified by the given percentage (1 to 100).
Example: g_randfill(50);

g_flip($direction)
Flip the current selection left-right (direction = 0) or top-bottom (direction = 1).

g_rotate($direction)
Rotate the current selection 90 degrees clockwise (direction = 0) or anticlockwise (direction = 1).

g_evolve($cellarray, $numgens)
Advance the pattern in the given cell array reference by the specified number of generations and return a reference to the new cell array.
Example: $newpatt = g_evolve($currpatt, 100);

g_transform($cellarray, $x0, $y0, $axx=1, $axy=0, $ayx=0, $ayy=1)
Apply an affine transformation to the pattern in the given cell array reference and return a reference to the new cell array. For each x,y cell in the input array the corresponding xn,yn cell in the output array is calculated as xn = x0 + x*axx + y*axy, yn = y0 + x*ayx + y*ayy.
Example: $rot_blinker = g_transform($blinker, 0, 0, 0, -1, 1, 0);

g_parse($string, $x0=0, $y0=0, $axx=1, $axy=0, $ayx=0, $ayy=1)
Parse an RLE or Life 1.05 string and return a reference to an optionally transformed cell array.
Example: $blinker = g_parse("3o!");

g_putcells($cellarray, $x0=0, $y0=0, $axx=1, $axy=0, $ayx=0, $ayy=1, $mode="or")
Paste the pattern in the given cell array reference into the current universe using an optional affine transformation and optional mode ("copy", "or", "xor", or "not").
Example: g_putcells($cells, 6, -40, 1, 0, 0, 1, "xor");

g_getcells(@rectarray)
Return any live cells in the specified rectangle as a cell array reference. The given rectangle array can be empty (in which case the cell array is empty) or it must represent a valid rectangle of the form (x,y,width,height).
Example: $cells = g_getcells( g_getrect() );

g_getclip()
Parse the pattern data in the clipboard and return a cell array reference, but where the first two numbers are the pattern's width and height (not necessarily the minimal bounding box because the pattern might have empty borders, or it might even be empty).
Example: $cells = g_getclip();

g_hash(@rectarray)
Return an integer hash value for the pattern in the given rectangle. Two identical patterns will have the same hash value, regardless of their location in the universe. This command provides a fast way to detect pattern equality, but there is a tiny probability that two different patterns will have the same hash value, so you might need to use additional (slower) tests to check for true pattern equality.
Example: $h = g_hash( g_getrect() );

g_select(@rectarray)
Create a selection if the given array represents a valid rectangle of the form (x,y,width,height) or remove the current selection if the given array is empty.
Example: g_select(-10,-10,20,20);

g_getrect()
Return the current pattern's bounding box as an array. If there is no pattern then the array is empty, otherwise the array is of the form (x,y,width,height).
Example: @pattrect = g_getrect();

g_getselrect()
Return the current selection rectangle as an array. If there is no selection then the array is empty, otherwise the array is of the form (x,y,width,height).
Example: @selrect = g_getselrect();

g_setcell($x, $y, $state)
Set the given cell to the specified state (0 for a dead cell, 1 for a live cell).

g_getcell($x, $y)
Return the state of the given cell. The following example inverts the state of the cell at 0,0.
Example: g_setcell(0, 0, 1 - g_getcell(0, 0));

g_setcursor($index)
Set the cursor according to the given index and return the old cursor index. The valid index values are 0 for the pencil cursor, 1 for the cross cursor, 2 for the hand cursor, 3 for the zoom-in cursor and 4 for the zoom-out cursor.
Example: $oldcurs = g_setcursor(3);

g_getcursor()
Return the current cursor index.

 
CONTROL COMMANDS

g_run($numgens)
Run the current pattern for the specified number of generations. Intermediate generations are never displayed, and the final generation is only displayed if the current g_autoupdate setting is 1.
Example: g_run(100);

g_step()
Run the current pattern for the current step. Intermediate generations are never displayed, and the final generation is only displayed if the current g_autoupdate setting is 1.

g_setstep($exp)
Set the step to base^exp (use the g_setbase command to change the base). A negative exponent sets the step to 1; it also sets a delay between each step, but that delay is ignored by the g_run and g_step commands.
Example: g_setstep(0);

g_getstep()
Return the current step exponent.
Example: g_setstep( g_getstep() + 1 );

g_setbase($base)
Set the base step for the current universe type (hashing or non-hashing), so you might need to call g_setoption("hashing",1/0) first. The given base must be an integer from 2 to 10000. The current step is also changed to base^exp where exp is the current step exponent returned by g_getstep().
Example: g_setbase(2);

g_getbase()
Return the current base step for the current universe type (hashing or non-hashing).

g_advance($where, $numgens)
Advance inside (where = 0) or outside (where = 1) the current selection by the specified number of generations. The generation count does not change.
Example: g_advance(0, 3);

g_reset()
Restore the starting pattern and generation count. Also reset the rule, scale, location, step exponent and hashing option to the values they had at the starting generation. The starting generation is usually zero, but it can be larger after loading an RLE/macrocell file that stores a non-zero generation count.

g_setgen($gen)
Set the generation count using the given string. Commas and other punctuation marks can be used to make a large number more readable. Include a leading +/- sign to specify a number relative to the current generation count.
Example: g_setgen("-1,000");

g_getgen($sepchar="")
Return the current generation count as a string. The optional parameter (default = "") specifies a separator character that can be used to make the resulting string more readable. For example, g_getgen(",") would return a string like "1,234,567" but g_getgen() would return "1234567". Use the latter call if you want to do arithmetic on the generation count.
Example: $gen = g_getgen();

g_getpop($sepchar="")
Return the current population as a string. The optional parameter (default = "") specifies a separator character that can be used to make the resulting string more readable. For example, g_getpop(",") would return a string like "1,234,567" but g_getpop() would return "1234567". Use the latter call if you want to do arithmetic on the population count.
Example: $pop = g_getpop();

g_empty()
Return 1 if the universe is empty or 0 if there is at least one live cell. This is much more efficient than testing getpop() == 0.
Example: g_exit("All cells are dead.") if g_empty();

g_setrule($string)
Set the current rule according to the given string. If the string is invalid then you'll get an error message and the script will be aborted (and the original rule will be restored).
Example: g_setrule("b3/s23");

g_getrule()
Return the current rule as a string.
Example: $oldrule = g_getrule();

 
VIEWING COMMANDS

g_setpos($x, $y)
Change the position of the viewport so the given cell is in the middle. The x,y coordinates are given as strings so the viewport can be moved to any location in the unbounded universe. Commas and other punctuation marks can be used to make large numbers more readable. Apart from a leading minus sign, most non-digits are simply ignored; only alphabetic characters will cause an error message. Note that positive y values increase downwards in Golly's coordinate system.
Example: g_setpos("1,000,000,000,000", "-123456");

g_getpos($sepchar="")
Return the x,y position of the viewport's middle cell in the form of a Perl array containing two strings. The optional parameter (default = "") specifies a separator character that can be used to make the resulting strings more readable. For example, g_getpos(",") might return two strings like "1,234" and "-5,678" but g_getpos() would return "1234" and "-5678". Use the latter call if you want to do arithmetic on the x,y values.
Example: my ($x, $y) = g_getpos();

g_setmag($mag)
Set the magnification, where 0 corresponds to the scale 1:1, 1 = 1:2, -1 = 2:1, etc. The maximum allowed magnification is 4 (= 1:16).
Example: g_setmag(0);

g_getmag()
Return the current magnification.
Example: g_setmag( g_getmag() - 1 );

g_fit()
Fit the entire pattern in the viewport.

g_fitsel()
Fit the current selection in the viewport. The script aborts with an error message if there is no selection.

g_visrect(@rectarray)
Return 1 if the given rectangle is completely visible in the viewport. The rectangle must be an array of the form (x,y,width,height).
Example: g_fitsel() if !g_visrect(@selrect);

g_autoupdate($bool)
When Golly runs a script this setting is initially 0. If the given parameter is 1 then Golly will automatically update the viewport and the status bar after each command that changes the universe or viewport in some way. Useful for debugging Perl scripts.
Example: g_autoupdate(1);

g_update()
Immediately update the viewport and the status bar, regardless of the current g_autoupdate setting. Note that Golly always does an update when a script finishes.

 
LAYER COMMANDS

g_addlayer()
Add a new, empty layer immediately after the current layer and return the new layer's index, an integer from 0 to g_numlayers() - 1. The new layer becomes the current layer and inherits most of the previous layer's settings, including its algorithm, rule, scale, location, cursor mode, etc. The step exponent is set to 0, there is no selection, no origin offset, and the layer's initial name is "untitled".
Example: $newindex = g_addlayer();

g_clone()
Like g_addlayer (see above) but the new layer shares the same universe as the current layer. The current layer's settings are duplicated and most will be kept synchronized so that a change to one clone automatically changes all the others. Each cloned layer does however have a separate viewport, so the same pattern can be viewed at different scales and locations (at the same time if layers are tiled).
Example: $cloneindex = g_clone();

g_duplicate()
Like g_addlayer (see above) but the new layer has a copy of the current layer's pattern. Also duplicates all the current settings but, unlike a cloned layer, the settings are not kept synchronized.
Example: $dupeindex = g_duplicate();

g_dellayer()
Delete the current layer. The current layer changes to the previous layer (unless layer 0 was deleted).

g_movelayer($fromindex, $toindex)
Move a specified layer to a new position in the layer sequence. The chosen layer becomes the current layer.
Example: g_movelayer(1, 0);

g_setlayer($index)
Set the current layer to the layer with the given index, an integer from 0 to g_numlayers() - 1.
Example: g_setlayer(0);

g_getlayer()
Return the index of the current layer, an integer from 0 to g_numlayers() - 1.
Example: $currindex = g_getlayer();

g_numlayers()
Return the number of existing layers, an integer from 1 to g_maxlayers().
Example: g_setoption("tilelayers",1) if g_numlayers() > 1;

g_maxlayers()
Return the maximum number of layers (10 in this implementation).

g_setname($string, $index=current)
Set the name of the given layer, or the current layer's name if no index is supplied.
Example: g_setname("temporary");

g_getname($index=current)
Return the given layer's name, or the current layer's name if no index is supplied.
Example: g_dellayer() if g_getname() eq "temporary";

 
MISCELLANEOUS COMMANDS

g_setoption($name, $value)
Set the given option to the given value. The old value is returned to make it easy to restore a setting. Here are all the valid option names and their possible values:

"autofit" 1 or 0
"boldspacing" 2 to 1000 (cells)
"fullscreen" 1 or 0
"hashing" 1 or 0
"hyperspeed" 1 or 0
"maxdelay" 0 to 5000 (millisecs)
"mindelay" 0 to 5000 (millisecs)
"opacity" 1 to 100 (percent)
"savexrle" 1 or 0
"showboldlines" 1 or 0
"showexact" 1 or 0
"showgrid" 1 or 0
"showhashinfo" 1 or 0
"showlayerbar" 1 or 0
"showpatterns" 1 or 0
"showscripts" 1 or 0
"showstatusbar" 1 or 0
"showtoolbar" 1 or 0
"stacklayers" 1 or 0
"swapcolors" 1 or 0
"switchlayers" 1 or 0
"synccursors" 1 or 0
"syncviews" 1 or 0
"tilelayers" 1 or 0

Example: $oldhash = g_setoption("hashing", 1);

g_getoption($name)
Return the current value of the given option. See above for a list of all the valid option names.
Example: g_setrule("b0/s1") if !g_getoption("hashing");

g_setcolor($name, $r, $g, $b)
Set the given color to the given RGB values (integers from 0 to 255). The old RGB values are returned as an array of 3 integers to make it easy to restore the color. Here is a list of all the valid color names and how they are used:

"livecells0" for displaying live cells in layer 0
... ...
"livecells9" for displaying live cells in layer 9
"deadcells" for displaying dead cells
"paste" for pasting patterns
"select" for selections (will be 50% transparent)
"hashing" for status bar background if hashing
"nothashing" for status bar background if not hashing

Example: @oldrgb = g_setcolor("livecells0", 0, 0, 255);

g_getcolor($name)
Return the current RGB values for the given color as an array of 3 integers. See above for a list of all the valid color names.
Example: my ($r, $g, $b) = g_getcolor("deadcells");

g_getstring($prompt, $initial="", $title="")
Display a dialog box and get a string from the user. If the initial string is supplied it will be shown and selected. If the title string is supplied it will be used in the dialog's title bar. The script will be aborted if the user hits the dialog's Cancel button.
Example: $i = g_getstring("Enter a number:","100");

g_getkey()
Return a key hit by the user as a single character, or an empty string if no key was hit. The characters returned by this command are a subset of ASCII:

' ' to '~' all displayable characters (space to tilde)
chr(8) backspace or delete
chr(9) tab
chr(13) return or enter
chr(28) to chr(31) left, right, up, down arrows

Example: $ch = g_getkey();

g_dokey($char)
This command allows limited keyboard interaction while a script is running. The given character is passed to Golly's keyboard event handler, but all keyboard shortcuts that can change the current pattern will be ignored.
Example: g_dokey( g_getkey() );

g_show($message)
Show the given string in the bottom line of the status bar. The status bar is automatically shown if necessary.
Example: g_show("Hit any key to continue...");

g_error($message)
Beep and show the given string in the bottom line of the status bar. The status bar is automatically shown if necessary.
Example: g_error("The pattern is empty.");

g_warn($message)
Beep and show the given string in a modal warning dialog. Useful for debugging Perl scripts or displaying error messages.
Example: g_warn("xxx = $xxx");

g_note($message)
Show the given string in a modal information dialog. Useful for displaying multi-line results.
Example: g_note("Line 1\nLine 2\nLine 3");

g_help($htmlfile)
Open the given HTML file in the help window. A non-absolute path is relative to the location of the script.
Example: g_help("results.html");

g_check($bool)
When Golly runs a script this setting is initially 1, which means that event checking is enabled. If the given parameter is 0 then event checking is disabled. Typically used to prevent mouse clicks being seen at the wrong time. This should only be done for short durations because the script cannot be aborted while the setting is 0.
Example: g_check(0);

g_exit($message="")
Exit the script with an optional error message. If a non-empty string is supplied then it will be displayed in the status bar along with a beep, just like the g_error command. If no message is supplied, or if the string is empty, then there is no beep and the current status bar message will not be changed.
Example: g_exit("There is no pattern.") if g_empty();

 
Cell arrays and rectangle arrays

Some of Golly's scripting commands manipulate patterns in the form of cell arrays. A cell array is simply a Perl array containing integer cell coordinates:

( x1, y1, x2, y2 . . . xn, yn )

A cell array should always contain an even number of integers. The ordering of cells within the array doesn't matter. Note that positive y values increase downwards in Golly's coordinate system.

Cell arrays can contain millions of coordinates, so all commands that accept or return cell arrays actually use references to those arrays.

Some commands manipulate rectangles in the form of arrays. An empty rectangle is indicated by an array with no items; ie. (). A non-empty rectangle is indicated by an array containing four integers:

( left, top, width, height )

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.

Unlike cell arrays, rectangle arrays only contain a few items (0 or 4), so all commands that accept or return rectangle arrays don't bother using array references.

 
Potential problems

1. Mac users need to ensure their Perl scripts use Unix line endings (LF). If a script uses Mac line endings (CR) and the first line is a comment then the Perl interpreter will treat the entire file as one long comment and nothing will happen when the script is executed.

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

 
Perl copyright notice

Golly uses an embedded Perl interpreter to execute scripts. Perl is Copyright (C) 1993-2007, by Larry Wall and others. It is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License".