Main Help → Writing Extensions → Internal Scripting Modules

GEDitCOM II Modules for Internal Scripting Scripting

GEDitCOM II is installed with a GEDitCOMII.gcscpt and MappingUtilities.gcscpt modules to help in writing Internal Scripts. Some details on using Internal Scripting modules are:

1. The default modules are installed in the /Users/(your name)/Library/Application Support/GEDitCOM II/System/Modules folder. You can also install these or other modules in the /Users/(your name)/Library/Application Support/GEDitCOM II//Modules folder.
2. Modules are made available using the Load command, which looks in the current extension, the user-section "Modules" folder, and the system-section "Modules" folder in that order. The first one found is used.
3. Module methods use Local commands to avoid conflicts with calling code, but some module methods need access to global variables or objects as follows:
   • Internal global variables will use #_var_ where var is some unique name. Calling code should not use similarly-placed underscores in variable names.
   • Object names needed in the module will all end in two underscores (obj__). Calling code should never use object names ending in two underscores.
   • Some module methods assume the automatically-set gcapp object name is still the correct object name for the main Application object.

The following topics explain Internal Scripting module methods. They are grouped by subject.

• Work with Individual Records
• Work with Family Records
• Event and Attribute Methods
• User Interaction Functions
• Date Functions
• Mapping Utilities
• Utility Functions

Work with Individual Records

These methods help access information about individual records.

Sub GetIndividual,gdoc,#prompt

• indi - object name to be assigned to an individual
• gdoc - find individual in this document.
• #prompt - user prompt when selecting from a list.

Set object name indi to the first selected individual record in the provided document. If no individual records are selected, this method looks at the #prompt argument. If #prompt is not an empty string, the user is shown a list of all individuals and can pick one for object name indi. If #prompt is empty or user cancels the selection, the object indi will be set to None. A code snippet is:

GoSub GetIndividual,indi,gdoc,"Pick an Individual"
ifNDef indi
  (code when no individual selected)
  exit
endif
(code working with individual now in object indi)

Work with Family Records

These methods help access information about family records.

Sub GetFamily,fam,gdoc,#prompt

• fam - object name to be assigned to a family
• gdoc - find family in this document.
• #prompt - user prompt when selecting from a list.

Set object name fam to the the first selected family record in the provided document. If no families are selected, this method looks at the #prompt argument. If #prompt is not an empty string, the user is shown a list of all families and can pick one for object name fam. If #prompt is empty or user cancels the selection, the object fam will be set to None. See GetIndividual for a code snippet.

Sub SpouseNames,famrec

• famrec - family record.

