Change Name Parts

TMG Utility is the essential TMG companion tool. If you use it, please make a donation.

advertisement

On this page: Description, Step by Step, Filters, Actions, User Variables, Field Labels, Rule Files, Example Rule Files

Description

Change Name Parts will change name parts (title, given name, surname, etc.) under the control of one or more filters and one or more actions.

Filters determine which names are changed. If more than one filter is supplied, the filters are anded together, meaning that the name must pass all the filters in order to be changed. The available filters support testing name part contents as well as the name style and the tag type.

Actions determine how the names are changed. The available actions support adding or deleting prefixes, adding or deleting suffixes, setting the entire contents of a name part, changing the name style or changing the tag type.

Both filters and actions use the standard name part labels.

Step by Step

  1. Choose Change Name Parts under Names in the function tree.
  2. Specify the filters and actions by clicking [Set Rules...] to open the Rules Editor.
  3. Set the Match case checkbox if you want the filter terms to be case sensitive. When Match case is checked, "MIXED" does not equal "Mixed". When Match case is not checked, they are equal. The default is unchecked.
  4. Set the Show All Name Fields checkbox if you want the log to show all the name fields in sequence rather than using the associated Name Style to format the log entry. This is useful if you are changing one or more subfields that do not display such as the SortGiven or SortSurname fields.
  5. Set the Flag Filter, if desired. TMG Utility will only change names for people who pass the filter.
  6. Click the [Change Name Parts] button.
  7. TMG Utility will prompt for the literal values if the rule set includes user variables.

Filters

Data Operators Values
Any Name Part
Title
Prefix
GivenName
PreSurname
Surname
Suffix
OtherName
SortGiven
SortSurname
equal to
not equal to
starts with
contains
like
ends with
A sequence of one or more characters.

You can enter user variables and field labels in this value.

Tests the contents of a specific part or all parts.
Any Name Part
Title
Prefix
GivenName
PreSurname
Surname
Suffix
OtherName
SortGiven
SortSurname
like A "regular expression".

Tests the contents of a specific part or all parts.

Regular expressions are a powerful matching facility that allow you to search for patterns of text rather than for literal text values. If you are not familiar with regular expressions, you may want to consider them as a means to add wildcard characters to the target. Regular expressions are described for the Find and Replace feature.

Any Name Part
Title
Prefix
GivenName
PreSurname
Surname
Suffix
OtherName
SortGiven
SortSurname
is empty
is not empty
<not applicable>
Tests whether a field is empty or not empty.
Name Style equal to
not equal
A name style from the list.
Tests the style assigned to the name.
Tag is primary
is not primary
<not applicable>
Tests whether a name tag is primary or not.
Tag Type equal to
not equal
A tag type from the list.
Tests the tag type of the name.

The sequence of filters is important only in that the processing will be faster if the most restrictive filters are at the top of the list.

Actions

Data Operators Values
Title
Prefix
GivenName
PreSurname
Surname
Suffix
OtherName
SortGiven
SortSurname
prepend
delete prefix
set to
append
delete suffix
A sequence of zero or more characters for set to, or a sequence of one or more characters for the other operators.

You can enter user variables and field labels in this value.

These actions can be used to modify the contents of a specific name part. In order to move data from one part to another, you should use an action that deletes data as well as an action that creates data. For example, to move "de " from the start of the Surname field to the PreSurname field, you need two actions:

  1. Change Surname delete prefix "de "
  2. Change PreSurname set to "de"

Furthermore, if you change the Surname field, you will usually want to change the SortSurname field to the same value:

  1. Change Surname delete prefix "de "
  2. Change SortSurname copy  Surname
  3. Change PreSurname set to "de"
Title
Prefix
GivenName
PreSurname
Surname
Suffix
OtherName
SortGiven
SortSurname
replace
A target value in the first textbox and a replacement value in the second textbox.
This action can be used to modify the contents of a specific name part.

The target value will be replaced by the replacement value.

Title
Prefix
GivenName
PreSurname
Surname
Suffix
OtherName
SortGiven
SortSurname
replace pattern A target value in the first textbox and a replacement value in the second textbox.
This action can be used to modify the contents of a specific name part.

The target value will be replaced by the replacement value. The target value is a regular expression.

Regular expressions are a powerful matching facility that allow you to search for patterns of text rather than for literal text values. If you are not familiar with regular expressions, you may want to consider them as a means to add wildcard characters to the target. Regular expressions are described for the Find and Replace feature.

The syntax for user variables conflicts with some regular expressions. You will have difficulty if you try to use a character class expression that begins with "v", as in "[v ...]". Put the "v" elsewhere in the character class to avoid the conflict.

Title
Prefix
GivenName
PreSurname
Surname
Suffix
OtherName
SortGiven
SortSurname
copy A name part from the list.
The copy operator can be used to copy the contents of one part to another part. It's a good idea to use the copy operator to set the SortSurname field to the same value as the Surname field whenever you change the Surname field.
Title
Prefix
GivenName
PreSurname
Surname
Suffix
OtherName
SortGiven
SortSurname
set to Sdx A name part from the list.
This operator can be used to set one name part to the Soundex code for another name part.

