Scripting API ReferenceScripting API Reference
This page is the complete reference for functions and methods available to Lua scripts in Pedigree Forge. For an introduction to scripting, see Scripts.
Global functions
| Function | Description |
|---|
| alert(message) | Display a message dialog |
| root_person() | The currently selected person |
| find_person(id) | Person by ID (e.g. "I1") |
| find_family(id) | Family by ID (e.g. "F1") |
| find_source(id) | Source by ID |
| find_archive(id) | Archive by ID |
| everyone() | Iterator over all persons |
Person properties
| Method | Description |
|---|
| name() | Full formatted name |
| given_names() | Given names |
| first_given_name() | First given name only |
| surname() | Surname |
| nickname() | Nickname |
| sex() | Sex |
| trade() / occupation() | Occupation |
| id() | Record ID |
| is_null() / is_not_null() | Validity check |
Person relationships
| Method | Returns |
|---|
| father() | Father (person) |
| mother() | Mother (person) |
| spouse(index) | Spouse by index (0-based) |
| family_as_spouse(index) | Family where person is a spouse |
| family_as_child(index) | Family where person is a child |
| families_as_spouse_count | Number of spouse families |
| families_as_child_count | Number of child families |
Person facts
| Method | Returns |
|---|
| born() | Birth fact |
| baptised() | Baptism fact |
| died() | Death fact |
| buried() | Burial fact |
| probate() | Probate fact |
| life_dates() | Formatted life dates string |
| date_of_birth() | Date of birth |
| date_of_death() | Date of death |
Family properties
| Method | Description |
|---|
| id() | Family ID |
| husband() | Husband/partner 1 (person) |
| wife() | Wife/partner 2 (person) |
| married() | Marriage fact |
| child_count() | Number of children |
| child(index) | Child by index (0-based) |
Source and archive properties
| Method | Description |
|---|
| id() | Record ID |
| title() | Source title |
| name() | Archive name |
| is_null() / is_not_null() | Validity check |
Fact properties
| Method | Returns |
|---|
| date() | Date string |
| place() | Place name |
| address() | Address |
Data expressions
Scripts can also access data through the data expression system using pf.get and pf.set:
| Function | Description |
|---|
| pf.get(id, expr) | Read a value (e.g. pf.get("I1", "person.birth.date")) |
| pf.set(id, expr, value) | Write a value |
| pf.query(query_text [, params]) | Run a query, returns a table of result rows. Optional params table supplies values for @parameter placeholders (e.g. pf.query("SELECT * FROM persons WHERE surname = @name", { name = "Smith" })) |
Tools API
The tools API gives scripts access to the same operations available through MCP tool calls. Use tools.call() to invoke a tool and receive its result.
| Function | Description |
|---|
| tools.call(name, args) | Call a tool by name with a table of arguments |
| tools.list() | List all available tools |
| tools.is_write(name) | Check whether a tool modifies data |
Commonly used tools:
| Tool name | Description |
|---|
| get_current_person | Get the currently selected person |
| search_people | Search for people matching criteria |
| get_person_details | Get full details for a person |
| get_family_details | Get full details for a family |
| add_person | Add a new person |
| update_person | Update person fields |
| add_fact | Add a fact to a person |
| add_family | Create a family record |
| search_sources | Search for sources |
| get_source_details | Get source details |
Document API (report scripts)
Report scripts receive a doc object with the following methods:
Document structure
| Method | Description |
|---|
| chapter(text) | Start a new chapter |
| heading_1(text) | Level 1 heading |
| heading_2(text) | Level 2 heading |
| heading_3(text) | Level 3 heading |
| paragraph() | Start a paragraph (returns a span) |
| ordered_list() | Start an ordered list |
| unordered_list() | Start an unordered list |
| table() | Create a table |
| block_quote() | Start a block quote |
| table_of_contents() | Insert a table of contents |
| index() | Insert an index |
Span formatting
The span object returned by paragraph(), block_quote(), and list items supports:
| Method | Description |
|---|
| append(text) | Append text |
| bold(bool) | Toggle bold |
| italic(bool) | Toggle italic |
| underline(bool) | Toggle underline |
| strike(bool) | Toggle strikethrough |
| superscript(bool) | Toggle superscript |
| subscript(bool) | Toggle subscript |
| footnote(text) | Insert a footnote |
| hyperlink(url, text) | Insert a hyperlink |
| index_term(value) | Add an index entry |
| new_line() | Line break |
| reset() | Clear all formatting |
Query API (query scripts)
Query scripts receive a query object:
| Method | Description |
|---|
| add_column(heading, width, right_align) | Define a column (right_align is optional, defaults to false) |
| add_row() | Add a result row (returns a row object) |
| set_id_column(index) | Mark a column as containing record IDs for navigation |
Row objects have a single method: cell(text) to append a cell value.