This method returns (in #returnValue$) the names of the spouse in the family with first name first, such as "Joseph Smith and Emma Hale". If either spouse is missing, it will be say "Unknown Spouse".

Event and Attribute Methods

These methods help access information about events and attributes.

Sub DescribeDate,event

• event - an event or attribute object by name

This method formats the date for an event or attribute for better inclusion in reports. For single dates it will be "on 4 Jul 1776" for exact dates or "in 1979" for vague dates. For dates with GEDCOM words, it will replace the abbreviations with full lower-case English words. For example "BET 1920 AND 1930" would be changed to "between 1920 and 1930". A code snippet is:

indi.findStructures birts,"BIRT"
if @birts.count>0
  @birt = "birts.0"
  GoSub DescribeDate,birt
  write @indi.alternateName&" was born "&#returnValue$&return
endif

Sub RandomDescribe,event,#noun,#verb,#atAge,#f1,#f2

• event - an event object by name
• #noun - noun for final phrase
• #verb - verb for final phrase
• #atAge - "true" to include age (if available)
• #f1 and #f2 - frequency for output phrase style

This method returns one of three possible complete sentences to describe the provided event. The possibilities are:

noun verb [at age (age)] (date) in (place)
    e.g. Sam Adams died at age 84 on 12 OCT 1856 in Boston, MA, USA
(date) [at age (age)], noun verb in (place)
    e.g. On 12 Oct 1856 at age 84, Sam Adams died in Boston, MA, USA
noun verb in (place) (date) [at age (age)]
    e.g. Sam Adams died in Boston, MA USA on 12 Oct 1856 at age 84

For events, the #noun is usually a person's name or a pronoun ("he" or "she", which will be capitalized if needed). The #verb should be appropriate for the above phrases and the event type. The above examples used #noun="Sam Adams" and #verb="died".
    The phrase will include the age if #atAge is "true" and the event has documented "Age" field. The #f1 and #f2 parameters determine the probability of each phrase. Phrase 1 and phrase 2 are picked with probabilities #f1 and #f2. Phrase 3 is picked with probability 1-#f1-#f2.

Sub RandomDescribeAttr,attr,#noun,#verb,#atAge,#f1,#f2

• attr - an attribute object by name
• #noun - noun for final phrase
• #verb - verb for final phrase
• #atAge - "true" to include age (if available)
• #f1 and #f2 - frequency for output phrase style

This method is similar to RandomDescribe except that it appends the contents of the attribute line to the #verb. This method returns one of three possible complete sentences to describe the provided attribute. The possibilities are:

noun verb (value) [at age (age)] (date) in (place)
    e.g. His occupation was as a brewer at age 84 on 12 OCT 1856 in Boston, MA, USA
(date) [at age (age)], noun verb (value) in (place)
    e.g. On 12 Oct 1856 at age 84, his occupation was as a brewer in Boston, MA, USA
noun verb (value) in (place) (date) [at age (age)]
    e.g. His occupation was as a brewer in Boston, MA USA on 12 Oct 1856 at age 84

For attributes, the #noun is usually a possessive version of a person's name or a possessive pronoun ("his" or "her", which will be capitalized if needed). The #verb should be appropriate for the above phrases and the attribute type. The above examples used #noun="his", #verb="occupation was as a", and the attribute value was "brewer" (note that if attribute content starts with an article, any article at the end of #verb will be removed).
    The phrase will include the age if #atAge is "true" and the attribute has documented "Age" field. The #f1 and #f2 parameters determine the probability of each phrase. Phrase 1 and phrase 2 are picked with probabilities #f1 and #f2. Phrase 3 is picked with probability 1-#f1-#f2.

User Interaction Functions

These methods make it easier to get input from the user or to provide user feedback.

Sub Alert,#message,#extra

• #message - main text for the alert
• #extra - extra text to display in smaller font

Displays an alert window to the user with the main text in bold and the optional extra text in a smaller font. The window has a single "OK" button to close the window.

Sub GetInteger,#min,#max,#title,#prompt,#init

• #imin to #imax - acceptable range for the entered number
• #title - window title
• #prompt - prompt to user
• #init - initial number in the editing field

Displays a window with a single editing field for the user to enter an integer. The entered number must satisfy #imin<=(number)<=#imax (either limit can be ignored by passing an empty string). If the number is not within that range, the user is notified and asked to try again. The entered integer is returned in #returnValue$ (which will be undefined if entry process was canceled). If the user enters a floating point number within the required range, it will be truncated to an integer when returned.

Sub InitProgress,#stepSize
Sub ShowProgress,#fractionDone

• #stepSize - fraction increment before user is notified of script progress
• #fractionDon - the current fraction of the script that is done

These two methods help provide feedback to users about progress of the current script. Adding these options to a script is desirable if the script might take a while to finish. A code snippet is:

GoSub InitProgress,0.01
Repeat "#i",1,#maxNum
  (do scripting calculations)
  GoSub ShowProgress,#i/#maxNum
EndRepeat

In brief, call InitProgress in the beginning to define how often progress information is updated (a fraction from 0 to 1). Then, periodically call ShowProgress with current fraction done. If needed, the update fraction will be displayed to the user. Note that if you omit the InitProgress call, the default #stepSize will be set to 0.01 (display progress after each 1% of completion).

Date Functions

This methods help processing of date information.

Sub GetGedWord.#key

• #key - a GEDCOM date word

Returns (in #returnValue$) a defined replacement string for a GEDCOM key word. These are usually key words used in GEDCOM dates. For example, it returns "about" for key "ABT", "between" for key "BET", etc.. If #key is not a valid GEDCOM date word, it returns #key unchanged.

Mapping Utilities

These functions are for help working creating maps in reports. They are in the MappingUtilities.gcscpt module.

Sub createJSMap,#height,bbrect,#mapPOIs,mapBBName,#clickLatLon

• #height - height of map element in pixels
• bbrect - name of list object with elements = [S, W, N, E] for bounding box.
      (Enter using signed latitudes for S and N and longitudes for W and E).
• #mapPOIs - java script code with all markers in one string
• mapBBName - name of list object with [stroke color, opacity, fill color, opacity] for map bounding box (or "None" to omit)
• #clickLatLon - "true" to add option to click on map to display lat,lon below the map

Creates java script code to include in html content for a report displaying maps. The code will be for google maps or OpenLayers map depending on the users' current mapping API setting in the GEDitCOM II settings. The #mapPOIs parameter can add markers to the map. These are typically created by building a list of marker locations using MaxMapPOI. The mapBBName parameter optionally draws a bounding box around the provided bbrect (it is only used for google maps API). A code snippet is:

CreateScriptOutput rpt,"My Mapping Report","html"
   ...(get map features in objects and variables)
GoSub createJSMap,#mheight,brect,#poiStr,None,"true"
GetObject JSMap,#returnValue$
rpt.css @JSMap.0
rpt.head @JSMap.1
   ...(optionally add html elements to be above the map)
rpt.out @JSMap.2
   ...(optionally add html elements to be below the map)
rpt.write gdoc

Sub MakeMapPOI,#lat,#lon,#num,#poiname,#details

• #lat,#lon - latitude and longitude for the marker
• #num - a unique number within the map for this marker
• #poiname - text to appear on hover over the marker
• #details - html content to appear if one clicks on the POI

Creates java script code to add a marker to either a google maps or OpenLayers map at given location. The #lat,#lon location uses signed numbers, which are typically found using with either lonLatBounds property of a Place Record or eventLonLatBounds property of a GEDCOM Structure. If #details is provided it is surrounded by <p>...</p> block to create a paragraph element in the marker. A code snippet is:

CreateList pois
GoSub MakeMapPOI,#lat,#lon,#num,#label,#det
pois.addString #returnValue$
...(add any number of additional markers)
pois.join "#mapPOIs"

When done, pass #mapPOIs to createJSMap when creating map code.

Utility Functions

These methods provide various utility functions for scripts.

Sub Cardinal,#anum

• #anum - an integer

For numbers 0 to 10, it returns (in #returnValue$) the number as a word, such as "zero", "one", "two", etc.; for all other numbers it returns the input number.

Sub RomanNumeral,#number

• #number - a number

For integers 1 to 4999, it returns (in #returnValue$) Roman numeral version of the number (using upper case letters); for all other numbers it returns the input number.

Sub CapitalOne,#target

• #target - a string to be capitalized

Returns (in #returnValue$) the input string capitalized by converting the first character to upper case. The rest of the string is unaltered.

Sub WaitForWindow,#prevID,#maxTime

• #prevID - ID of previous front window
• #maxTime - maximum time to wait for new window to open (in seconds)

Sometimes you need be sure a report window is done displaying before the script can continue. For example, you cannot resize a window until it has opened. Another challenge is the way windows are opened varies in different MacOS versions. This methods provides a MacOS-independent method of waiting for a new window to open. Here is a code snippet:

@winds = "gcapp.windows"
#prevID=@winds.0.id
! (Code to open new report window)
GoSub WaitForWindow,#prevID,2
! (Code that relies on window being now opened)

Before creating a new window, fetch the ID of the current front window. Then after creating the new window, call this method to wait for it to open (it waits until the ID for the front window is no longer #prevID). The #maxTime provides fail-safe exit in case the new window never opens.