Lumesh List Module Documentation

Module Overview

The Lumesh list module provides a rich set of list manipulation functionalities, categorized into the following functional groups:

Element Retrieval Functions (Get)

`list.first`

Functionality: Get the first element of the list.
Parameters: List.
Return Value: The first element or an error (if the list is empty).
Example:
list.first([1, 2, 3]) -- returns 1

`list.last`

Functionality: Get the last element of the list.
Parameters: List.
Return Value: The last element or an error (if the list is empty).
Example:
list.last([1, 2, 3]) -- returns 3

`list.nth`

Functionality: Get the element at the specified position in the list.
Parameters:
- Index (integer, supports negative numbers for counting from the end).
- List.
Return Value: The element at the specified position or an error (if the index is out of bounds).

Example:

list.nth(2, [1, 2, 3])  -- returns 2
      
list.nth(-1, [1, 2, 3]) -- returns 3

`list.take`

Functionality: Get the first n elements of the list.
Parameters:
- Count n (integer).
- List.
Return Value: A new list.

Example:

list.take(2, [1, 2, 3, 4])  -- returns [1, 2]

`list.drop`

Functionality: Get the part of the list after skipping the first n elements.
Parameters:
- Count n (integer).
- List.
Return Value: A new list.

Example:

list.drop(2, [1, 2, 3, 4])  -- returns [3, 4]

List Modification Functions (Modify)

`list.append`

Functionality: Add an element to the end of the list.
Parameters:
- The element to add.
- List.
Return Value: A new list.

Example:

list.append(4, [1, 2, 3])  -- returns [1, 2, 3, 4]

`list.prepend`

Functionality: Add an element to the beginning of the list.
Parameters:
- The element to add.
- List.
Return Value: A new list.

Example:

list.prepend(0, [1, 2, 3])  -- returns [0, 1, 2, 3]

`list.sort`

Functionality: Sort the list.
Parameters:
- Optional: A sorting function (accepts two elements and returns a comparison result).
- Or optional: A list of fields.
- Or optional: Multiple field parameters.
- List or string (will be automatically converted to a list).
Return Value: A new sorted list.

Example:

list.sort([3, 1, 2])  -- returns [1, 2, 3]
list.sort((a, b) -> a > b, [1, 2, 3])  -- descending order sort
fs.ls -l | list.sort('type', size)

`list.unique`

Functionality: Remove duplicate elements from the list (preserving order).
Parameters: List.
Return Value: A new list with duplicates removed.

Example:

list.unique([1, 2, 2, 3])  -- returns [1, 2, 3]

`list.split_at`

Functionality: Split the list at a specified position.
Parameters:
- Split position (integer).
- List.
Return Value: A new list containing two lists.

Example:

list.split_at(2, [1, 2, 3, 4])  -- returns [[1, 2], [3, 4]]

List Creation Functions (Create)

`list.concat`

Functionality: Concatenate multiple lists or elements.
Parameters: Variable number of parameters (lists or elements).
Return Value: A new concatenated list.

Example:

list.concat([1, 2], [3, 4])  -- returns [1, 2, 3, 4]
      
list.concat(1, 2, 3, 4)      -- returns [1, 2, 3, 4]

`list.from`

Functionality: Create a list from a range or elements.
Parameters:
- Range (e.g., 1..10) or list of elements.
Return Value: A new list.

Example:

list.from(1..3)  -- returns [1, 2, 3]
      
list.from(1, 2, 3) -- returns [1, 2, 3]

Higher-order Functions

`list.map`

Functionality: Apply a function to each element of the list.
Parameters:
- Mapping function.
- List.
Return Value: A new list with the function applied.

Example:

list.map(x -> x * 2, [1, 2, 3])  -- returns [2, 4, 6]

`list.filter`

Functionality: Filter elements of the list.
Parameters:
- Filtering function (returns a boolean).
- List.
Return Value: A new list with elements that satisfy the condition.

Example:

list.filter(x -> x > 2, [1, 2, 3, 4])  -- returns [3, 4]

`list.filter_map`

Functionality: Filter and map the list simultaneously.
Parameters:
- Function (returns None to filter out).
- List.
Return Value: A new list.

Example:

list.filter_map(x -> if x > 2 { x * 2 } else { None }, [1, 2, 3, 4])  -- returns [6, 8]

`list.reduce`

Functionality: Reduce the list from left to right.
Parameters:
- Reducing function (accepts accumulated value and current element).
- Initial value.
- List.
Return Value: The reduction result.

Example:

list.reduce((acc, x) -> acc + x, 0, [1, 2, 3])  -- returns 6

`list.find`

Functionality: Find the position of an element in the list.
Parameters:
- The element to find.
- List.
Return Value: Index (if found) or None (if not found).
Example:
list.find(2, [1, 2, 3]) -- returns 1

Grouping and Reorganizing Functions

`list.group`

