Utils.Fn.FileSystem

Overview

The Utils.Fn module offers a comprehensive set of user-defined utility functions tailored for use within the Wezterm environment. It includes functionalities for handling file system operations, determining platform-specific details, and managing path-related tasks.

Usage

local Utils = require "utils.fn"

-- Determine the platform
local platform = Utils.fs.platform()
print(platform.os) -- Output: "windows", "linux", or "mac"

-- Get the user home directory
local home_dir = Utils.fs.home()
print(home_dir) -- Output: User home directory path

-- Shorten a path
local short_path = Utils.fs.pathshortener("/some/very/long/path/to/file", 10)
print(short_path) -- Output: Shortened path

-- Read files in a directory
local files = Utils.fs.read_dir "/path/to/your/directory"
for _, file in ipairs(files) do
  print(file)
end

Features

• Platform Detection: Identifies the operating system and platform specifics.
• Home Directory Retrieval: Provides a consistent way to access the user’s home directory.
• Path Manipulation: Includes functions to shorten paths, concatenate paths, and read directory contents.
• Git Project Detection: Finds the root directory of a Git project.
• Memoization: Caches values to improve performance and avoid redundant computations.

Class Structure

The Utils.Fn module provides various functions grouped into a file system operations class.

Functions

.platform()

Determines the platform based on the target triple.

This function checks the target triple string to determine if the platform is Windows, Linux, or macOS.

Returns:

• platform [Utils.Fn.FileSystem.Platform] - platform object:
  • os ["windows"|"linux"|"mac"|"unknown"] - operating system name.
  • is_win [boolean] - whether the platform is Windows.
  • is_linux [boolean] - whether the platform is Linux.
  • is_mac [boolean] - whether the platform is MacOS.

.home()

This function retrieves the home directory path from environment variables or fallback sources and replaces backslashes with forward slashes.

Returns:

• home [string] - path to user home directory

.basename(path)

Extracts the base name (the final component) from a given path.

Parameters:

• path [string] - Any string representing a path.

Returns:

• str [string] - The base name of the path.

Example:

local base_name = Utils.fs.basename("/path/to/file.txt")
print(base_name)  -- Output: "file.txt"

.find_git_dir(directory)

Searches for the Git project root directory by traversing up the directory tree.

Parameters:

• directory [string] - The directory path to start searching from.

Returns:

• git_root [string|nil] - The Git root directory if found, otherwise nil.

Example:

local git_root = Utils.fs.find_git_dir("/path/to/project")
print(git_root)  -- Output: Git root directory or nil

.get_cwd_hostname(pane, search_git_root_instead)

Retrieves the current working directory and hostname from a Wezterm pane object. Optionally searches for the Git root instead.

Parameters:

• pane [table] - The Wezterm pane object.
• search_git_root_instead [boolean] - Whether to search for the Git root instead.

Returns:

• cwd [string] - The current working directory.
• hostname [string] - The hostname.

Example:

local cwd, hostname = Utils.fs.get_cwd_hostname(pane, true)
print(cwd, hostname)

.pathshortener(path, len)

Shortens each component of a given path to a specified length.

Parameters:

• path [string] - The path to shorten.
• len [number] - The maximum length for each component of the path.

Returns:

• short_path [string] - The shortened path.

Example:

local short_path = Utils.fs.pathshortener("/some/very/long/path/to/file", 10)
print(short_path)  -- Output: "/some/very/lon/path/to/file"

.pathconcat(...)

Concatenates a vararg list of values into a single path string.

Parameters:

• ... [string] - The parts of the path to concatenate.

Returns:

• path [string] - The concatenated path.

Example:

local full_path = Utils.fs.pathconcat("/path", "to", "file.txt")
print(full_path)  -- Output: "/path/to/file.txt"

.read_dir(directory)

Reads the contents of a directory and returns a list of absolute filenames.

Parameters:

• directory [string] - Absolute path to the directory to read.

Returns:

• files [table|nil] - A list of files present in the directory or nil if not accessible.

Example:

local files = Utils.fs.read_dir("/path/to/your/directory")
for _, file in ipairs(files) do
  print(file)
end