Depot (Depot v0.5.2) View Source

Depot is a filesystem abstraction for elixir providing a unified interface over many implementations. It allows you to swap out filesystems on the fly without needing to rewrite all of your application code in the process. It can eliminate vendor-lock in, reduce technical debt, and improve the testability of your code.

This library is based on the ideas of flysystem, which is a PHP library providing similar functionality.

Examples

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: prefix
end

LocalFileSystem.write("test.txt", "Hello World")
{:ok, "Hello World"} = LocalFileSystem.read("test.txt")

Visibility

Depot does by default only deal with a limited, but portable, set of visibility permissions:

  • :public
  • :private

For more details and how to apply custom visibility permissions take a look at Depot.Visibility

Options

The following write options apply to all adapters:

  • :visibility - Set the visibility for files written
  • :directory_visibility - Set the visibility for directories written (if applicable)

Link to this section Summary

Functions

Clear the filesystem.

Copy a file from source to destination on a filesystem

Copy a file from one filesystem to the other

Delete a file from a filesystem

Copy a file from source to destination on a filesystem

List the contents of a folder on a filesystem

Move a file from source to destination on a filesystem

Read from a filesystem

Returns a Stream for reading the given path.

Returns a Stream for writing to the given path.

Link to this section Types

Specs

adapter() :: module()

Specs

filesystem() :: {module(), Depot.Adapter.config()}

Link to this section Functions

Specs

clear(filesystem(), keyword()) :: :ok | {:error, term()}

Clear the filesystem.

This is always recursive.

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
:ok = Depot.clear(filesystem)

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

LocalFileSystem.clear()
Link to this function

copy(arg, source, destination, opts \\ [])

View Source

Specs

copy(filesystem(), Path.t(), Path.t(), keyword()) :: :ok | {:error, term()}

Copy a file from source to destination on a filesystem

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
:ok = Depot.copy(filesystem, "test.txt", "other-test.txt")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

:ok = LocalFileSystem.copy("test.txt", "other-test.txt")
Link to this function

copy_between_filesystem(source, destination, opts \\ [])

View Source

Specs

copy_between_filesystem(
  source :: {filesystem(), Path.t()},
  destination :: {filesystem(), Path.t()},
  keyword()
) :: :ok | {:error, term()}

Copy a file from one filesystem to the other

This can either be done natively if the same adapter is used for both filesystems or by streaming/read-write cycle the file from the source to the local system and back to the destination.

Examples

Direct filesystem

filesystem_source = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
filesystem_destination = Depot.Adapter.Local.configure(prefix: "/home/user/storage2")
:ok = Depot.copy_between_filesystem({filesystem_source, "test.txt"}, {filesystem_destination, "copy.txt"})

Module-based filesystem

defmodule LocalSourceFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

defmodule LocalDestinationFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage2"
end

:ok = Depot.copy_between_filesystem(
  {LocalSourceFileSystem.__filesystem__(), "test.txt"},
  {LocalDestinationFileSystem.__filesystem__(), "copy.txt"}
)
Link to this function

create_directory(arg, path, opts \\ [])

View Source

Specs

create_directory(filesystem(), Path.t(), keyword()) :: :ok | {:error, term()}

Create a directory

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
:ok = Depot.create_directory(filesystem, "test/")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

LocalFileSystem.create_directory("test/")
Link to this function

delete(arg, path, opts \\ [])

View Source

Specs

delete(filesystem(), Path.t(), keyword()) :: :ok | {:error, term()}

Delete a file from a filesystem

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
:ok = Depot.delete(filesystem, "test.txt")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

:ok = LocalFileSystem.delete("test.txt")
Link to this function

delete_directory(arg, path, opts \\ [])

View Source

Specs

delete_directory(filesystem(), Path.t(), keyword()) :: :ok | {:error, term()}

Delete a directory.

Options

  • :recursive - Recursively delete contents. Defaults to false.

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
:ok = Depot.delete_directory(filesystem, "test/")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