Functionality: Group by a key function.
Parameters:
- Key function or key name (only applicable when list items are maps).
- List.
Return Value: A mapping of key-value pairs { key1: [items1,…], key2: [items2,…], … }.

Example:

list.group(x -> x % 2, [1, 2, 3, 4])  -- returns {0: [2, 4], 1: [1, 3]}
      

# Group by type
fs.ls -l | list.group 'type'     # 'type' is the function name, so the quotes cannot be omitted.

+-----------------------------------------------------------------+
| KEY        VALUE                                                |
+=================================================================+
| directory  +--------------------------------------------------+ |
|            | MODE  MODIFIED          NAME     SIZE  TYPE      | |
|            +==================================================+ |
|            | 493   2025-05-13 10:57  assets   102   directory | |
|            | 493   2025-04-06 12:21  benches  66    directory | |
|            | 493   2025-06-02 05:15  src      346   directory | |
|            | 493   2025-03-23 11:58  target_  128   directory | |
|            | 493   2025-06-03 04:32  wiki     528   directory | |
|            +--------------------------------------------------+ |
| file       +--------------------------------------------------+ |
|            | MODE  MODIFIED          NAME          SIZE  TYPE | |
|            +==================================================+ |
|            | 420   2025-03-23 05:32  LICENSE       1K    file | |
|            | 420   2025-05-29 12:57  README.md     4K    file | |
|            | 420   2025-06-02 06:26  Cargo.lock    46K   file | |
|            | 420   2025-05-29 12:57  README-cn.md  4K    file | |
|            | 420   2025-06-02 04:40  CHANGELOG.md  9K    file | |
|            | 420   2025-06-02 06:26  Cargo.toml    2K    file | |
|            +--------------------------------------------------+ |
| symlink    +-----------------------------------------------+    |
|            | MODE  MODIFIED          NAME    SIZE  TYPE    |    |
|            +===============================================+    |
|            | 511   2025-03-29 05:58  target  11    symlink |    |
|            +-----------------------------------------------+    |
+-----------------------------------------------------------------+

`list.chunk`

Functionality: Chunk the list.
Parameters:
- Size of each chunk.
- List.
Return Value: A list of chunks.

Example:

list.chunk(2, [1, 2, 3, 4])  -- returns [[1, 2], [3, 4]]

`list.zip`

Functionality: Merge two lists.
Parameters:
- List 1.
- List 2.
Return Value: A list of pairs.

Example:

list.zip([1, 2], ["a", "b"])  -- returns [[1, "a"], [2, "b"]]

`list.unzip`

Functionality: Unzip a list of pairs.
Parameters: A list of pairs.
Return Value: Two lists.

Example:

list.unzip([[1, "a"], [2, "b"]])  -- returns [[1, 2], ["a", "b"]]

`list.transpose`

Functionality: Transpose a matrix (list of lists).
Parameters: Matrix.
Return Value: The transposed matrix.

Example:

list.transpose([[1, 2], [3, 4]])  -- returns [[1, 3], [2, 4]]

`list.foldl`

Functionality: Fold the list from left to right.
Parameters:
- Fold function (accepts accumulated value and current element).
- Initial value.
- List.
Return Value: The fold result.

Example:

list.foldl((acc, x) -> acc + x, 0, [1, 2, 3])  -- returns 6

`list.foldr`

Functionality: Fold the list from right to left.
Parameters:
- Fold function (accepts accumulated value and current element).
- Initial value.
- List.
Return Value: The fold result.

Example:

list.foldr((acc, x) -> acc + x, 0, [1, 2, 3])  -- returns 6

Utility Functions

`list.join`

Functionality: Join a list of strings.
Parameters:
- Separator.
- List of strings.
Return Value: A joined string.

Example:

list.join(", ", ["a", "b", "c"])  -- returns "a, b, c"

`list.to_map`

Functionality: Convert a list to a map.
Parameters:
- Optional: Key function (defaults to the element itself).
- Optional: Value function (defaults to the element itself). If both key and value functions are omitted, the 0th, 2nd… elements are used as keys, and the 1st, 3rd… elements are used as values.
- List.
Return Value: A map.

Example:

list.to_map(x -> x.id, y -> y.name, [{id: 1, name: "wang"}, {id: 2, name: "fang"}])  -- returns {1: "wang", 2: "fang"}
      
list.to_map(x -> x.id, [{id: 1}, {id: 2}])  -- returns {1: {id: 1}, 2: {id: 2}}
      
list.to_map([Q1, 45, Q2, 52, Q3, 49, Q4, 87])  -- returns {Q1: 45, Q2: 52, Q3: 49, Q4: 87}

`list.emulate`

Functionality: Simulate enumeration of indices and values.
Parameters: List.
Return Value: A list of index-value pairs.

Example:

list.emulate(["a", "b"])  -- returns [[0, "a"], [1, "b"]]

updated at 2025-06-14

# libs # list # array