Lifelines Emulation in GEDitCOM II and GEDitCOM using Internal Scripts

Introduction

Internal Scripting emulation of the Lifelines scripting language was done by developing a Lifelines.gcscpt module (included in this extension) that allows many Lifelines commands to work the same way in converted Internal Scripts. The Lifelines emulator was written to minimize the number of changes required to convert a Lifelines script to a Internal Script. Nevertheless, syntax differences between Lifelines scripting language and the Internal Scripting langauge mean that 100% emulation was not possible. The documentation below explains the steps needed to reconcile those difference to translate a Lifelines script into a Internal Script.

This extension comes with translations of selected Lifelines scripts and they appear in the "Scripts" section. The "Text Files" section has all Lifelines scripts as provided with a download using original names but with file's extension changed from "ll" to "txt". An underscore was inserted into the name of any script that has been translated. You can compare the Internal Scripting version to the original to see the translation process in action. The details below can enable translation of more scripts into Internal Scripts.

Documentation details aree:

• Getting Started - Prelimiary tasks to translating a script.
• Converting Lifelines Scripts
• Conversion Tasks - Summary of key conversion tasks.
• Lifelines Emulation Reference - listing of how to convert all Lifelines scripting options into Internal Scripting methods.
• PDF copy of the Lifelines manual including its scripting language (control-click and choose "Back" from popup menu to return to this help).
• Extension Help - Return to the entry page for this extension's help.

Getting Started

Imagine you want to convert another Lifelines script originally called script.ll for use in the . The process starts with the following steps:

1. Open the "LifelinesIS" extension in GEDitCOM Editor.
2. Use the "New Script..." (or "S" icon in the tool bar) and create a script called newscript.gcscpt (i.e. pick any name and use Internal Scripting extension gcscpt).
3. Expand the "Text Files" section and locate the original version, which will be called script.txt (i.e., extension "txt" instead of "ll"). Click on that file, copy all the text, and paste into the new newscript.gcscpt.
4. To allow your new translation to be selected when running this extension, click on "menu choices" in the extension's "Properties." Click the "+" icon and set the key to newscript.gcscpt and the value to short text description of the script. Repeat for "menu choices SD" to make the script available in GEDitCOM too.
5. When translation is finished, the follow steps make it official in this extension:
   • Document the new translation in the "help.html" file by adding it to the list of available scripts in this extension (and provide brief description).
   • Add an underscore in front of script.txt in the "Text Files" section to indicate translation is done.

Once the above steps are completed, you are ready to start translating and testing. The process is explained in the next section. Note that developing Internals Script is best done by using GEDitCOM II and GEDitCOM Editor. Although you can develop Internal Scripts using GEDitCOM, the workflow is different and cumbersome. See the GEDitCOM Editor for workflow details.

Note the goal of this Lifelines emulator was to reproduce the language as much as possible. It was not written to maximize efficiency. If you find a converted Lifelines script to be useful, a logical next step would be to convert the logic of the script into a native Internal Script. The goal would be a script that can run without using the lifeline.gcscpt module.

Converting Lifelines Scripts

The remainder of this document gives details on converting Lifelines scripts to Internal Scripts for using the Lifelines.gcscpt module. The documentation sections are:

• Conversion Tasks
• Lifelines Emulation Reference
• PDF copy of the Lifelines manual including its scripting language (control-click and choose "Back" from popup menu to return to this help).

For ideas on more scripts to convert, you can refer to the original Lifelines scripts provided in the "Text Files" section of this extension. An on-line tutorial gives a specific example of converting a Lifelines script to the Internal Script.

Conversion Tasks

The section summarizes the process for converting a Lifelines script into an emulated Internal Script. Specific details on some conversion tasks are in the Lifelines Emulation Reference section. The conversion always starts with reorganizing high-level structures are follows:

