  Installing Perl
  Example scripts
  Golly's scripting commands
  Cell arrays
  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. Windows and Linux users need to have Perl 5.10 or later. If you are using Linux then you might already have Perl 5.10 installed; if not, visit www.perl.org and download a suitable installer. Windows users are advised to download the ActivePerl installer. Note that the current binary distributions of Golly are 32-bit builds, so they require a 32-bit version of Perl. If you've built a 64-bit Golly from source then it will require a 64-bit version of Perl.

On Windows and Linux, the Perl library is loaded at runtime (the first time you try to run a .pl script). Golly initially attempts to load a particular version of the Perl library: perl510.dll on Windows or libperl.so.5.10 on Linux. The numbers correspond to Perl version 5.10.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
  make-torus.pl |  | — makes a toroidal universe from 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

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.pl in the same directory as the Golly application and then in a user-specific data directory (see the g_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 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_autoupdate
  g_check
  g_clear
  g_clone
  g_copy
  g_cut
  g_dellayer
  g_doevent
  g_duplicate
  g_empty
  g_error
  g_evolve
  g_exit
  g_fit
  g_fitsel
  g_flip
  g_getalgo
  g_getbase
  g_getcell
  g_getcells
  g_getclip

  g_getclipstr
  g_getcolor
  g_getcolors
  g_getcursor
  g_getdir
  g_getevent
  g_getgen
  g_getheight
  g_getlayer
  g_getmag
  g_getname
  g_getoption
  g_getpop
  g_getpos
  g_getrect
  g_getrule
  g_getselrect
  g_getstep
  g_getstring
  g_getwidth
  g_getxy
  g_hash
  g_help

  g_join
  g_load
  g_maxlayers
  g_movelayer
  g_new
  g_note
  g_numalgos
  g_numlayers
  g_numstates
  g_open
  g_opendialog
  g_parse
  g_paste
  g_putcells
  g_randfill
  g_reset
  g_rotate
  g_run
  g_save
  g_savedialog
  g_select
  g_setalgo
  g_setbase

  g_setcell
  g_setclipstr
  g_setcolor
  g_setcolors
  g_setcursor
  g_setdir
  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 file and process it according to its type:

  - A HTML file (.htm or .html extension) is displayed in the help window.
  - A text file (.txt or .doc extension, or a name containing "readme") is opened in your text editor.
  - A script file (.pl or .py extension) is executed.
  - A zip file (.zip extension) is processed as described here.
  - Any other type of file is assumed to be a pattern file and is loaded into the current layer.

  A non-absolute path is relative to the location of the script. The 2nd parameter is optional (default = 0) and specifies if the given pattern or zip file should be remembered in the Open Recent submenu, or in the Run Recent submenu if the file is a script.
  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" |  | run length encoded (RLE)
  "rle.gz" |  | compressed RLE
  "mc" |  | macrocell
  "mc.gz" |  | compressed macrocell

  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_opendialog($title, $filetypes, $initialdir, $initialfname, $mustexist=1)
  Present a standard Open dialog to the user and return the chosen path in a string. All parameters are optional; the default is an Open dialog showing the current directory, with a title of "Choose a file" and a file type of "All files (*)|*". If the 5th parameter (default = 1) is set to 0, the user can specify a new filename instead of choosing an existing file. If the given file type is "dir" then the dialog lets the user choose a directory rather than a file. If the user cancels the dialog, the return value will be an empty string.
  Example: my $fname = g_opendialog('Open MCell File', 'MCell files (*.mcl)|*.mcl', 'C:\\Temp', 'sample.mcl');
  Example: my $dirname = g_opendialog('Choose a folder', 'dir');

g_savedialog($title, $filetypes, $initialdir, $initialfname, $suppressprompt=0)
  Present a standard Save dialog to the user and return the chosen path in a string. All parameters are optional; the default is a Save dialog showing the current directory, with a title of "Choose a save location and filename" and a file type of "All files (*)|*". If a file already exists at the chosen location, an Overwrite? query will be displayed unless the 5th parameter (default = 0) is set to 1. If the user cancels the dialog, the return value will be an empty string.
  Example: my $fname = g_savedialog('Save text file', 'Text files (*.txt;*.csv)|*.txt;*.csv', 'C:\\Temp', 'Params.txt', 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_getdir(dirname)
  Return the path of the specified directory:

  "app" — the directory containing the Golly application.

  "data" — the user-specific data directory:

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

  "temp" — the directory Golly uses to store various temporary files. All these files are deleted when Golly quits.

  "rules" — the user-specific rules directory set in Preferences > Control.

  "patterns" — the directory displayed by File > Show Patterns.

  "scripts" — the directory displayed by File > Show Scripts.

  "download" — the directory Golly uses to store downloaded files.

  In each case a full path is returned, terminated by the appropriate path separator for the current platform.
  Example: g_open(g_getdir("app")."Patterns/Life/Breeders/breeder.lif");

g_setdir(dirname, dirpath)
  Set the specified directory to the given path (which must be a full path to an existing directory). All the directory names listed above are allowed, except for "app", "data" and "temp".
  Example: g_setdir("patterns", "/path/to/my-patterns/");

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 ("and", "copy", "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_join($cellarray1, $cellarray2)
  Join the given cell arrays and return a reference to the resulting cell array. If the given arrays are both one-state then the result is one-state. If at least one of the given arrays is multi-state then the result is multi-state, but with one exception: if both arrays have no cells then the result is an empty one-state array. See below for a description of one-state and multi-state cell arrays.
  Example: $result = g_join($part1, $part2);

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 ("and", "copy", "not", "or", "xor").
  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). If the clipboard data is multi-state but all cell states happen to be zero then the returned cell array is (wd,ht) rather than (wd,ht,0).
  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($string)
  Set the current cursor according to the given string and return the old cursor string. The given string must match one of the names in the Cursor Mode menu.
  Example: $oldcurs = g_setcursor("Draw");

g_getcursor()
  Return the current cursor as a string (ie. the ticked name in the Cursor Mode menu).

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)
  Temporarily set the current step exponent to the given integer. A negative exponent sets the step size to 1 and also sets a delay between each step, but that delay is ignored by the g_run and g_step commands. Golly will reset the step exponent to 0 upon creating a new pattern, loading a pattern file, or switching to a different algorithm.
  Example: g_setstep(0);

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

g_setbase($base)
  Temporarily set the current base step to an integer from 2 to 10000. Golly will restore the default base step (set in Preferences > Control) upon creating a new pattern, loading a pattern file, or switching to a different algorithm.
  Example: g_setbase(2);

g_getbase()
  Return the current base step.

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 algorithm, rule, scale, location and step exponent 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_numstates()
  Return the number of cell states in the current universe. This will be a number from 2 to 256, depending on the current algorithm and rule.
  Example: $maxstate = g_numstates() - 1;

g_numalgos()
  Return the number of algorithms (ie. the number of items in the Set Algorithm menu).
  Example: $maxalgo = g_numalgos() - 1;

g_setalgo($string)
  Set the current algorithm according to the given string which must match one of the names in the Set Algorithm menu.
  Example: g_setalgo("HashLife");

g_getalgo($index=current)
  Return the algorithm name at the given index in the Set Algorithm menu, or the current algorithm's name if no index is supplied.
  Example: $lastalgo = g_getalgo( g_numalgos() - 1 );

g_setrule($string)
  Set the current rule according to the given string. If the current algorithm doesn't support the specified rule then Golly will automatically switch to the first algorithm that does support the rule. If no such algorithm can be found then you'll get an error message and the script will be aborted.
  Example: g_setrule("b3/s23");

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

g_getwidth()
  Return the width of the current universe (0 if unbounded).
  Example: $wd = g_getwidth();

g_getheight()
  Return the height of the current universe (0 if unbounded).
  Example: $ht = g_getheight();

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";

g_setcolors($colorarray)
  Set the color(s) of one or more states in the current layer and its clones (if any). If the given array contains a multiple of 4 integers then they are interpreted as state, red, green, blue values. A state value of -1 can be used to set all live states to the same color (state 0 is not changed). If the given array contains exactly 6 integers then they are interpreted as a color gradient from r1, g1, b1 to r2, g2, b2 for all the live states (state 0 is not changed). If the given array is empty then all states (including state 0) are reset to their default colors, depending on the current algorithm and rule. Note that the color changes made by this command are only temporary. Golly will restore the default colors if a new pattern is opened or created, or if the algorithm or rule changes, or if Preferences > Color is used to change any of the default colors/icons for the current layer's algorithm.

  Example: g_setcolors([1,0,0,0, 2,0,0,0]); |  | # set states 1 and 2 to black
  Example: g_setcolors([-1,0,255,0]); |  | # set all live states to green
  Example: g_setcolors([255,0,0, 0,0,255]); |  | # live states vary from red to blue
  Example: g_setcolors([]); |  | # restore default colors

g_getcolors(state=-1)
  Return the color of a given state in the current layer as a reference to an array of the form

  ( state, red, green, blue )

  or if the given state is -1 (or not supplied) then return all colors as

  ( 0, r0, g0, b0, . . . N, rN, gN, bN )

  where N equals g_numstates() - 1. Note that the array reference returned by g_getcolors can be passed into g_setcolors; this makes it easy to save and restore colors.
  Example: $allcolors = g_getcolors();
  Example: $deadcolor = g_getcolors(0);

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)
  "drawingstate" |  | 0 to g_numstates()-1
  "fullscreen" |  | 1 or 0
  "hyperspeed" |  | 1 or 0
  "maxdelay" |  | 0 to 5000 (millisecs)
  "mindelay" |  | 0 to 5000 (millisecs)
  "opacity" |  | 1 to 100 (percent)
  "restoreview" |  | 1 or 0
  "savexrle" |  | 1 or 0
  "showallstates" |  | 1 or 0
  "showboldlines" |  | 1 or 0
  "showeditbar" |  | 1 or 0
  "showexact" |  | 1 or 0
  "showgrid" |  | 1 or 0
  "showhashinfo" |  | 1 or 0
  "showicons" |  | 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: $oldgrid = g_setoption("showgrid", 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_fit() if g_getoption("autofit");

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:

  "border" |  | color for border around bounded grid
  "paste" |  | color for pasting patterns
  "select" |  | color for selections (will be 50% transparent)
  algoname |  | status bar background for given algorithm

  Example: @oldrgb = g_setcolor("HashLife", 255, 255, 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("select");

g_getclipstr()
  Return the current contents of the clipboard as an unmodified string.
  Example: $illegalRLE = g_getclipstr();

g_setclipstr($string)
  Copy an arbitrary string (not necessarily a cell pattern) directly to the clipboard.
  Example: g_setclipstr($correctedRLE);

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_getevent($get=1)
  When Golly runs a script it initially handles all keyboard and mouse events, but if the script calls g_getevent() then future events are put into a queue for retrieval via later calls. These events are returned in the form of strings (see below for the syntax). If there are no events in the queue then the returned string is empty. Note that the very first g_getevent() call will always return an empty string, but this isn't likely to be a problem because it normally occurs very soon after the script starts running. A script can call g_getevent(0) if it wants Golly to resume handling any further events.

  Keyboard events are strings of the form "key charname modifiers" where charname can be any displayable ASCII character from '!' to '~' or one of the following names: space, home, end, pageup, pagedown, help, insert, delete, tab, enter, return, left, right, up, down, or f1 to f24. If no modifier key was pressed then modifiers is none, otherwise it is some combination of alt, cmd, ctrl, meta, shift. Note that cmd corresponds to the command key on a Mac and the control key on Windows/Linux (this lets you write portable scripts that work on any platform). The alt modifier corresponds to the option key on a Mac.

  Mouse events are strings of the form "click x y button modifiers" where x and y are integers giving the cell position of the click, button is one of left, middle or right, and modifiers is the same as above. The following examples show the strings returned after various user events:

  "key m none" |  | user pressed M key
  "key space shift" |  | user pressed space bar and shift key
  "key , altctrlshift" |  | user pressed comma and 3 modifier keys
  "click 100 20 left none" |  | user clicked cell at 100,20 with left button
  "click -10 9 middle alt" |  | user clicked cell with middle button and pressed alt key
  "click 0 1 right altshift" |  | user clicked cell with right button and pressed 2 modifiers

  Example: $evt = g_getevent();

g_doevent($string)
  Pass the given event to Golly to handle in the usual manner (but events that can change the current pattern will be ignored). The given event must be a string with the exact same format as returned by the g_getevent command (see above). If the string is empty then Golly does nothing.
  Example: g_doevent("key q cmd"); # quit Golly

g_getxy()
  Return the mouse's current grid position as a string. The string is empty if the mouse is outside the viewport or outside a bounded grid or over the translucent buttons, otherwise the string contains x and y cell coordinates separated by a space; eg. "-999 12345".
  Example: $mousepos = g_getxy();

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

Some scripting commands manipulate patterns in the form of cell arrays. Golly supports two types of cell arrays: one-state and multi-state. A one-state cell array 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:

  ( x1, y1, . . . xN, yN )

A multi-state cell array 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 array to ensure the total number of integers is odd:

  ( x1, y1, state1, . . . xN, yN, stateN ) if N is odd
  ( x1, y1, state1, . . . xN, yN, stateN, 0 ) if N is even

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

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

One-state cell arrays 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 array can be used in a two-state universe, but only if the array's cell states are 0 or 1.

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

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

Rectangle 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_doevent("") to allow the script to be aborted in a timely manner.

3. When writing a script that creates a pattern, make sure the script starts with a g_new command (or, less useful, a g_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 g_new or g_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 g_new or g_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 g_run calls) are stored in temporary files, while other changes are stored in memory.

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".