Jido.VFS.Filesystem behaviour (Jido.VFS v1.0.1)

Behaviour and delegation helpers for a Jido.VFS filesystem module.

Summary

Callbacks

access(path, modes)

Checks access for the given relative path.

append(path, contents, opts)

Appends contents to the given relative path.

clear(opts)

Clears the configured filesystem.

commit(message, opts)

Commits changes in version-aware filesystems.

copy(source, destination, opts)

Copies a file from one relative path to another.

create_directory(path, opts)

Creates a directory at the given relative path.

delete(path, opts)

Deletes the file at the given relative path.

delete_directory(path, opts)

Deletes a directory at the given relative path.

file_exists(path, opts)

Checks whether the given relative path exists.

list_contents(path, opts)

Lists the directory entries for the given relative path.

move(source, destination, opts)

Moves a file from one relative path to another.

read(path, opts)

Reads the file at the given relative path.

read_revision(path, revision, opts)

Reads a file as it existed at a specific revision.

read_stream(path, opts)

Opens a readable stream for the file at the given relative path.

revisions(path, opts)

Lists revisions for a relative path in version-aware filesystems.

rollback(revision, opts)

Rolls a version-aware filesystem back to a revision.

set_visibility(path, visibility)

Sets public/private visibility for the given relative path.

stat(path)

Reads file or directory metadata for the given relative path.

truncate(path, new_size)

Truncates the file at the given relative path.

utime(path, mtime)

Updates the modification time for the given relative path.

visibility(path)

Reads public/private visibility for the given relative path.

write(path, contents, opts)

Writes contents to the given relative path.

write_stream(path, opts)

Opens a writable stream for the given relative path.

Functions

__using__(opts)

Injects a filesystem wrapper module backed by a configured adapter.

merge_app_env(opts, module)

Merges adapter options with application environment overrides when :otp_app is present.

parse_opts(module, opts)

Merges compile-time options with module-specific runtime configuration and extracts the adapter.

Callbacks

access(path, modes)

@callback access(path :: Path.t(), modes :: [:read | :write]) :: :ok | {:error, term()}

Checks access for the given relative path.

append(path, contents, opts)

@callback append(path :: Path.t(), contents :: iodata(), opts :: keyword()) ::
  :ok | {:error, term()}

Appends contents to the given relative path.

clear(opts)

@callback clear(opts :: keyword()) :: :ok | {:error, term()}

Clears the configured filesystem.

commit(message, opts)

@callback commit(message :: String.t() | nil, opts :: keyword()) :: :ok | {:error, term()}

Commits changes in version-aware filesystems.

copy(source, destination, opts)

@callback copy(source :: Path.t(), destination :: Path.t(), opts :: keyword()) ::
  :ok | {:error, term()}

Copies a file from one relative path to another.

create_directory(path, opts)

@callback create_directory(path :: Path.t(), opts :: keyword()) :: :ok | {:error, term()}

Creates a directory at the given relative path.

delete(path, opts)

@callback delete(path :: Path.t(), opts :: keyword()) :: :ok | {:error, term()}

Deletes the file at the given relative path.

delete_directory(path, opts)

@callback delete_directory(path :: Path.t(), opts :: keyword()) :: :ok | {:error, term()}

Deletes a directory at the given relative path.

file_exists(path, opts)

@callback file_exists(path :: Path.t(), opts :: keyword()) ::
  {:ok, :exists | :missing} | {:error, term()}

Checks whether the given relative path exists.

list_contents(path, opts)

@callback list_contents(path :: Path.t(), opts :: keyword()) ::
  {:ok,
   [
     %Jido.VFS.Stat.Dir{
       mtime: term(),
       name: term(),
       size: term(),
       visibility: term()
     }
     | %Jido.VFS.Stat.File{
         mtime: term(),
         name: term(),
         size: term(),
         visibility: term()
       }
   ]}
  | {:error, term()}

Lists the directory entries for the given relative path.

move(source, destination, opts)

@callback move(source :: Path.t(), destination :: Path.t(), opts :: keyword()) ::
  :ok | {:error, term()}

Moves a file from one relative path to another.

read(path, opts)

@callback read(path :: Path.t(), opts :: keyword()) :: {:ok, binary()} | {:error, term()}

Reads the file at the given relative path.

read_revision(path, revision, opts)

@callback read_revision(path :: Path.t(), revision :: String.t(), opts :: keyword()) ::
  {:ok, binary()} | {:error, term()}

Reads a file as it existed at a specific revision.

read_stream(path, opts)

@callback read_stream(path :: Path.t(), opts :: keyword()) ::
  {:ok, Enumerable.t()} | {:error, term()}

Opens a readable stream for the file at the given relative path.

revisions(path, opts)

@callback revisions(path :: Path.t(), opts :: keyword()) ::
  {:ok, [Jido.VFS.Revision.t()]} | {:error, term()}

Lists revisions for a relative path in version-aware filesystems.

rollback(revision, opts)

@callback rollback(revision :: String.t(), opts :: keyword()) :: :ok | {:error, term()}

Rolls a version-aware filesystem back to a revision.

set_visibility(path, visibility)

@callback set_visibility(path :: Path.t(), visibility :: Jido.VFS.Visibility.t()) ::
  :ok | {:error, term()}

Sets public/private visibility for the given relative path.

stat(path)

@callback stat(path :: Path.t()) ::
  {:ok,
   %Jido.VFS.Stat.File{
     mtime: term(),
     name: term(),
     size: term(),
     visibility: term()
   }
   | %Jido.VFS.Stat.Dir{
       mtime: term(),
       name: term(),
       size: term(),
       visibility: term()
     }}
  | {:error, term()}

Reads file or directory metadata for the given relative path.

truncate(path, new_size)

@callback truncate(path :: Path.t(), new_size :: non_neg_integer()) ::
  :ok | {:error, term()}

Truncates the file at the given relative path.

utime(path, mtime)

@callback utime(path :: Path.t(), mtime :: DateTime.t()) :: :ok | {:error, term()}

Updates the modification time for the given relative path.

visibility(path)

@callback visibility(path :: Path.t()) ::
  {:ok, Jido.VFS.Visibility.t()} | {:error, term()}

Reads public/private visibility for the given relative path.

write(path, contents, opts)

@callback write(path :: Path.t(), contents :: iodata(), opts :: keyword()) ::
  :ok | {:error, term()}

Writes contents to the given relative path.

write_stream(path, opts)

@callback write_stream(path :: Path.t(), opts :: keyword()) ::
  {:ok, Collectable.t()} | {:error, term()}

Opens a writable stream for the given relative path.

Functions

using(opts)

(macro)

@spec __using__(Macro.t()) :: Macro.t()

Injects a filesystem wrapper module backed by a configured adapter.

merge_app_env(opts, module)

@spec merge_app_env(
  keyword(),
  module()
) :: keyword()

Merges adapter options with application environment overrides when :otp_app is present.

parse_opts(module, opts)

@spec parse_opts(
  module(),
  keyword()
) :: {module(), keyword()}

Merges compile-time options with module-specific runtime configuration and extracts the adapter.