1. For the one main method, move it all to the end of the Internal Script, remove the proc main, remove its brackets ({}), and adjust indents (or automatically adjust indents later using GEDitCOM Editor's "Indent Commands" menu command, which works best when translation is farther along).
2. Just before the main commands insert module initializer with the a name for the script:

   ll_init("name of script")

3. To get the final results displayed in a window, put finish() command at the end of the main commands.
4. Insert command to load the Lifelines.gcscpt module. It must be at the beginning of the script before any other commands.

   load Lifelines

5. Change all Lifelines comments (/* a comment ... */) to Internal Scripting comments (! a comment ...) and an ! is needed on each line in mutliple line Lifelines comments. Some Lifelines scripts have long comments in the beginning and sometimes at the end with sample output. These sections can be deleted (they are always in the original file if needed).

Any Lifelines script converted to using these taks should now look like:

! Header comments (if retained)

! load module
Load Lifelines

! Subroutines
(original proc's and func's) 

! Preamble
ll_init("My translated script")

! Translated script
(original proc main statements)

! Final Output
finish()

! Final commands (if retained)

The rest of the convertion process deals with syntax and logic of the script. The following items list key tasks with links for more details in the Lifelines Emulation Reference section.

• If this is your first translation, read about Value Types in Internal Scripts especially to meaning of "variables" and "objects" in Internal Scripts.
• Change all Lifelines proc and func methods (which should now be at the beginning of the script after moving proc main as described above) to InternalScript sub methods:

  proc name ( params ) { statements }

  func name ( params ) { statements return(result) }

  to

  sub name params: statements return result endsub

  Note that the params in the sub definition are delimited by commas or spaces and not group withi parentheses. Besides this syntax change, various subroutine concepts may need more translation as explained below.
• Change set commands for variables to pass the first variable by reference. In Internal Scripts, "passing by reference" means to quote that variable, which effective sends the variable name to the subrouting rather than its current value. Change set commands for objects to setobj commands (the first parameter need not be quoted, although works it if is). The second parameter might need to change too. See below for details and other requirements for translating set commands.
• Change all conditionals from Lifelines syntax to Internal Scripting syntax:

  if ([varb,] expr) { statements } elsif ([varb], expr) { statements } else { statements }

  to

  if expr statements else if expr statements else statements endif

  Notice that Internal Scripts cannot assign a variable and check an expression in the same line. Therefore Lifelines scripts that use the optional [varb,] above will need to assign that variable before the conditional.
      A Internal Script command "if variable" will be true unless variable is 0 or an empty string, but will cause an error if variable is undefined. To check for an undefined variable, use "ifdef variable" or "ifndef variable" instead.
      An Internal Script command "if object" does not work for objects (instead of an error, it will interpret object name as a string and allows be true, i.e., a non-empty string). To check if an object exists, change conditional to "ifdef object" (true if object found) or "ifndef object" (true if object not found). For example, a Lifelines line to assign and check for birth event must be split to to two lines — assign then check using an ifdef command:

  if (e, birth(indi)) ...

  to

  birth(indi,e) ifdef e ...

      Single-line conditionals in Lifelines are changed as follows:

  if ([varb,] expr) { statement }

  to

  if expr then statement

      Finally, the conditional expression can use most (but not all) defined logicals or it can switch to the more-flexible conditional options of Internals Script (see GEDitCOM Editor help for those options)
• Lifelines scripts usually add text to reports. These lines translate easily by methods slightly different for line mode than for page mode. See each one for details. For most lines it is simply a matter of concatenating adjacent text blocks with ampersands ("&") and then inserting out or cout at the start of line depending on whether the line starts with text or with col(n) to pick a column number.
• Besides multiple text blocks to output text to reports, some Lifelines scripts mix other commands on a single line. When needed, break such lines into one command per line for the Internal Script.
• Change while loops from Lifelines syntax to Internal Scripting repeat loops:

  while ([varb,] expr) { statements }

  to

  repeat if notexpr then break statements endrepeat

  The notxpr exits the loop when the expr in the Lifelines command is not true. Notice that Internal Scripts cannot assign a variable and check an expression in the same line. Therefore Lifelines scripts that use the optional [varb,] above will need to initialize that variable before the loop starts.
• Lifelines provides many functions for iterating over objects. These need to change as documented below for each one. The Lifelines iterators are forindi(), forindiset(), children(), spouses(), families(), forfam(). Copy the Internal Scripting version from this document, paste into script being translated, and then change variable names to those used in the original script.

With luck, the conversion will be complete. Try running in and see what happens. The most likely errors are Internal Scripting syntax errors. Each time you run, the script will stop at the first error and print a brief (sometimes vague) reason. The error message will also indicate line in the script. Use "Go To Line..." menu command in GEDitCOM Editor to find that line. An error that says "In loaded subroutines" means the error was in the Lifelines.gcscpt module. It usually means you passed an invalid parameter to an module method.

Lifelines Emulation Reference

The following sections list all methods from the Lifelines manual, which is available in this extension in pdf form (control click and use "Back" to return to this documentation) or in a on-line translation). This reference does not define the behavior of the Lifelines functions (you can refer to the Lifelines documentation for that information). Instead, this reference lists all Lifelines methods, whether or not they are implemented, and whether or not they are identical or require some modification. Fully supported methods are in black; methods needing modification are in green, and methods not implemented are in red. The subsections are:

