Sprites.Filesystem (Sprites v0.2.0)

Filesystem operations for sprites.

Provides file and directory operations similar to Elixir's File module, but operating on files within a sprite container.

Usage

fs = Sprites.filesystem(sprite, "/app")
{:ok, content} = Sprites.Filesystem.read(fs, "config.json")
:ok = Sprites.Filesystem.write(fs, "output.txt", "data")

Working Directory

The filesystem struct includes a working directory that serves as the base for relative paths. Absolute paths (starting with /) are used as-is.

Summary

Types

t()

Functions

%Sprites.Filesystem{}

Represents a filesystem handle for a sprite.

chmod(fs, path, mode, opts \\ [])

Changes file permissions.

chmod!(fs, path, mode, opts \\ [])

Changes file permissions, raising on error.

cp(fs, source, dest, opts \\ [])

Copies a file or directory.

cp!(fs, source, dest, opts \\ [])

Copies a file or directory, raising on error.

ls(fs, path)

Lists directory contents.

ls!(fs, path)

Lists directory contents, raising on error.

mkdir_p(fs, path)

Creates directories recursively (like mkdir -p).

mkdir_p!(fs, path)

Creates directories recursively, raising on error.

new(sprite, working_dir \\ "/")

Creates a new filesystem handle for a sprite.

read(fs, path)

Reads the contents of a file.

read!(fs, path)

Reads the contents of a file, raising on error.

rename(fs, source, dest)

Renames a file or directory.

rename!(fs, source, dest)

Renames a file or directory, raising on error.

rm(fs, path)

Removes a single file (not recursive).

rm!(fs, path)

Removes a single file, raising on error.

rm_rf(fs, path)

Removes files or directories recursively (like rm -rf).

rm_rf!(fs, path)

Removes files or directories recursively, raising on error.

stat(fs, path)

Gets file or directory information.

stat!(fs, path)

Gets file or directory information, raising on error.

write(fs, path, data, opts \\ [])

Writes data to a file.

write!(fs, path, data, opts \\ [])

Writes data to a file, raising on error.

Types

t()

@type t() :: %Sprites.Filesystem{sprite: Sprites.Sprite.t(), working_dir: String.t()}

Functions

%Sprites.Filesystem{}

(struct)

Represents a filesystem handle for a sprite.

Fields

:sprite - The sprite this filesystem operates on
:working_dir - The working directory for relative paths

chmod(fs, path, mode, opts \\ [])

@spec chmod(t(), String.t(), non_neg_integer(), keyword()) :: :ok | {:error, term()}

Changes file permissions.

Options

:recursive - Apply to directory contents recursively (default: false)

Examples

:ok = Sprites.Filesystem.chmod(fs, "script.sh", 0o755)

chmod!(fs, path, mode, opts \\ [])

@spec chmod!(t(), String.t(), non_neg_integer(), keyword()) :: :ok

Changes file permissions, raising on error.

Examples

Sprites.Filesystem.chmod!(fs, "script.sh", 0o755)

cp(fs, source, dest, opts \\ [])

@spec cp(t(), String.t(), String.t(), keyword()) :: :ok | {:error, term()}

Copies a file or directory.

Options

:recursive - Copy directories recursively (default: false)

Examples

:ok = Sprites.Filesystem.cp(fs, "src.txt", "dst.txt")
:ok = Sprites.Filesystem.cp(fs, "src_dir", "dst_dir", recursive: true)

cp!(fs, source, dest, opts \\ [])

@spec cp!(t(), String.t(), String.t(), keyword()) :: :ok

Copies a file or directory, raising on error.

Examples

Sprites.Filesystem.cp!(fs, "src.txt", "dst.txt")

ls(fs, path)

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

Lists directory contents.

Examples

{:ok, entries} = Sprites.Filesystem.ls(fs, "/app")

ls!(fs, path)

@spec ls!(t(), String.t()) :: [map()]

