Running scripts from the command line

Pedigree Forge can be invoked from the command line as a Lua + Gizmos runtime. A single Lua script can define a complete application window — menus, tabs, data-bound widgets and all — and pedigree_forge hosts it the same way it hosts its own main interface. The script runs unchanged on every platform Pedigree Forge builds for.

This is useful for:

Utility tools — calendar converters, format helpers, anything small that doesn’t need the full genealogy application around it.
Custom genealogy apps — workflows that want the Pedigree Forge model, query engine and widget toolkit but present them through a simplified or domain-specific UI of the script author’s own design.
Experimentation — trying out a new panel layout or data view without touching the main program.

The ‘run‘ subcommand

pedigree_forge run <script.lua> [-i <file.ged>] [–raw]

The script path is a required positional argument; the flags can go before or after it and in either short or long form. There are two modes.

Default mode — full ged model

pedigree_forge run C:\path\to\script.lua
pedigree_forge run C:\path\to\script.lua -i C:\path\to\family.ged
pedigree_forge run –input=C:\path\to\family.ged C:\path\to\script.lua

In the default mode the script gets the full Pedigree Forge scripting engine: the ged model, all the controllers, PreQL queries, and every data-bound gizmos widget (<bound_text_field>, <bound_label>, <bound_table>, <bound_detail_grid>, …) wired to live genealogy data.

If -i (or –input) is given, the GEDCOM file is loaded into the model before the script runs. Without -i, the script still gets the full scripting engine but starts with an empty model.

This is the mode to use for anything that touches genealogy data.

Raw mode — bare Lua + Gizmos runtime

pedigree_forge run –raw C:\path\to\script.lua
pedigree_forge run –raw C:\path\to\script.lua – arg1 arg2

In raw mode no genealogy app is instantiated at all. The script gets the Lua runtime and the Gizmos widget system, but no ged model, no controllers, no data-bound widgets. This is the mode to use for general-purpose utility scripts that have nothing to do with genealogy.

Raw mode starts up noticeably faster than the default mode because it skips the genealogy subsystem initialisation.

–raw and -i/–input are mutually exclusive — there is no model to load a GEDCOM into. Combining them is a hard error.

The shape of an "app mode" script

Any Lua script run from the command line is expected to open a top-level application window. The script author declares this by wrapping the layout in <gizmos mode="app"> and using <frame> as the top-level container instead of <dialog>:

xml [[
<gizmos mode="app">
  <frame title="My App" status_bar="true">
    <menu_bar>
      <menu text="File">
        <menu_item id="file_exit" text="Exit"/>
      </menu>
    </menu_bar>
    <vbox expand="both">
      <!– your content here –>
    </vbox>
  </frame>
</gizmos>
]]

function file_exit_action()
    gizmos.close()
end

Key points:

‘mode="app"‘ on the root <gizmos> tag signals that this is an application window, not a dialog.
‘<frame>‘ replaces <dialog> as the top-level container. Frames support title, status_bar="true" and a <menu_bar> child with <menu>/<menu_item>/<menu_check>/<menu_sep> entries.
‘gizmos.show()‘ is called automatically when the script finishes loading, just like for dialogs. You don’t need to call it yourself.
Closing the frame tears down the script and ends the application. Returning a value from gizmos.on_closing() lets you veto the close (return false).

Everything else in Script Gizmos applies as normal — event handlers by naming convention, the Widget() proxy, gizmos.call(), data-bound widgets, and so on.

A worked example — browsing people in a GEDCOM

The following script shows every person in the loaded GEDCOM file using the built-in <bound_detail_grid> widget, which displays one record at a time and lets the user step forward and backward through the query results:

xml [[
<gizmos mode="app">
  <frame title="People Browser" status_bar="true">
    <menu_bar>
      <menu text="File">
        <menu_item id="file_exit" text="Exit"/>
      </menu>
    </menu_bar>
    <vbox expand="both">
      <bound_detail_grid
        query="SELECT surname, given_names, sex, birth.date, birth.place,
               death.date, death.place FROM persons
               ORDER BY surname, given_names"
        expand="both"/>
    </vbox>
  </frame>
</gizmos>
]]

function file_exit_action()
    gizmos.close()
end

Save this as people_browser.lua and run it with:

pedigree_forge run -i C:\path\to\family.ged C:\path\to\people_browser.lua

The whole application — window, menu, status bar, navigable detail view — is those few lines of XML plus one Lua function. The SELECT … FROM persons query is standard PreQL; see the Query Language Reference for the full syntax.

Output and errors

Ordinary script output from print() and any error messages go to standard output and standard error. On Windows the executable is a GUI binary, so there is no console window by default, but std::cout / std::cerr still work and can be captured by redirection (pedigree_forge run … > log.txt 2>&1) or piped into another process.
If the script file does not exist, is a directory, is empty, or contains a Lua syntax error, pedigree_forge exits immediately with a clear error on standard error and the event loop never starts.
If -i points to a GEDCOM that does not exist, the same applies.