Main Help → GENerel Reference / GENerel Commmands → GEDCOM Expressions

GEDCOM Expressions

You can use GEDCOM expressions, which are text phrases beginning in "@", to extract text from the current genealogy data. Furthermore, the result of a GEDCOM expression can be used as an element in any expression.

Note that these "@" expressions are for use when customizing the interface by writing browser styles. When writing internal scripts, the "@" expression changes from reading genealogy data to reading properties of scripting objects.

GEDCOM Expressions

A GEDCOM expression begins with an "@" sign and has any number of GEDCOM tags or specially defined psuedo tags connected by periods:

@tag1.tag2.tag3. ...

GEDCOM expressions are evaluated left to right by looking up the tags in the GEDCOM data or by performing special tag functions. When in a template, the look up starts in the GEDCOM structure for the current template. The following rules apply:

• When a tag is located, the expression to that point will be the text contents of that tag. If the tag is not found, the expression evaluates to an empty string. For example

  @NAME
  

  will evaluate to the name when in a template for an individual record. When in a structure template, the look up starts in the structure. For example

  @DATE
  

  is the birth date if used in the "BIRT Editing" template.
• The above step will always find the first requested tag in the current structure. You can find the second, third, etc., with expressions like:

  @CHIL.i.2
  @CHIL.i.#varName
  

  Here the "i" means an indexed search and the subsequent tag is the tag number to find. The tags are numbered starting from 1. The tag number can be a variable (that contains a number).
• If a located tag has subordinate date, additional tags can be used to access that data. For example, in an individual record, the expression:

  @BIRT.DATE
  

  will evaluate to that person's birth date.
• If a located tag has a pointer to a record, the tag itself will evaluate to that record ID. For example, in an individual's template

  @FAMS
  

  will evaluate to a record ID for the family record with the current individual as a spouse (e.g., @F143@)
• Subsequent tags after a record ID will reference data in the referenced record rather than in the original record. Some examples are

  @FAMC.HUSB.NAME = father's name
  @FAMC.WIFE.FAMC.HUSB.NAME = maternal grandfather's name
  @FAMS.MARR.PLAC = marriage place
  @DEAT.SOUR.TITL = title of source on a death event
  @FAMS.CHIL.FAMS.CHIL.NAME = name of a grandchild
  

  Sometimes, however, you would like to reference data subordinate to a tag that has a valid record ID. To access such data, you must insert an "s" tag between the parent tag and the subordinate tags. For example, the expression

  REPO.s.CALN
  

  will find the CALN line (call number) subordinate to the REPO (repository link) tag. The "s" tag says to look for subordinate data. Without the "s" tag, the search would move to the Repository record where it would not find the call number.
• Any tag in a GEDCOM expression can be a variable that contains a record ID and subsequent tags will be read from that record. For example

  #spouse=@FAMS.HUSB
  @#spouse.NAME
  

  Here #spouse will have the husband's ID (e.g., @I34@). The second expression will evaluate to @@I34@.NAME and return the name of a women's husband. The inserted element can only be an variable and cannot an expression that combines variables with with operators.
