Scripts

Pedigree Forge supports scripting via the Lua programming language, giving you the ability to automate tasks, generate custom reports, and create specialised queries that go beyond the built-in features.

Scripts are accessed from Tools > Scripts. New scripts can be added by placing .lua files in your scripts directory and selecting Tools > Refresh Scripts.

Where to put scripts

Pedigree Forge looks for scripts in two directories, in order:

1. Bundled scripts — the scripts folder alongside the application executable. These are shipped with Pedigree Forge.
2. User scripts — %APPDATA%\Pedigree Forge\scripts on Windows (or ~/Library/Application Support/Pedigree Forge/scripts on macOS). Place your own scripts here.

If both directories contain a script with the same filename, the bundled version takes priority. Use distinct filenames for your own scripts to avoid conflicts.

Script types

There are three types of script, indicated by an annotation at the top of the file:

• @tool — appears in the Tools > Scripts menu.
• @report — appears in the Report panel’s item drop-down for generating custom narrative content.
• @query — appears in the Queries panel’s drop-down for producing tabular results.

Script annotations

Scripts are configured using annotations in a block comment at the top of the file:

–[[
@tool
@name Count Children
]]

Writing a tool script

A tool script runs when selected from the Tools > Scripts menu. It can read information about people, families, and sources, and display results with alert():

–[[
@tool
@name List Children
]]

local person = root_person()
if person:is_null() then
    alert("No person selected")
    return
end

local msg = person:name() .. " has children:\n"
local fam = person:family_as_spouse()
if fam:is_not_null() then
    for i = 0, fam:child_count() - 1 do
        local child = fam:child(i)
        msg = msg .. "  " .. child:name() .. "\n"
    end
end
alert(msg)

Writing a report script

Report scripts appear in the Report panel’s item drop-down. They receive a doc parameter for building formatted output — headings, paragraphs with inline formatting, tables, lists, and footnotes:

–[[
@report
@name Custom Report
]]

doc:chapter("My Report")
local p = doc:paragraph()
p:bold(true)
p:append("Introduction")
p:bold(false)
p:append(" — This is a custom report.")

Writing a query script

Query scripts appear in the Queries panel drop-down (prefixed with "Script:"). They receive a query parameter for building tabular results:

–[[
@query
@name People Without Death Dates
]]

query:add_column("Name", 200)
query:add_column("Born", 100)

for person in everyone() do
    if person:date_of_death() == "" and person:date_of_birth() ~= "" then
        local row = query:add_row()
        row:cell(person:name())
        row:cell(person:date_of_birth())
    end
end

Use set_id_column(index) to mark a column as containing record IDs, enabling double-click navigation from the results.

Data expressions

In addition to the record object API, scripts can read and write data using data expressions — a dot-notation path syntax shared with the query language and gizmo widgets:

pf.get("I1", "person.birth.date")          – "12 Feb 1809"
pf.get("I1", "person.father.surname")      – "Darwin"
pf.set("I1", "person.trade", "Naturalist")

Script dialogs (gizmos)

Scripts can create interactive dialog windows using an XML layout. See Script Gizmos for an introduction and Gizmos Widget Reference for the full widget catalogue.

Script libraries

If your scripts directory contains a libs/ subdirectory, it is automatically added to Lua’s package.path, allowing you to organise shared code into reusable modules loaded with require.

Lua version

Scripts have access to the standard Lua 5.4 libraries: base, io, math, table, package, and string.

API reference

For the complete function and method listings, see the Scripting API Reference.