TMG Utility uses a Soundex routine that has been modified to match codes generated by TMG. TMG's method stops processing characters at the first space character, whereas some other systems ignore the space and process the remainder of the name part.

RootsWeb provides a Soundex Converter which you may find useful.

Name Style set to
A style from the list.
This operator sets the name style of the name.
Tag Type set to
A tag type from the list.
This operator sets the tag type of the name.

You can combine actions to change multiple parts, etc. The sequence of actions is important only if you perform two or more actions on the same part.

When an action term modifies the Given or Surname field, you will usually want to modify the associated sort field, either SortGiven or SortSurname.

User Variables

Variables allow the creation of general purpose rules; the value of a variable is set via a prompt when you click the [Change Name Parts] button, not when you define the rules. You can include variables in any literal text field used by filters or actions.

User variables work the same way in all of the "Change <something> Parts" features including Change Name Parts, Change Citation Parts, and Change Place Parts. The description on this page applies to all those features.

Variables are entered as follows: "[Vn:prompt]" where

  • "[V" is a literal string that starts a variable reference.
  • "n" is a number from 1 to 9.
  • ":" is an optional prompt delimeter.
  • "prompt" is an optional prompt that TMG Utility uses when it prompts for the value of the variable.
  • "]" is a literal character that ends the variable reference.

If you use the same value more than once in a rule set, and there's a possibility that in the future you'll want to use the same rules with different value, it's a good idea to use a variable to define the value and save the rule set to a file for later use.

TMG Utility will only prompt once for a variable, so you only have to key the "prompt" part of the variable reference once. For example, if you use [V1:Surname?] and in a subsequent filter or action you use [V1], both variable references will be replaced by the same value: whatever is keyed in response to the "Surname?" prompt.

If you click "Cancel" when prompted for a value, TMG Utility will not perform the processing defined by the action rules.

If you want a space (or other special character) before or after the variable text, but whether the space is necessary varies according to the filter or action where it is used, key the space as a literal and do not key the space when prompted for the variable value. See the "Move to PreSurname.u5rn" entry in the Example Rule Files section.

You can not nest user variables. You can put multiple variable references in a literal field, in any sequence.

TMG Utility saves the text you enter when prompted for the value of a user variable. If you rerun the same set of rules, the default value for each user variable will be set to the previous value. You can accept the previous value by clicking [OK] or modify the value before clicking [OK]. This helps when executing the rules with Log Only unchecked after doing a test run with Log Only checked by making it easy to ensure the real run mimics the test run without any inadvertent differences.

If you open the Rule Editor and press [OK] to close it, even if you don't make any changes, TMG Utility discards any saved values. The prompt values are not saved across sessions, so if you close TMG Utility and then restart it later, the default values will be empty.

Here is a set of rules that includes variable references.

If Surname equal to "[V1:Old Surname?]"
Change Surname set to "[V2:New Surname?]"
And Change SortSurname copy Surname

Field Labels

You can reference the value of another field via a Field Label in any literal text value used by filters or actions. Field Label references support the creation of general purpose rules.

The Change Name Parts feature supports the following Field Labels only. If you use custom styles or country-specific versions of TMG that do not use the following labels by default, choose a Field Label from the list below based on the sequence # that matches your Field Label.

Number Field Label
1[TITLE]
2[PREFIX]
3[GIVENNAME]
4[PRESURNAME]
5[SURNAME]
6[SUFFIX]
7[OTHERNAME]
8[SORTSURNAME]
9[SORTGIVEN]

Rule Files (.u5rn)

You can save and load rule files using the Rules Editor. The ".u5rn" files look like text files, but they include invisible characters embedded in the text. Don't change them with a text editor such as Notepad or TextPad. Change them using the Rules Editor.

Example Rule Files

There are a few example rule files in the Rules folder supplied with TMG Utility that demonstrate the feature and actually produce results you might want.

Change SortSurname.u5rn
Changes the SortSurname field when the Surname field is equal to a particular value. Use this example as a base when you want to assign a different SortSurname for specific names in your project. This method--changing the SortSurname for specific Surnames--is an alternative to using Add Standard Name. In this case, you don't add an extra name, you change the SortSurname field to match the expected or standard spelling of the surname.

This rule set uses two user variables: [V1:Surname?] and [V2:SortSurname?]. When prompted for "Surname?", key the Surname of the names for which you want to set a different SortSurname. When prompted for "SortSurname?", key the new SortSurname to be assigned.

Move to PreSurname.u5rn
This rule set moves a variable prefix from the Surname field to the PreSurname field. When prompted for "Surname Prefix?" key "de", "van", or some other prefix that you want to move from the Surname field to the PreSurname field.

The rules include an action to change the Name Style on the assumption that the existing name style does not show the PreSurname field. The name of the style will probably not match a name style in your project. Click on the Change Name Style term, then select the appropriate name style from the pull-down menu. The click [Update Action] to save the term change.

Move Maiden from Suffix to Other.u5rn
Moves the Suffix data to the OtherName field in Name-Marr tags when the suffix includes a specific leader and trailer in the Suffix field. This could be a useful tool for people who have put a woman's maiden name in the Suffix field of Name-Marr tags but who now want to use the OtherName field rather than the Suffix.