• Value Types
• Expressions
• Statements
• Subroutines and Functions
• Arithmetic and Logic Functions
• Person Functions
• Family Functions
• List Functions
• Table Functions
• GEDCOM Node Functions
• Event and Date Functions
• Value Extraction Functions
• User Interaction Functions
• String Functions
• Output Mode Functions
• Person Set Functions and GEDCOM Extraction
• Record Update Functions
• Record Linking Functions
• Miscellaneous Functions

Value Types

Lifelines defines several types of values and any one can be assigned to a variable name. Internal Scripting has "variables" and "objects." Variables are anything that can be represented by a number or a string. Objects are eveything else. Internal Scripting has many types of objects. You can refer to GEDitCOM Editor help for listing of all possible object types:

In Lifelines, all types can be assigned to variable names. In contrast, Internal Script maintains different name spaces for variable names and object names. It is important that a scipt never uses the same name for a variable as a name used for an object.

When writing Internal Scripts, variable names can start with a number sign (#) while objects names cannot. An good approach when writing Internal Scripts is to use a number sign for all variable names. By this approach, variable and object namnes are never in conflict. When transloating a Lifelines script, however, the original script's variables will not start with number signs. You could insert number signs in front of all INT, BOOL and STRING variables, but it is not necessary. Instead, you can use variable names as they defined in the original script, but you must be careful to not mix variable and object names. You should not, for example use a name for Internal Script variable in one part of the code and then reuse that same name in another part for an Internal Script object. The process is usually straight forward with one exception when passing objects to a subrourine.

(section index)

Expressions

All expression should be converted to Internal Scripting expressions, which are very similar to most programming languages. Most Lifelines functions used in expressions are supported for convenience. Expressions in an Internal Script can only combine variables, numbers, and strings. Numbers are combined by usually operators, String are concatenated using ampersands (&).

Expressions cannot use objects unless the entire expression is just the name of the object or a string expression that evaluates to the name of a object.

(section index)

Statements

Conditionals, loops, and procedure calls must all be converted to Internal Scripting syntax as explained above. Some additional statements also require minor changes:

include options

    The include(string) statement is not supported in this translation. It can be replaced by putting the other script into an Internal Scripting module in this extension (e.g., myModule.gcscpt) and then importing it with

Load myModule.gcscpt

and the Load command must be at the start of the script along with the Load Lifelines command. Such modules, however, can only contain Internal scripting subroutines and definitions.

set options

For set() to "set" a variable, the variable has to be passed by reference in an Internal Script, which means to put the variable's name in quotes. The variable is set to value of expr, which is any expression of variables that evaluates to a string or number. A common mistake when translating scripts it to forget to quote the variable. The script will not flag that as an error, but the script will not work because the variable will not be set.

    Note that emulation of the set() is just to make the translated script "look" like the original Lifelines script. If you are not concerned with looks, it is simpler to replace set() commands for variables with an Internal Script assignment command:

Lifelines:          set(varb,expr)
Emulation Method:   set("varb",expr)     ! quote varb
Assignment Method:  varb = expr          ! just use Internal Script assignment

    Because Internal Scripts have variables and objects, a separate command is needed to set objects. A setobj(obj,expr) sets obj to object name in expr (which is either just an object's name or an expression that evaluates to an object's name). A common method in Lifelines scripts to set an object is:

set(nextgen,parentset(thisgen))

or to set an object to result of a function. Because such subroutines in Internal Scripts cannot return an object and objects are set with setobj(), such commands must be changed. To make this easy, the Lifelines.gcscpt module adds an extra parameter to most functions like parentset(thisgen) to assign a new object. The above line from a Lifelines script could change to:

parentset(thisgen,nextgen)

Note that because Internal Scripts always pass objects by references, the first parameter need not be quoted (although it will still work if it is quoted). The second parameter in emulated functions is optional. If it is not used, the translation would need two lines — one to get the parent set and one to assign it to an object:

parentset(thisgen)
setobj(nextgen,result())

The subroutine will return a new object name and that name can be fetched with the return() expression and then used in a setobj() command (return() must be used before calling any other subroutine, because a new call would replace returned value with a new returned value).

    Note that emulation of the set() with setobj() for objects is just to make the translated script "look" like the original Lifelines script. If you are not concerned with looks, it is simpler to replace set() for objects with an Internal Script object assignment command:

Lifelines:          set(varb,expr)
Emulation Method:   setobj(varb,object)     ! replace expr with pre-calculated object
Assignment Method:  @varb = object          ! just use Internal Script object assignment

(section index)

Subroutines and Functions

Lifelines has procs and funcs. They are similar except funcs can return a value to be used inside an expression. In contrast, Internal Scripts have only subs. While they can return a value, they cannot be used in expressions. Translations of procs and funcs first changes their syntax and then may need one or more of the following changes:

• Subroutine calls can either change call to gosub or can just delete the call (because gosub is optional in Internal Scripts).
• Former funcs that are used in expression have to moved to a separate line and the return value is fetched when done. For example, translation of code to assign an individual's birth object to e using set(e,birth(indi)) can translate two ways

  birth(indi) setobj(e,result())

  birth(indi,e)

  The first calls birth(indi) and then uses result() instead of birth(indi) in a setobj() command, which is changed from a set() command because it is setting an object. The second option looks up birth and assigns to an object name passed in a second optional argument. Most emulated functions in the Lifelines.gcscpt module include such an optional argument to simplify translation.
• If any proc or func method declares global variables, remove that line and replace with Internal Script methods. All variables in Internal Script default to be global so you never need to declare a global, but this means a subroutine might inadvertently change a global variable. To solve this issue, you can declare variables used only in the subroutine to be local, which is done using local commands immediately after the sub command. Each one can have any number of comma separated variable names.
• Variables and objects in Internal Scripts use different name spaces. Internal Script translations should never use the same name for a variable as a name that is used for an object. Namespace mixup can arise when passing an object to a subroutine. Consider the following translation:

  proc pout(gen,indi) { statements } getindi(indi) set(gen,0) call pout(gen,indi)

  sub pout,gen,indi statement endsub getindi(indi) set(gen,0 gosub pout(gen,indi)

  This translation looks correct, but the problem is Internal Scripts always pass objects by reference (which means the call sends the name of the object and not the object). The subroutine in the above translation will create a variable indi (set to string "indi") thereby resulting in both a variable and an object with the same name. The following uses Internal Scripting object assignment to fix the issue:

  sub pout,gen,#indi @indi = #indi statements endsub

  Insert a '#' in front object name being passed by reference (which recognizes it as a variable). The next line dereferences the object name to be an object that can be used in the subroutine. The should pick object names in subroutines that do not overwrite object names in the calling code.
• Recursive subroutines are allowed, but can be tricky. Dealing with variables is easy, just make sure all variables defined by the subroutine are local variables (which includes variable names in the sub definition line. Objects need more work. Any object the subroutine will need after a recursive call should be pushed onto an object stack and then pop back when returned. For example:

  sub pout,gen,#indi local gen,#indi @indi = #indi statements (that might change indi and gen) pushObject(indi) gosub pout(gen,indi) popObject(indi) endsub

  It is essential that every pushObject be balanced by a corresponding popObject() in reverse order.

(section index)

Arithmetic and Logic Functions

These Lifelines methods are mostly supported, but you can also convert to standard, simpler, and more powerful Internal Scripting expressions. The translations are:

(section index)

Person Functions

The following functions retrieve information about an individual. When the function needs an INDI, you pass a reference to a individual record.

spouses(indi,sp,fam,num) {
    statements
}

spouses(indi,spouselist)
repeatwith iter from spouselist
  spousesiter(iter,sp,fam,"num")
  statements
endrepeat

families(indi,fam,sp,num) {
    statements
}

families(indi,famlist)
repeatwith iter from famlist
  familiesiter(iter,fam,sp,"num")
  statements
endrepeat

forindi(indi,num) {
    statements
}

forindi(indilist)
repeatwith iter from indilist
  forindiiter(iter,indi,"num")
  statements
endrepeat

(section index)

Family Functions

The following functions retrieve information about a family. When the function needs an FAM, you pass a reference to a family record.

children(fam,indi,num) {
    statements
}

children(fam,chillist)
repeatwith iter from chillist
  childreniter(iter,indi,"num")
  statements
endrepeat

forfam(fam,num) {
    statements
}

forfam(famlist)
repeatwith iter from famlist
  forfamiter(iter,fam,"num")
  statements
endrepeat

(section index)

List Functions

Lists are handled using Internal Scripting lists, which means you can make use of all the Internal Scripting options for lists (see details in GEDitCOM Editor help). The Lifelines options are supported as follows:

VOID getel(LIST,INT,"ANY")
ifndef ANY then ANY=0

forlist(alist,val,num) {
    statements
}

forlist(alist,listlist)
repeatwith iter from listlist
  forlistiter(iter,objval,"val","num")
  statements
endrepeat

(section index)

Table Functions

Tables are handled using Internal Scripting dictionaries, which means you can make use of all the Internal Scripting options for dictionaries (see details in GEDitCOM Editor help). The Lifelines methods are implemented as follows:

(section index)

GEDCOM Node Functions

Lifelines nodes are equivalent to structures. In addition, record objects can be used wherever a NODE is expected and it will be treated as the root or level 0 node for that record (a record's tag is its record type).

fornodes(node,nodev) {
    statements
}

fornodes(node,nodelist)
repeatwith nodev from nodelist
  statements
endrepeat

traverse(node,nodev,lev) {
    statements
}

traverse(node,nodelist)
repeatwith iter from nodelist
  traverseiter(iter,nodev,"lev")
  statements
endrepeat

(section index)

Event and Date Functions

In an Internal Script, an EVENT is a structure and can be used directly in any NODE function. Options in Lifelines are supported as follows:

(section index)

Value Extraction Functions

(section index)

User Interaction Functions

(section index)

String Functions

Internal Scripting has many methods for working with strings. The Lifelines methods are implemented as follows (some just for convenience):

(section index)

Output Mode Functions

In Lifelines scripts, elements that are not function calls are sent to the output. This method has to be modified in this emulator. The functions are listed here; details on translating scripts are below the table.

out STRING INT ...
cout INT STRING INT ...

Line Mode

The line mode is the default mode. In this mode Lines of Lifelines scripts that are not other commands are output to the report. The translation must comnbine text elements into a single string and then preface the line with out. For example, a line such as:

"ANCESTORS OF -- " upper(name(i)) "    (" key(i) ") " nl() nl()

should be converted to

out "ANCESTORS OF -- "&upper(name(i))&"    ("&key(i)&") "&nl()&nl()

which combines the strings (with &'s) and inserts out() at the start of the line (note: the nl() can optionally be changed to return)

Some Lifeline scripts in line mode output text separated by col() to move to column number before the next block of text. This style is translated as follows: if the line starts in col(), start the line with cout and combine any text sections into single text blocks. For example change:

col(12) name(child) col(63) "(RN=" key(child) ")"

to

cout col(12) name(child) col(63) "(RN="&key(child)&")"

Note that ampersands (&) were used in the last text block to make it a single STRING. If the line starts with a text block, start the command with out and combine text sections into single blocks:

name(child) col(63) "(RN=" key(child) ")"

to

out name(child) col(63) "(RN="&key(child)&")"

In summary, text blocks and col() must alternate and then use cout if the line starts in col() or cout if if it starts with text.

Page Mode

Page mode buffers pages before adding them to a report, which allows output to jump around a page. A common option is to move to position and then output some text. For example, this Lifelines script outputs some text at a position on a page with:

pos(4,10)
"  FULL NAME:   " name(i) col(46) "(" key(i) ")" nl() nl()

This is translated similar to line mode to:

pos(4,10)
out "  FULL NAME:   "&name(i)) col(46) "("&key(i)&")"
nl()
nl()

The text blocks are combined when needed (with ampersands &) and text blocks can be separated by col() commands. In page mode for Internal Scripts, nl() or return are converted to spaces. If you really want a new line, use nl() on a line by itself. A report that is outputting consecutive lines, however, need not use explicit nl() commands because a new line will automatically be started when a requested col() within an out line is before the current column position in the report. Note that col() on a line by itself will move that column on current row and never cause a new line.

An enhancement of page mode in Internal Scripts is that if any col() within an out line is changed to -col(), the previous text will be right justified in the space up to that column. This option only applies when using page mode.

Script Output

By default, script output is sent to a report window with fixed-width font. To direct to a file instead of a report, use an newfile(STRING,INT) command anytime before the final finish() command. The STRING parameter can be a full POSIX path to the desired output file. If it is empty, the user is prompted to pick a file. If user cancels option to pick a file, the report will revert to opening in a report window.

Any output displayed in a report window can also by ouuput to a file later using the "File→Export→Report to Text File" menu command in .

Pinting Messages

(section index)

Person Set Functions and GEDCOM Extraction

These functions are implemented with custom Lifelines.gcscpt modulue methods with list objected passed to each method:

forindiset(b,blist)
repeatwith iter from blist
  forindisetiter(iter,i,"v","n")
  statements
endrepeat

(section index)

Record Update Functions

This Lifelines emulation does not support editing of the data. You can however, use other script-editing methods to make changes to the data in a script.

(section index)

Record Linking Functions

(section index)

Miscellaneous Functions

(section index)