MAP Namespace

Overview of MAP Namespaces

A namespace is collection of related keys (or entries) that may share common properties.

For example, ACME_CORPORATION_DEPARTMENTS can be a namespace that refers to a set of departments such as Human Resources, Engineering, IT, and Accounting.

In GLASS, namespaces are defined with the MAP operator and have the following properties:

• Namespaces are unique.
• Namespaces can be referenced anywhere in a GLASS data type definition. For example, use namespaces in search patterns (GROUP), pattern rules (RANGE with REQUIRE / EXCLUDE), or contextual keywords (CONTEXT).
• Namespaces are reusable blocks that can be referenced more than once in a GLASS data type.

The generic GLASS syntax for MAP is:

MAP [NOCASE|DECOMPOSE] '<source namespace>' [NOCASE|DECOMPOSE] '<key>[ = <literal>]'[, [NOCASE|DECOMPOSE] '<key>[ = <literal>]']*

GROUP '<namespace>'

RANGE '<range of characters>' [TIMES <integer>[-<integer>]] [EXCLUDE|REQUIRE '<namespace>']

CONTEXT '<context namespace>' [BEFORE|AFTER|AROUND] [REQUIRE|DENY] '<namespace>'
<search pattern> APPLY '<context namespace>'

See LIST Operator, RANGE Operator, REQUIRE Rule, EXCLUDE Rule and CONTEXT and APPLY for more information.

Defining a MAP Namespace

The MAP operator creates or appends to a namespace and associates a set of keys (or entries) with the given namespace.

Each namespace entry can be defined as a:

1. <key> - a key, or

   MAP NOCASE 'SWIFT_CODES' 'MACSUS33', 'WVIOUS6L'
   

2. <key> and <literal> - a key and associated literal combination.

   MAP NOCASE 'SWIFT_CODES' \
     'MACSUS33' = "Master Card International Inc.", \
     'WVIOUS6L' = "World Vision International"
   

   To find out more about using keys and associated literals in namespaces, see the META operator.

You can define (a combination of) literal values, integers, and integer ranges as keys in namespaces.

• Literal values (e.g. 'AU'),

  MAP 'NS0' 'AU'
  

  

  Note: Literal values that are added as keys to a namespace must be enclosed in single ('') or double quotes ("").
• Integers (e.g. 123), or

   MAP 'NS1' 123
  

  

• Integer ranges (e.g. 2221-2720).

   MAP 'NS2' 2221-2720
  

  

Case Sensitivity of MAP Keys

By default, the GLASS expressions are case sensitive. The NOCASE (No Case) option determines if the GLASS pattern matching engine treats uppercase and lowercase characters as distinct (case sensitive) or equal (case-insensitive) characters.

Without the NOCASE option, uppercase and lowercase characters in namespace entries are distinct characters.

MAP '<namespace>' '<key 1>', '<key 2>', ..., '<key N>'

For example, lowercase usa and uppercase USA are treated as different keys / entries by the GLASS pattern matching engine.

If the NOCASE (No Case) option specified or checked, uppercase and lowercase characters in namespace entries are equal.

MAP NOCASE '<namespace>' '<key 1>', '<key 2>', ..., '<key N>'

For example, lowercase usa and uppercase USA are treated as the same keys / entries by the GLASS pattern matching engine.

MAP Example 1

You want to build a custom data type to search for Australia addresses. You start by defining a MAP namespace containing the abbreviations for all Australian States and Territories, and reference this namespace using the GROUP (LIST) component.

MAP NOCASE 'AU_STATES' 'ACT', 'NSW', 'NT', 'QLD', 'SA', 'TAS', 'VIC', 'WA'
GROUP 'AU_STATES'

Without specifying additional pattern rules, all the following lines will be returned as match locations by the GLASS pattern matching engine:

The equivalent configuration in GLASS Studio Visual Builder mode is:

• MAP Name: 'AU_STATES'
• MAP Entries: 'ACT', 'NSQ', 'NT', 'QLD', 'SA', 'TAS', 'VIC', 'WA'
• MAP No Case option: Checked
• Data type component: LIST (GROUP)
  • List namespace selection: 'AU_STATES'

Decomposing MAP Keys

If the DECOMPOSE (Decompose) option is specified or checked, the GLASS pattern matching engine matches the namespace key / entry both in its original form and normalized (ASCII) form, where applicable.

