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
Create a directory
Delete a file from a filesystem
Delete a directory.
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
.
Write to a filesystem
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()
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")
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"}
)
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/")
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")
Specs
delete_directory(filesystem(), Path.t(), keyword()) :: :ok | {:error, term()}
Delete a directory.
Options
:recursive
- Recursively delete contents. Defaults tofalse
.
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/")
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")
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(".")
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")
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")
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 aFile.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")
Specs
set_visibility(filesystem(), Path.t(), Depot.Visibility.t()) :: :ok | {:error, term()}
Specs
visibility(filesystem(), Path.t()) :: {:ok, Depot.Visibility.t()} | {:error, term()}
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")
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 aFile.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")