Raxol.Commands.FileSystem (Raxol v2.6.0)

Pure functional in-memory virtual file system.

Every operation takes a filesystem struct and returns {:ok, result} or {:error, reason}. The struct is immutable -- mutations return a new copy.

Internally uses a flat map keyed by absolute path for O(1) lookups.

Example

fs = FileSystem.new()
{:ok, fs} = FileSystem.mkdir(fs, "/docs")
{:ok, fs} = FileSystem.create_file(fs, "/docs/readme.txt", "Hello")
{:ok, entries} = FileSystem.ls(fs, "/docs")
{:ok, content} = FileSystem.cat(fs, "/docs/readme.txt")

Summary

Types

node_entry()

node_type()

stat_info()

t()

timestamp()

tree_node()

Functions

cat(fs, path)

Read the content of a file.

cd(fs, path)

Change the current working directory. Supports absolute paths, relative paths, .. (parent), and - (previous directory).

create_file(fs, path, content)

Create a file at path with content. Parent directory must exist.

exists?(fs, path)

Check if a path exists.

format_cat(content, max_width, max_height)

Format file content for terminal display. Returns a list of {line, line_number} tuples, truncated to fit max_width and max_height.

format_ls(entries, fs, dir_path)

Format ls output for terminal display. Returns a list of styled line tuples {text, style} where style is :directory or :file.

ls(fs, path \\ ".")

List entries in a directory. Returns {:ok, entries} where entries is a sorted list of child names.

mkdir(fs, path)

Create a directory at path. Parent directories must exist.

new()

Create a new filesystem with an empty root directory.

pwd(file_system)

Return the current working directory.

rm(fs, path)

Remove a file or empty directory at path.

stat(fs, path)

Return metadata for the node at path.

tree(fs, path \\ "/", depth \\ 3)

Return a tree representation of the directory at path, limited to depth levels. Returns {:ok, tree_node} where tree_node is {name, type, children}.

Types

node_entry()

@type node_entry() :: %{
  type: node_type(),
  created_at: timestamp(),
  modified_at: timestamp(),
  size: non_neg_integer(),
  content: String.t() | nil,
  children: [String.t()] | nil
}

node_type()

@type node_type() :: :file | :directory

stat_info()

@type stat_info() :: %{
  type: node_type(),
  size: non_neg_integer(),
  created_at: timestamp(),
  modified_at: timestamp(),
  path: String.t()
}

t()

@type t() :: %Raxol.Commands.FileSystem{
  cwd: String.t(),
  nodes: %{required(String.t()) => node_entry()},
  prev_dir: String.t() | nil
}

timestamp()

@type timestamp() :: integer()

tree_node()

@type tree_node() :: {String.t(), node_type(), [tree_node()]}

Functions

cat(fs, path)

@spec cat(t(), String.t()) :: {:ok, String.t()} | {:error, atom()}

Read the content of a file.

cd(fs, path)

@spec cd(t(), String.t()) :: {:ok, t()} | {:error, atom()}

Change the current working directory. Supports absolute paths, relative paths, .. (parent), and - (previous directory).

create_file(fs, path, content)

@spec create_file(t(), String.t(), String.t()) :: {:ok, t()} | {:error, atom()}

Create a file at path with content. Parent directory must exist.

exists?(fs, path)

@spec exists?(t(), String.t()) :: boolean()

Check if a path exists.

format_cat(content, max_width, max_height)

@spec format_cat(String.t(), pos_integer(), pos_integer()) :: [
  {String.t(), pos_integer()}
]

Format file content for terminal display. Returns a list of {line, line_number} tuples, truncated to fit max_width and max_height.

Note: uses String.length/1 (grapheme count) for truncation. For CJK-accurate display width, the render pipeline handles this via Raxol.UI.TextMeasure.

format_ls(entries, fs, dir_path)

@spec format_ls([String.t()], t(), String.t()) :: [{String.t(), atom()}]

Format ls output for terminal display. Returns a list of styled line tuples {text, style} where style is :directory or :file.

ls(fs, path \\ ".")

@spec ls(t(), String.t()) :: {:ok, [String.t()]} | {:error, atom()}

List entries in a directory. Returns {:ok, entries} where entries is a sorted list of child names.

mkdir(fs, path)

@spec mkdir(t(), String.t()) :: {:ok, t()} | {:error, atom()}

Create a directory at path. Parent directories must exist.

new()

@spec new() :: t()

Create a new filesystem with an empty root directory.

pwd(file_system)

@spec pwd(t()) :: String.t()

Return the current working directory.

rm(fs, path)

@spec rm(t(), String.t()) :: {:ok, t()} | {:error, atom()}

Remove a file or empty directory at path.

stat(fs, path)

@spec stat(t(), String.t()) :: {:ok, stat_info()} | {:error, atom()}

Return metadata for the node at path.

tree(fs, path \\ "/", depth \\ 3)

@spec tree(t(), String.t(), non_neg_integer()) ::
  {:ok, tree_node()} | {:error, atom()}

Return a tree representation of the directory at path, limited to depth levels. Returns {:ok, tree_node} where tree_node is {name, type, children}.