Lumesh File System Module Documentation

Module Overview

The Lumesh file system module provides a rich set of file/directory operation functionalities, divided into the following functional groups:

Information Retrieval Functions (Get)

fs.dirs

• Function: Get standard directory paths of the system
• Return Value: Returns a mapping table containing system directory paths
• Example:

fs.dirs()  #-- Returns {home="...", config="...", cache="...", data="...", pic="...", desk="...", docs="...", down="...", current="..."}

fs.ls

• Function: List directory contents
• Parameters:
  • Optional path parameter (string)
  • Optional options parameter (symbol or string):
    • -l: Show detailed information
    • -a: Show hidden files
    • -L: Follow symbolic links
    • -U: Show UNIX timestamps
    • -k: Display size in KB, defaults to human-readable format
    • -u: Show user ID (Unix)
    • -m: Show permission mode (Unix)
    • -p: Show full path
• Return Value: List of files/directories; returns a mapping table with metadata in detailed mode
• Example:

fs.ls()          # -- List current directory
fs.ls("-l")      # -- Detailed list
fs.ls("-l -a")   # -- Detailed list including hidden files
fs.ls("~/Downloads") -- List downloads directory

• File Size
  This is a special data type consisting of numbers and units that can be directly compared.

1024K==1M              # Returns: True

fs.ls -l | where(size > 5K)

# Returns:

+---------------------------------------------------------------+
| MODE  MODIFIED                       NAME          SIZE  TYPE |
+===============================================================+
| 420   2025-06-02T06:26:18.518753376  Cargo.lock    46K   file |
| 420   2025-06-02T04:40:56.185300249  CHANGELOG.md  9K    file |
+---------------------------------------------------------------+

• Time
  This is also a data type that can be directly compared or involved in time calculations:

fs.ls -l | where(modified > time.parse('2025-06-01'))

# Returns:
+--------------------------------------------------------------------+
| MODE  MODIFIED                       NAME          SIZE  TYPE      |
+====================================================================+
| 493   2025-06-02T05:15:40.117198118  src           346   directory |
| 420   2025-06-02T06:26:18.518753376  Cargo.lock    46K   file      |
| 493   2025-06-03T04:32:11.980565126  wiki          528   directory |
| 420   2025-06-02T04:40:56.185300249  CHANGELOG.md  9K   file      |
| 420   2025-06-02T06:26:31.105350975  Cargo.toml    2K   file      |
+--------------------------------------------------------------------+


fs.ls -l | where(time.diff('d',modified)>2)

# Returns:
+--------------------------------------------------------------------+
| MODE  MODIFIED                       NAME          SIZE  TYPE      |
+====================================================================+
| 420   2025-03-23T05:32:28.669533898  LICENSE       1K    file      |
| 493   2025-05-13T10:57:43.452389275  assets        102   directory |
| 493   2025-04-06T12:21:40.016431660  benches       66    directory |
| 493   2025-03-23T11:58:56.124332786  target_       128   directory |
| 511   2025-03-29T05:58:39.035865303  target        11    symlink   |
| 420   2025-05-29T12:57:07.160557939  README.md     4K    file      |
| 420   2025-05-29T12:57:07.160557939  README-cn.md  4K    file      |
+--------------------------------------------------------------------+

fs.glob

• Function: Match files using wildcard patterns
• Parameters:
  • Pattern string (e.g., *.txt)
• Return Value: List of matched file paths
• Example:

fs.glob("*.txt")  # -- Match all txt files in the current directory

fs.tree

• Function: Get directory tree structure
• Parameters:
  • Optional parameter 1: Maximum depth (integer) or path (string)
  • Optional parameter 2: Path (string)
• Return Value: Nested directory tree structure
• Example:

fs.tree()        # -- Complete tree structure of the current directory
fs.tree(2)       # -- Current directory with 2 levels deep
fs.tree(3, "~/projects") -- Specify directory with 3 levels deep

fs.canon