LocalFileSystem.delete_directory("test/")
Link to this function

file_exists(arg, path, opts \\ [])

View Source

Specs

file_exists(filesystem(), Path.t(), keyword()) ::
  {:ok, :exists | :missing} | {:error, term()}

Copy a file from source to destination on a filesystem

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
:ok = Depot.copy(filesystem, "test.txt", "other-test.txt")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

:ok = LocalFileSystem.copy("test.txt", "other-test.txt")
Link to this function

list_contents(arg, path, opts \\ [])

View Source

Specs

list_contents(filesystem(), Path.t(), keyword()) ::
  {:ok,
   [
     %Depot.Stat.Dir{
       mtime: term(),
       name: term(),
       size: term(),
       visibility: term()
     }
     | %Depot.Stat.File{
         mtime: term(),
         name: term(),
         size: term(),
         visibility: term()
       }
   ]}
  | {:error, term()}

List the contents of a folder on a filesystem

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
{:ok, contents} = Depot.list_contents(filesystem, ".")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

{:ok, contents} = LocalFileSystem.list_contents(".")
Link to this function

move(arg, source, destination, opts \\ [])

View Source

Specs

move(filesystem(), Path.t(), Path.t(), keyword()) :: :ok | {:error, term()}

Move a file from source to destination on a filesystem

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
:ok = Depot.move(filesystem, "test.txt", "other-test.txt")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

:ok = LocalFileSystem.move("test.txt", "other-test.txt")
Link to this function

read(arg, path, opts \\ [])

View Source

Specs

read(filesystem(), Path.t(), keyword()) :: {:ok, binary()} | {:error, term()}

Read from a filesystem

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
{:ok, "Hello World"} = Depot.read(filesystem, "test.txt")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

{:ok, "Hello World"} = LocalFileSystem.read("test.txt")
Link to this function

read_stream(arg, path, opts \\ [])

View Source

Returns a Stream for reading the given path.

Options

The following stream options apply to all adapters:

  • :chunk_size - When reading, the amount to read, usually expressed as a number of bytes.

Examples

Note: The shape of the returned stream will necessarily depend on the adapter in use. In the following examples the Local adapter is invoked, which returns a File.Stream.

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
{:ok, %File.Stream{}} = Depot.read_stream(filesystem, "test.txt")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

{:ok, %File.Stream{}} = LocalFileSystem.read_stream("test.txt")
Link to this function

set_visibility(arg, path, visibility)

View Source

Specs

set_visibility(filesystem(), Path.t(), Depot.Visibility.t()) ::
  :ok | {:error, term()}

Specs

visibility(filesystem(), Path.t()) ::
  {:ok, Depot.Visibility.t()} | {:error, term()}
Link to this function

write(arg, path, contents, opts \\ [])

View Source

Specs

write(filesystem(), Path.t(), iodata(), keyword()) :: :ok | {:error, term()}

Write to a filesystem

Examples

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
:ok = Depot.write(filesystem, "test.txt", "Hello World")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

LocalFileSystem.write("test.txt", "Hello World")
Link to this function

write_stream(arg, path, opts \\ [])

View Source

Returns a Stream for writing to the given path.

Options

The following stream options apply to all adapters:

  • :chunk_size - When reading, the amount to read, usually expressed as a number of bytes.

Examples

Note: The shape of the returned stream will necessarily depend on the adapter in use. In the following examples the Local adapter is invoked, which returns a File.Stream.

Direct filesystem

filesystem = Depot.Adapter.Local.configure(prefix: "/home/user/storage")
{:ok, %File.Stream{}} = Depot.write_stream(filesystem, "test.txt")

Module-based filesystem

defmodule LocalFileSystem do
  use Depot.Filesystem,
    adapter: Depot.Adapter.Local,
    prefix: "/home/user/storage"
end

{:ok, %File.Stream{}} = LocalFileSystem.write_stream("test.txt")