Lumesh Shell Map Module Documentation

Overview

The Map module provides a series of functions for operating on mapping tables (collections of key-value pairs), supporting operations such as creation, querying, modification, and transformation. All functions are called with the map. prefix, for example, map.keys(my_map).

Function Categories

Checking Functions

has

• Function: Check if the mapping table contains the specified key

• Syntax:

  map.has(key, target_map)

• Parameters:

  • key: String - The key to check
  • target_map: Map - The target mapping table

• Return Value: Boolean - Returns true if the key exists, otherwise returns false

• Example:

  let my_map = {a: 1, b: 2}; map.has("a", my_map) # Returns true

Retrieval Functions

use top-level function get to get value via path

items

• Function: Get a list of all key-value pairs in the mapping table

• Syntax:

  map.items(target_map)

• Parameters:

  • target_map: Map - The target mapping table

• Return Value: List - A list of [key, value] pairs

• Example:

  map.items({x: 10, y: 20}) # Returns [["x", 10], ["y", 20]]

keys

• Function: Get a list of all keys in the mapping table

• Syntax:

  map.keys(target_map)

• Parameters:

  • target_map: Map - The target mapping table

• Return Value: List - A list of strings containing all keys

• Example:

  map.keys({name: "Alice", age: 30}) # Returns ["name", "age"]

values

• Function: Get a list of all values in the mapping table

• Syntax:

  map.values(target_map)

• Parameters:

  • target_map: Map - The target mapping table

• Return Value: List - A list containing all values

• Example:

  map.values({a: 1, b: 2}) # Returns [1, 2]

Modification Functions

insert

• Function: Insert a new key-value pair into the mapping table

• Syntax:

  map.insert(key, value, target_map)

• Parameters:

  • key: String - The key to insert
  • value: Any - The value to insert
  • target_map: Map - The target mapping table

• Return Value: Map - A new mapping table containing the new key-value pair (the original mapping table remains unchanged)

• Example:

  let orig = {a: 1}; let new = map.insert("b", 2, orig); # new is {a: 1, b: 2}

remove

• Function: Remove the specified key from the mapping table

• Syntax:

  map.remove(key, target_map)

• Parameters:

  • key: String - The key to remove
  • target_map: Map - The target mapping table

• Return Value: Map - A new mapping table after removing the specified key

• Example:

  map.remove("a", {a: 1, b: 2}) # Returns {b: 2}

Creation Functions

from_items

• Function: Create a mapping table from a list of key-value pairs

• Syntax:

  map.from_items(item_list)

• Parameters:

  • item_list: List - A list containing [key, value] pairs

• Return Value: Map - The newly created mapping table

• Example:

  map.from_items([["x", 10], ["y", 20]]) # Returns {x: 10, y: 20}

Transformation Functions

union

• Function: Merge two mapping tables (the latter overwrites the former)

• Syntax:

  map.union(map1, map2)

• Parameters:

  • map1: Map - The first mapping table
  • map2: Map - The second mapping table

• Return Value: Map - The merged new mapping table

• Example:

  map.union({a:1}, {b:2}) # Returns {a:1, b:2}

intersect

• Function: Get the intersection of keys from two mapping tables (retaining values from the first mapping table)

• Syntax:

  map.intersect(map1, map2)

• Parameters:

  • map1: Map - The first mapping table
  • map2: Map - The second mapping table

• Return Value: Map - A new mapping table containing only the common keys

• Example:

  map.intersect({a:1,b:2}, {a:3}) # Returns {a:1}

difference

• Function: Get the key-value pairs unique to the first mapping table

• Syntax:

  map.difference(map1, map2)

• Parameters:

  • map1: Map - The first mapping table
  • map2: Map - The second mapping table

• Return Value: Map - A new mapping table containing only the unique keys from the first mapping table

• Example:

  map.difference({a:1,b:2}, {a:1}) # Returns {b:2}

deep_merge

• Function: Deeply and recursively merge multiple mapping tables

• Syntax:

  map.deep_merge(map1, map2, ...)

• Parameters:

  • map1, map2, …: Map - The mapping tables to merge (at least two)

• Return Value: Map - The new mapping table after deep merging

• Example:

  let base = {a: {x: 1}}; let update = {a: {y: 2}}; map.deep_merge(base, update) # Returns {a: {x:1, y:2}}

Iteration Functions

map

• Function: Transform the keys and values of a mapping table using functions

• Syntax:

  map.map(key_func, [value_func], target_map)

• Parameters:

  • key_func: Function - A function to process keys (accepts the original key and returns a new key)
  • value_func: Function (optional) - A function to process values (accepts the original value and returns a new value)
  • target_map: Map - The target mapping table

• Return Value: Map - The new mapping table after transformation

• Example:

  let m = {a: 1, b: 2}; # Transform only keys map.map(k -> k + "_new", m) # Returns {a_new:1, b_new:2} # Transform both keys and values map.map(k -> k + "_k", v -> v * 2, m) # Returns {a_k:2, b_k:4}

Usage Recommendations

1. All modification operations (such as insert, remove) return a new mapping table, leaving the original mapping table unchanged.
2. Deep operations (such as deep_merge) can handle nested structures of any level.
3. Using get to access deeply nested values is more concise than chaining get.
4. map.map can be combined with anonymous functions to implement complex transformation logic.

Error Handling

• Type errors will be returned when parameter types do not match.
• Accessing a non-existent path will cause get to throw an error.
• All functions will return None for non-mapping table parameters (except in cases that throw errors).