This is useful when searching for data patterns that contain language-specific accents or diacritics (e.g. s'il vous plaît).

Without the DECOMPOSE option, the GLASS pattern matching engine matches a MAP namespace entry as is.

MAP '<namespace>' '<key 1>', '<key 2>', ..., '<key N>'

If the DECOMPOSE (Decompose) option is specified or checked, the GLASS pattern matching engine matches a MAP namespace entry both in its original form and normalized (ASCII) form, where applicable.

MAP DECOMPOSE '<namespace>' '<key 1>', '<key 2>', ..., '<key N>'

MAP Example 2

You define the following GLASS expression:

MAP NOCASE DECOMPOSE 'MENU_ITEMS' 'crème brûlée', 'gougères', 'paté de pâques'
GROUP 'MENU_ITEMS'

As the NOCASE and DECOMPOSE options are specified or checked, all the underlined terms will be returned as match locations by the GLASS engine:

The equivalent configuration in GLASS Studio Visual Builder mode is:

• MAP Name: 'MENU_ITEMS'
• MAP Entries: 'crème brûlée', 'gougères', 'paté de pâques'
• MAP No Case option: Checked
• MAP Decompose option: Checked
• Data type component: LIST (GROUP)
  • List namespace selection: 'MENU_ITEMS'

Copying Keys to a MAP Namespace

The COPY operator allows you to copy the contents / keys from a source namespace, to a target namespace.

If the target namespace does not exist at the time of the COPY operation, the namespace will be created. Otherwise, the contents of the source namespace will be appended to the target namespace.

The namespace COPY operation preserves all options defined in the source namespace.

The generic GLASS syntax for MAP and COPY is:

MAP [NOCASE|DECOMPOSE] '<source namespace>' [NOCASE|DECOMPOSE] '<key>[ = <literal>]'[, [NOCASE|DECOMPOSE] '<key>[ = <literal>]']*

MAP '<target namespace>' COPY '<source namespace>'[, COPY '<source namespace>']*

Copying Keys in GLASS Studio Visual Builder Mode

In GLASS Studio Visual Builder mode, when multiple namespaces are selected for base pattern components, (GROUP), pattern rules (RANGE with REQUIRE / EXCLUDE), or contextual keywords (CONTEXT), GLASS Studio automatically creates a new target namespace with a unique label and copies the selected source namespaces to the new namespace using the COPY operator.

MAP Example 3

Let's take a look at how the contents for each namespace changes with each new line of GLASS code.

Line 1

A new namespace 'HERBIVORE_INSECTS' is created with two case-insensitive keys.

Line 2

A new namespace 'HERBIVORE_MAMMALS' is created with one case-sensitive, and one case-insensitive key. The contents in namespace 'HERBIVORE_INSECTS' is unchanged.

Line 3

A new namespace 'HERBIVORES' is created and the contents from 'HERBIVORE_INSECTS' and 'HERBIVORE_MAMMALS' are copied to it.

The contents in namespaces 'HERBIVORE_INSECTS' and 'HERBIVORE_MAMMALS' are unchanged.

Line 4

A new namespace 'HERBIVORE_DINOSAURS' is created with two case-sensitive keys.

The contents in namespaces 'HERBIVORE_INSECTS', 'HERBIVORE_MAMMALS' and 'HERBIVORES' are unchanged.

Line 5

The contents from 'HERBIVORE_DINOSAURS' are copied and appended to the target namespace 'HERBIVORES'.

The contents in namespaces 'HERBIVORE_INSECTS', 'HERBIVORE_MAMMALS' and 'HERBIVORE_DINOSAURS' are unchanged.

MAP Example 4

Suppose you are tasked to search for employee names across your organization's data storage locations:

• Ireland site: Cara, Grainne, Shannon
• Singapore site: Charlotte, Evelyn, Layla, Sarah
• U.S. site: Ava, Gabrielle, Ruby, Sophie

You decide to take the approach to create separate namespaces for employee names by location (e.g. IE_NAMES, SG_NAMES, and US_NAMES), and select all three when defining a GROUP. This makes the namespaces easier to manage and also enables the namespaces to be reused in a more flexible manner.

MAP NOCASE 'IE_NAMES' 'Cara', 'Grainne', 'Shannon'
MAP NOCASE 'SG_NAMES' 'Charlotte', 'Evelyn', 'Layla', 'Sarah'
MAP NOCASE 'US_NAMES' 'Ava', 'Gabrielle', 'Ruby', 'Sophie'
MAP 'EMPLOYEE_NAMES' COPY 'IE_NAMES', COPY 'SG_NAMES', COPY 'US_NAMES'
GROUP 'EMPLOYEE_NAMES'

The equivalent configuration and generated GLASS Studio code in GLASS Studio Visual Builder mode is:

• Data type component: LIST (GROUP)
  • Data pattern to search for (+ Create Map):
    • 1st namespace
      • Label : IE_NAMES
      • Entries: 'Cara', 'Grainne', 'Shannon'
      • No Case option: Checked
    • 2nd namespace
      • Label : SG_NAMES
      • Entries: 'Charlotte', 'Evelyn', 'Layla', 'Sarah'
      • No Case option: Checked
    • 3rd namespace
      • Label : US_NAMES
      • Entries: 'Ava', 'Gabrielle', 'Ruby', 'Sophie'
      • No Case option: Checked

MAP NOCASE 'IE_NAMES' 'Cara', 'Grainne', 'Shannon'
MAP NOCASE 'SG_NAMES' 'Charlotte', 'Evelyn', 'Layla', 'Sarah'
MAP NOCASE 'US_NAMES' 'Ava', 'Gabrielle', 'Ruby', 'Sophie'
MAP 'NS_1673427388991' COPY 'IE_NAMES', COPY 'SG_NAMES', COPY 'US_NAMES'
GROUP 'NS_1673427388991'

Adding MAP Namespaces

To add a MAP namespace in GLASS Studio Visual Builder Mode:

1. Click on the Map icon in the GLASS Studio playground to open the MAPS dialog and click on .
   Or
   Add a LIST Component to the GLASS Studio project and click on Create Map.
   Or
   Add a RANGE Component to the GLASS Studio project, click to add a REQUIRE or EXCLUDE rule, and click on Create Map.
2. In the New Map dialog:
   

   1. Add a unique and descriptive label in the Map Name field to identify the MAP namespace.

      Tip: This label is the value that will be used when you reference the MAP namespace in your GLASS expressions.

   2. Add keys to the MAP namespace.
      Manual Entry
      Key in a literal (enclosed in single '' or double quotes ""), integer, or integer range into the MAP entries field below and press the Enter key to add the key(s).

      File Upload
      Upload a set of keys by clicking on + Add from file and selecting a text or CSV file. Each MAP entry must be defined on a new line.

      'AU'
      'IE'
      123
      2221-2720
      

      See Defining a MAP Namespace for more information.

   3. (Optional) Select the No Case NOCASE or Decompose (DECOMPOSE) global options.
   4. (Optional) Hover over a key and click on to remove the key from the MAP namespace.
3. Click on Save Map to save the new MAP namespace.

Managing MAP Namespaces

To view a list of all MAP namespaces that have been added to the GLASS Studio data type project, click on the Map icon in the GLASS Studio playground to open the MAPS dialog.

All available MAP namespaces are displayed with the following details:

• Map Name - Describes the unique identifier / label for the namespace.
• Entries - Indicates the number of keys (entries) that are associated with the namespace.
• References - Indicates the number of times the namespace is referenced in a base pattern or pattern rule in the current project. A namespace can only be deleted if it is not referenced anywhere in the GLASS data type project.
• [Actions] - Option to edit or Trash the namespace.

Editing MAP Namespaces

You can modify the label, add new keys, and/or remove existing keys when you edit a MAP namespace.

To edit a MAP namespace:

1. Click on the Map icon in the GLASS Studio playground to open the MAPS dialog.
2. Hover over a namespace in the Map Name column until you see a blue underline and click to edit the MAP namespace.
   
3. (Optional) Update the identifier for the MAP namespace in the Map Name field. The Map Name field can only be updated if the namespace is not referenced anywhere in the GLASS data type project.
4. (Optional) Add new keys to the MAP namespace.
5. (Optional) Remove existing keys from the MAP namespace.
6. Click on Save Map to save the changes made to the MAP namespace.
7. (Optional) Click Close to discard all changes made and exit the Edit your Map dialog.

Deleting MAP Namespaces

To remove a MAP namespace:

1. Click on the Map icon in the GLASS Studio playground to open the MAPS dialog.
2. Click on the Trash icon next to a MAP namespace. A namespace can only be deleted if it is not referenced anywhere in the GLASS data type project.
   
3. Click on Ok to delete the MAP namespace.