Lumesh Built-in Function Library

Lumesh Built-in Function Documentation: Core Modules

Modules

Top-Level Functions

1. Environment Control Functions

1. cd

   • Function: Change the current working directory
   • Parameters:
     • path: String | Symbol - Target path (supports ~ for home directory)
   • Returns: None
   • Example:

cd "~/projects"  # Switch to the projects folder in the user's home directory

2. exit

   • Function: Terminate the process
   • Parameters:
     • [Optional] code: Integer - Exit status code (default is 0)
   • Returns: None (directly terminates the process)
   • Example:

exit 1  # Exit with status code 1

3. set
   same as sys.set

4. unset
   same as sys.unset

2. Input and Output Functions

1. print / println

   • Function: Print parameters (println automatically adds a newline)
   • Parameters:
     • ...values: Any - Any number of parameters
   • Returns: None
   • Example:

print "Result:" 25  # Output: Result: 25

1. pprint

   • Function: Print parameters pretty
   • Parameters:
     • values: Any - parameter
   • Returns: None
   • Example:

0...10 | pprint()     # output: table
fs.ls -l |  pprint()  # output: table

2. eprint / eprintln

   • Function: Output to the red error stream (with ANSI color codes)
   • Parameters:
     • ...values: Any - Any number of parameters
   • Returns: None
   • Example:

eprintln "Error: File not found"  # Red error message

3. tap

   • Function: Print parameter values and return them unchanged
   • Parameters:
     • ...values: Any - Any number of parameters
   • Returns: The last parameter or the parameter list
   • Example:

tap (range 5) |> map (*2)  # First print [0,1,2,3,4] then execute map

4. read

   • Function: Read user input
   • Parameters:
     • [Optional] ...prompt: Any - Any number of prompt messages
   • Returns: String
   • Example:

let name = read "Enter name:"  # Display prompt and wait for input

3. Type Operation Functions

1. type

   • Function: Get the type name of a value
   • Parameters:
     • value: Any - Value of any type
   • Returns: String
   • Example:

type [1 2 3]  # Returns "List"

to convert between data types, look into into module.

4. Data Structure Functions

1. ** get **

   • Function: Retrieve values from nested complex data using dot-separated paths.

   • Syntax:

     map.get(path, target_collection)

   • Parameters:

     • path: String - Dot-separated path (e.g., “a.b.c”, “1.name”)
     • target_collection: Map/List/Range - A mapping/list/range that can be nested.

   • Return Value: Any - The value corresponding to the path; an error is raised if the path does not exist.

   • Example:

     let nested = {a: {b: {c: [42, 43]}}, r: [0..3, 10..15]}; map.get("a.b.c.0", nested) # Returns 42 map.get("a.r.0", nested) # Returns 0..3 map.get("a.r.0.1", nested) # Returns 1

2. insert

   • Function: Insert an element into a container
   • Parameters:
     • index: Integer | String - Index (numbers for lists, strings for dictionaries)
     • value: Any - Value to insert
     • container: List | HMap | Map | String - Target container
   • Returns: New container
   • Example:

insert 0 "X" ["A" "B"]  # Returns ["X" "A" "B"]
insert "key" 42 {}      # Returns {key: 42}

3. len

   • Function: Get the length of a container
   • Parameters:
     • container: List | HMap | Map | String | Bytes
   • Returns: Integer
   • Example:

len "hello"  # Returns 5

4. rev

   • Function: Reverse a sequence
   • Parameters:
     • container: List | String | Symbol | Bytes
   • Returns: Reversed result of the same type
   • Example:

rev "abc"  # Returns "cba"

5. flatten

   • Function: Flatten a nested structure
   • Parameters:
     • container: List | HMap | Map
   • Returns: List
   • Example:

flatten [[1] {a: [2]}]  # Returns [1, 2]

5. Advanced Operation Functions

1. where

   • Function: Filter table rows (third part cmd is to be used with parse.cmd)
   • Parameters:
     • condition: Lambda/Function - Boolean condition
     • rows: List - List of row data (each row is a Map/HMap)
   • Returns: List
   • Example:

   supported vars: LINENO, LINES and keys of the map.

fs.ls -l | where(size<1K)

fs.ls -l | where(LINENO>1)

2. select

   • Function：Select table cols（third part cmd is to be used with parse.cmd）
   • Parameters：
     • headers: 1 List/ many symbol - headers list
     • rows: List - List of row data（each row is a Map/HMap）
   • Returns：List
   • Example：

fs.ls -l | select(name,size)

2. repeat

   • Function: Generate values repeatedly
   • Parameters:
     • count: Integer - Number of repetitions
     • generator: Expression - Generation expression
   • Returns: List
   • Example:

repeat 3 "A"  # Returns ["A" "A" "A"]

6. Script Import and Execution Functions

1. import

   • Function: Import and execute a script file (creates a new environment)
   • Parameters:
     • path: String - File path (based on the current working directory)
   • Returns: Result of the last expression in the file
   • Example:

import "utils.lm"  # Import script from the same directory

2. include

   • Function: Import and execute a script file (shares the current environment)
   • Parameters:
     • path: String - File path
   • Returns: Result of the last expression in the file
   • Note: The difference from import is the environment sharing mechanism
   • Example:

include "config.lm"  # Execute script in the current environment

3. eval

   • Function: Dynamically execute an expression (creates a new environment)
   • Parameters:
     • expression: Any - Executable expression
   • Returns: Result of the expression execution
   • Example:

eval(parse.expr "(1 + 2) * 3")  # Returns 9

4. exec_str

   • Function: Dynamically execute a string expression (shares the current environment)
   • Parameters:
     • expression: String - Executable expression
   • Returns: Result of the expression execution
   • Example:

exec_str("(1 + 2) * 3")  # Returns 9

5. exec

   • Function: Dynamically execute an expression (shares the current environment)
   • Parameters:
     • expression: Any - Executable expression
   • Returns: Result of the expression execution
   • Example:

exec(parse.expr "(1 + 2) * 3")  # Returns 9

7. Debugging Tool Functions

1. debug

   • Function: Print debugging information for parameters (with type identification)
   • Parameters:
     • ...values: Any - Any number of parameters
   • Returns: None
   • Example:

debug [1, "text", true]  # Output: [Integer(1), String("text"), Boolean(true)]

2. report

   • Function: Format and print complex data structures
   • Parameters:
     • value: HMap | Map | String - Structured data
   • Returns: None
   • Example:

report {name: "Alice", age: 30}  # Format and output dictionary

8. Help System Functions

1. help
   • Function: Display built-in function documentation
   • Parameters:
     • [Optional] name: String - Module name/function name
   • Returns:
     • Returns a list of all functions when no parameters are provided
     • Returns documentation for the specified function when a parameter is provided
   • Example:

help len  # Display documentation for the len function

help about

# Returns
+-------------------------------------------------+
| KEY         VALUE                               |
+=================================================+
| version     "0.4.4"                             |
| git         "https://codeberg.com/santo/lumesh" |
| author      "Adam McDaniel, santo"              |
| path        "/tmp/target/debug/lume"            |
| suggestion  "Use the `?:` to handle errors and  |
|             read error messages!"               |
| homepage    "https://codeberg.com/santo/lumesh" |
| prelude     None                                |
| license     "APACHE-2.0"                        |
+-------------------------------------------------+

Note: All built-in functions support two calling syntaxes:
func(arg1, arg2) or func arg1 arg2
It is recommended to use the first form when parameters contain complex structures.