trunk
v1.4.0

View Source Trunk.State (trunk v1.4.0)

This module defines a Trunk.State struct and provides some helper functions for working with that state.

Fields

The following fields are available in the state object. Some values are filled in during processing.

  • filename - The base filename of the file being processed. (e.g. "photo.jpg")
  • rootname - The root of the filen being processed. (e.g. "photo")
  • extname - The file extension of the file being processed. (e.g. ".jpg")
  • lower_extname - The file extension of the file being processed forced to lower case (e.g. "*.jpg", even if the file is "PHOTO.JPG")
  • path - The full path to the file being processed. If the file was passed in as a binary, it is a path to the temporary file created with that binary.
  • versions - A map of the versions and their respective Trunk.VersionState (e.g. %{original: %Trunk.VersionState{}, thumbnail: %Trunk.VersionState{}})
  • scope - A user struct/map passed in useful for determining storage locations and file naming.
  • async - A boolean indicator of whether processing will be done in parallel.
  • timeout - The timeout after which each processing process will be terminated. (Only applies with async: true)
  • storage - The module to use for storage processing. (e.g. Trunk.Storage.Filesystem or Trunk.Storage.S3)
  • storage_opts - A keyword list of options for the storage module
  • errors - a place to record errors encountered during processing. (nli if no errors, otherwise a map of errors)
  • opts - All the options merged together (see Options in Trunk module documentation).
  • assigns - shared user data as a map (Same as assigns in Plug.Conn)

Summary

Types

assign_keys()
file_info()
opts()
save_opts()
t()
version()

Functions

assign(state, key, value)

Assigns a value to a key on the state.

get_version_assign(map, version, assign)

Retrieves an assign value for a specific version.

init(info, scope, opts)
put_error(state, version, stage, error)

Puts an error into the error map.

restore(file_info, opts \\ [])

Restore a saved state from a filename, JSON, or a map

save(state, opts \\ [])

Extracts the data needed from the state in order to reconstruct the file paths in future.

Types

Link to this type

assign_keys()

View Source 
@type assign_keys() :: [atom()]
Link to this type

file_info()

View Source 
@type file_info() :: String.t() | map()
Link to this type

opts()

View Source 
@type opts() :: Keyword.t()
Link to this type

save_opts()

View Source 
@type save_opts() :: [{:assigns, :all | assign_keys()}]
Link to this type

t()

View Source 
@type t() :: %Trunk.State{
  assigns: map(),
  async: boolean(),
  errors: Keyword.t(),
  extname: String.t(),
  filename: String.t(),
  lower_extname: String.t(),
  module: atom(),
  opts: opts(),
  path: String.t(),
  rootname: String.t(),
  scope: map() | struct(),
  storage: atom(),
  storage_opts: Keyword.t(),
  timeout: integer(),
  versions: map()
}
Link to this type

version()

View Source 
@type version() :: atom()

Functions

Link to this function

assign(state, key, value)

View Source 
@spec assign(state :: t(), key :: any(), value :: any()) :: map()

Assigns a value to a key on the state.

Example: 

iex> state.assigns[:hello]
nil
iex> state = Trunk.State.assign(state, :hello, :world)
iex> state.assigns[:hello]
:world
Link to this function

get_version_assign(map, version, assign)

View Source 
@spec get_version_assign(state :: t(), version(), assign :: atom()) :: any() | nil

Retrieves an assign value for a specific version.

Example: 

iex> state = %Trunk.State{versions: %{thumbnail: %Trunk.VersionState{assigns: %{hello: :world}}}}
iex> %Trunk.State.get_version_assign(state, :thumbnail, :hello)
:world
iex> %Trunk.State.get_version_assign(state, :thumbnail, :unknown)
nil
Link to this function

init(info, scope, opts)

View Source
Link to this function

put_error(state, version, stage, error)

View Source

Puts an error into the error map.

Example: 

iex> state.errors
nil
iex> state = Trunk.State.put_error(state, :thumb, :transform, "Error with convert blah blah")
iex> state.errors
%{thumb: [transform: "Error with convert blah blah"]}
Link to this function

restore(file_info, opts \\ [])

View Source 
@spec restore(file_info(), opts()) :: t()

Restore a saved state from a filename, JSON, or a map

Example: 

iex> Trunk.State.restore("photo.jpg")
%Trunk.State{filename: "photo.jpg"}
iex> Trunk.State.restore(%{filename: "photo.jpg", assigns: %{hash: "abcdef"}}
%Trunk.State{filename: "photo.jpg", assigns: %{hash: "abcdef"}}
iex> Trunk.State.restore(%{"filename" => "photo.jpg", "assigns" => %{"hash" => "abcdef"}}
%Trunk.State{filename: "photo.jpg", assigns: %{hash: "abcdef"}}
iex> Trunk.State.restore("{\"filename\": \"photo.jpg\", \"assigns\": {\"hash\": \"abcdef\"}}")
%Trunk.State{filename: "photo.jpg", assigns: %{hash: "abcdef"}}
Link to this function

save(state, opts \\ [])

View Source 
@spec save(t(), [{:as, :string} | save_opts()]) :: String.t()
@spec save(t(), [{:as, :json} | save_opts()]) :: String.t()
@spec save(t(), [{:as, :map} | save_opts()]) :: map()

Extracts the data needed from the state in order to reconstruct the file paths in future.

Options:

  • :as - How to save the state.
    • :string - Default, will just save the file name. An error will be raised if there are any assigns unless :ignore_assigns is set to tru
    • :map - will save a map with keys :filename, :assigns, and :version_assigns
    • :json - will save a map encoded as JSON (Requires Poison library to be included in deps)
  • :ignore_assigns boolean, default false. Use this to save as string and ignore any assigns (Make sure you’re not using assigns for Trunk.storage_dir/2 or Trunk.filename/2)
  • :assigns - a list of keys to save from the assigns hashes

Example: 

iex> Trunk.State.save(%Trunk.State{filename: "photo.jpg"})
"photo.jpg"
iex> Trunk.State.save(%Trunk.State{filename: "photo.jpg", assigns: %{hash: "abcdef"}}, as: :map)
%{filename: "photo.jpg", assigns: %{hash: "abcdef"}}
iex> Trunk.State.save(%Trunk.State{filename: "photo.jpg", assigns: %{hash: "abcdef", file_size: 12345}}, as: :map, assigns: [:hash])
%{filename: "photo.jpg", assigns: %{hash: "abcdef"}}
iex> Trunk.State.save(%Trunk.State{filename: "photo.jpg", assigns: %{hash: "abcdef"}}, as: :json)
"{\"filename\": \"photo.jpg\", \"assigns\": {\"hash\": \"abcdef\"}}"