Lists directory contents, raising on error.

Examples

entries = Sprites.Filesystem.ls!(fs, "/app")

mkdir_p(fs, path)

@spec mkdir_p(t(), String.t()) :: :ok | {:error, term()}

Creates directories recursively (like mkdir -p).

Examples

:ok = Sprites.Filesystem.mkdir_p(fs, "deep/nested/path")

mkdir_p!(fs, path)

@spec mkdir_p!(t(), String.t()) :: :ok

Creates directories recursively, raising on error.

Examples

Sprites.Filesystem.mkdir_p!(fs, "deep/nested/path")

new(sprite, working_dir \\ "/")

@spec new(Sprites.Sprite.t(), String.t()) :: t()

Creates a new filesystem handle for a sprite.

Examples

fs = Sprites.Filesystem.new(sprite, "/app")

read(fs, path)

@spec read(t(), String.t()) :: {:ok, binary()} | {:error, term()}

Reads the contents of a file.

Examples

{:ok, content} = Sprites.Filesystem.read(fs, "config.json")
{:error, :enoent} = Sprites.Filesystem.read(fs, "missing.txt")

read!(fs, path)

@spec read!(t(), String.t()) :: binary()

Reads the contents of a file, raising on error.

Examples

content = Sprites.Filesystem.read!(fs, "config.json")

rename(fs, source, dest)

@spec rename(t(), String.t(), String.t()) :: :ok | {:error, term()}

Renames a file or directory.

Examples

:ok = Sprites.Filesystem.rename(fs, "old.txt", "new.txt")

rename!(fs, source, dest)

@spec rename!(t(), String.t(), String.t()) :: :ok

Renames a file or directory, raising on error.

Examples

Sprites.Filesystem.rename!(fs, "old.txt", "new.txt")

rm(fs, path)

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

Removes a single file (not recursive).

Examples

:ok = Sprites.Filesystem.rm(fs, "file.txt")

rm!(fs, path)

@spec rm!(t(), String.t()) :: :ok

Removes a single file, raising on error.

Examples

Sprites.Filesystem.rm!(fs, "file.txt")

rm_rf(fs, path)

@spec rm_rf(t(), String.t()) :: :ok | {:error, term()}

Removes files or directories recursively (like rm -rf).

Examples

:ok = Sprites.Filesystem.rm_rf(fs, "directory")

rm_rf!(fs, path)

@spec rm_rf!(t(), String.t()) :: :ok

Removes files or directories recursively, raising on error.

Examples

Sprites.Filesystem.rm_rf!(fs, "directory")

stat(fs, path)

@spec stat(t(), String.t()) :: {:ok, map()} | {:error, term()}

Gets file or directory information.

Returns a map with file stats including:

"name" - File/directory name
"size" - Size in bytes
"mode" - File permissions
"isDir" - Whether it's a directory
"modTime" - Modification time

Examples

{:ok, stat} = Sprites.Filesystem.stat(fs, "file.txt")
IO.inspect(stat["size"])

stat!(fs, path)

@spec stat!(t(), String.t()) :: map()

Gets file or directory information, raising on error.

Examples

stat = Sprites.Filesystem.stat!(fs, "file.txt")

write(fs, path, data, opts \\ [])

@spec write(t(), String.t(), iodata(), keyword()) :: :ok | {:error, term()}

Writes data to a file.

Creates parent directories if they don't exist.

Options

:mode - File permissions (default: 0o644)

Examples

:ok = Sprites.Filesystem.write(fs, "output.txt", "hello world")
:ok = Sprites.Filesystem.write(fs, "script.sh", "#!/bin/bash", mode: 0o755)

write!(fs, path, data, opts \\ [])

@spec write!(t(), String.t(), iodata(), keyword()) :: :ok

Writes data to a file, raising on error.

Examples

Sprites.Filesystem.write!(fs, "output.txt", "hello world")