• Function: Normalize path (resolves . and .. and symbolic links)
• Parameters: Path string
• Return Value: Normalized path string
• Example:

fs.canon(".././dir")  # -- Returns the resolved absolute path

Modification Functions (Modify)

fs.mkdir

• Function: Create a directory
• Parameters: Directory path (string)
• Return Value: None
• Example:

fs.mkdir("new_dir")  # -- Create new_dir directory

fs.rmdir

• Function: Remove an empty directory
• Parameters: Directory path (string)
• Return Value: None
• Example:

fs.rmdir("empty_dir")  # -- Remove empty_dir directory

fs.mv

• Function: Move a file/directory
• Parameters:
  • Source path (string)
  • Destination path (string)
• Return Value: None
• Example:

fs.mv("old.txt", "new.txt")  # -- Rename file
fs.mv("dir1", "dir2")       # -- Move directory

fs.cp

• Function: Copy a file/directory
• Parameters:
  • Source path (string)
  • Destination path (string)
• Return Value: None
• Example:

fs.cp("file.txt", "backup.txt")  # -- Copy file
fs.cp("src_dir", "dst_dir")      # -- Recursively copy directory

fs.rm

• Function: Remove a file/directory
• Parameters: Path (string)
• Return Value: None
• Example:

fs.rm("file.txt")    # -- Remove file
fs.rm("dir")         # -- Recursively remove directory

Checking Functions (Check)

fs.exists

• Function: Check if a path exists
• Parameters: Path (string)
• Return Value: Boolean
• Example:

fs.exists("file.txt")  # -- Returns true or false

fs.is_dir

• Function: Check if a path is a directory
• Parameters: Path (string)
• Return Value: Boolean
• Example:

fs.is_dir("path")  # -- Check if it is a directory

fs.is_file

• Function: Check if a path is a file
• Parameters: Path (string)
• Return Value: Boolean
• Example:

fs.is_file("path")  # -- Check if it is a file

Reading/Writing Functions (Read/Write)

fs.head

• Function: Read the first N lines of a file
• Parameters:
  • Number of lines (integer,default 10)
  • File path (string)
• Return Value: String
• Example:

fs.head(10, "log.txt")  # -- Read the first 10 lines

fs.tail

• Function: Read the last N lines of a file
• Parameters:
  • Number of lines (integer,default 10)
  • File path (string)
• Return Value: String
• Example:

fs.tail(10,"log.txt")  # -- Read the last 10 lines

fs.read

• Function: Read the content of a file
• Parameters: File path (string)
• Return Value: String (text file) or byte array (binary file)
• Example:

fs.read("file.txt")  # -- Read text file

fs.write

• Function: Write to a file (overwrite)
• Parameters:
  • File path (string)
  • Content (string or byte array)
• Return Value: None
• Example:

fs.write("file.txt", "content")  # -- Write text
fs.write("data.bin", bytes)      # -- Write binary

fs.append

• Function: Append content to a file
• Parameters:
  • File path (string)
  • Content (string or byte array)
• Return Value: None
• Example:

fs.append("log.txt", "new entry\n")  # -- Append text

Helper Functions

fs.base_name

• Function: Returns the file name from a given path
• Parameters:
  • Whether to split the extension (optional)
  • File path (string)
• Return Value: String
• Example:

fs.base_name("~/Documents/log.txt")  # -- Returns log.txt
fs.base_name(True, "~/Documents/log.tar.gz")  # -- Returns [log, tar.gz]

fs.join

• Function: Joins multiple paths
• Parameters:
  • File paths (strings), multiple
• Return Value: String
• Example:

fs.join("~", "Documents/mydoc", "log.txt")  # -- Returns "~/Documents/mydoc/log.txt"

Other

Error Handling

When operations fail, an error message will be returned, including detailed failure reasons and path information.

Platform Differences

• Unix-specific features: User ID, permission mode, symbolic link targets, etc.
• Windows platform will ignore Unix-specific parameters.