• Numerous special tags are defined. Some of these special tags only make sense alone or at the end of a GEDCOM expression, while others can be used anywhere in a GEDCOM expression:
  • tag - the GEDCOM tag of the GEDCOM line for the current template (e.g., @tag)
  • contents - the contents of the GEDCOM line for the current template (e.g., @contents.HUSB.NAME)
  • level - the level number of the GEDCOM line for the current template (e.g., @level)
  • this - record pointer to the record containing the GEDCOM line for the current template (e.g., @this.SEX)
  • parent - get the structure of the data for the current template (if it exists). An important special case is when used in a template for data from StructuresLink cell where parent gives the structure that contains the data linked by that cell (if it exists). For example, to find the tag for the parent structure, use @parent.tag.
  • rec - the GEDCOM record type such as INDI, FAM, SOUR, etc. (e.g., @rec is record type of the GEDCOM line for the current template).
  • id - the GEDCOM record ID for the referenced record.
  • view - returns a description of a record suitable for display. The result depends on record type. The view of a individual record is the person's name, the view of a source is the title, etc. (e.g., @FAMS.view). This tag can also be appended to expressions ending in NAME or DATE to format the name (in format "last, first") or date using the user-defined format.
  • altview - returns an alternate description of a record. The result depends on record type. For example, the view of an individual gives last name first while the altview gives the first name first. If a record has no altview, this tag will return the view instead (e.g., @FAMS.HUSB.altview). This tag can also be appended to expressions ending in NAME to format the name (in format "first last")
  • spouse - the record ID for an individual's spouse (e.g., @spouse.NAME).
  • year - convert a date into just a year (e.g., @BIRT.DATE.year) (2).
  • span - converts a date to a life span from that year to the individual's death year. Normally it is used after a birth date as in BIRT.DATE.span. It will output "1834-1903" for birth and death years. If either date is unknown it will be empty. If the death date is unknown, but the individual is known to be deceased (e.g., the "Has Died" check box is checked), the death date will by "?". (2).
  • user - reformat a date using the user-defined format for dates in the GEDitCOM II settings (e.g., @BIRT.DATE.user) (2).
  • i - find tag by index number.
  • s - find subordinate data to a tag with a valid record ID.
  • _REF - in NOTE, SOUR, and OBJE records, this special tag returns a record pointer to the first record citing the notes, source, or multimedia object or returns empty string if no records cite it. You can using indexing (e.g., @REF.i.3) to find the second, third, etc., record citing the current record (or empty string if fewer records cite it). (1)
  • sdn - convert a date into a serial day number or a positive integer with day one corresponding to date in 4714 B.C. (e.g., @DEAT.DATE.sdn) (2).
  • trunc - truncate the current expression to 50 characters an insert an ellipsis (...) if it is longer (e.g., @OCCU.NOTE.CONC.trunc). This tag can optionally be followed by a number (or a variable containing a number) to truncate to a different number of characters (e.g., view.trunc.25).
  • err - describe the reason a GEDCOM record is corrupted (e.g., @err for column of corrupted records in the index window).
  • number - this tag tells GEDitCOM II you expect the result to be a number but does not do anything else. It has no use in templates. It is useful in GEDitCOM II for determining the sorting method for columns in the index window (2).
  • reverse - reverse the order of a comma-separated list. For example PLAC.reverse would convert place name of "Ridgewood, Bergen, NJ, USA" to "USA, NJ, Bergen, Ridgewood."
  • count - counts the number of tags at the current level and tag is given by the next element in the expression (e.g., @count.OBJE counts the number of OBJE links in the current record). The next tag can be INDIEvents, INDIAttributes, INDIOrdinances, FAMEvents, FAMOrdinances to count event, attribute, or ordinance tags in individual or family records.
  • countAll - same as count option except it counts tags in all subordinate levels and it cannot use the events, attributes, or ordinaces options, because it does not make sense (i.e., those tags are always comfined to level 1 in records).

Notes

1. Even though a @_REF expression looks like a reference to a GEDCOM tag (and can even be indexed), it does not correspond to actual GEDCOM data. Thus you cannot use Show _REF or ShowAll _REF commands to access the cited records or read all cited records in ReadAll or RepeatWith commands. You could however, read all cited records in a repeat loop such as:

   #index=0
   Repeat
     #index+=1
     #cite=@_REF.i.#index
     if #cite=""
       break
     endif
     
     ! commands to display cited record with pointer in #cite
     
   EndRepeat
   

   Warning: Some GEDCOM files cite source records by many records (maybe thousands of records in large files). A template to display them all could get intolerably slow. A simple solution is for the template to use a LinkButton MenuLinked to the "Referenced By" menu command.
2. This tag must be the last tag in an expression. Any tags after this tag will be ignored.
3. If the date referenced by the expression is not in the file, the result of the expression will be an empty string.