Initial commit of Stash

.gitignore

@@ -0,0 +1,8 @@
+/_build
+/_native
+/bench
+/cover
+/deps
+/doc
+erl_crash.dump
+*.ez

.travis.yml

@@ -0,0 +1,9 @@
+language: elixir
+elixir:
+  - 1.2.1
+  - 1.1.1
+otp_release:
+  - 18.2
+  - 18.1
+script:
+  - mix test --trace

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Isaac Whitfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,80 @@
+# Stash
+[![Build Status](https://travis-ci.org/zackehh/stash.svg?branch=master)](https://travis-ci.org/zackehh/stash)
+
+A very small wrapping implementation around ETS, providing a more user-friendly key/value interface for new users. Takes care of setting up a new ETS table as needed with a default set of options to avoid having to deal with configurations. This library is meant as a fast way to use ETS without anything flashy, so don't expect many features over what's already here (which isn't much, intentionally).
+
+## Installation
+
+This package can be installed via Hex, just add stash to your list of dependencies in `mix.exs`:
+
+```elixir
+def deps do
+  [{:stash, "~> 1.0.0"}]
+end
+```
+
+## Quick Usage
+
+It's straightforward to get going:
+
+```elixir
+iex(1)> Stash.set(:my_cache, "my_key", "my_value")
+true
+iex(2)> Stash.get(:my_cache, "my_key")
+"my_value"
+iex(3)> Stash.delete(:my_cache, "my_key")
+true
+iex(4)> Stash.get(:my_cache, "my_key")
+nil
+```
+
+For further examples, as well as the rest of the API, please see the [documentation](http://hexdocs.pm/stash/Stash.html).
+
+## A Note On Table Configuration
+
+By default, Stash will create a table with the following configuration:
+
+```elixir
+[
+  { :read_concurrency, true },
+  { :write_concurrency, true },
+  :public,
+  :set,
+  :named_table
+]
+```
+
+If you **don't** wish to have this configuration, please create your ETS table in advance of using Stash to access it. However keep in mind that Stash is written with the assumption that you're using either a `set` or `ordered_set`, so it's best to stick to those. The defaults should be ok in most cases, so unless you're already thinking that you want a setting changed above, you're probably fine.
+
+## Persistence
+
+A neat little feature is the ability to persist a cache to disk, by calling `Stash.persist/2`. This will move your ETS tables into DTS, allowing you to reload after your process has died. This is not kept in sync due to the overhead involved, so it might be an idea to schedule persistance if you rely on it. To reload, call `Stash.load/2`.
+
+```elixir
+iex(1)> Stash.set(:my_cache, "key", "value")
+true
+iex(2)> Stash.size(:my_cache)
+1
+iex(3)> Stash.persist(:my_cache, "/tmp/my_persistence_file")
+:ok
+iex(4)> Stash.delete(:my_cache, "key")
+true
+iex(5)> Stash.size(:my_cache)
+0
+iex(6)> Stash.load(:my_cache, "/tmp/my_persistence_file")
+:ok
+iex(7)> Stash.size(:my_cache)
+1
+iex(1)> Stash.get(:my_cache, "key")
+"value"
+```
+
+## Issues/Contributions
+
+If you spot any issues with the implementation, please file an [issue](http://github.com/zackehh/stash/issues) or even a PR. Like I mentioned above, not too many features will make it into this lib as it's a small wrapping library, nothing special.
+
+Make sure to test your changes though!
+
+```bash
+$ mix test --trace
+```

lib/stash.ex

@@ -0,0 +1,265 @@
+defmodule Stash do
+  use Stash.Macros
+
+  @doc """
+  Retrieves a value from the cache.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key", "value")
+      iex> Stash.get(:my_cache, "key")
+      "value"
+
+      iex> Stash.get(:my_cache, "missing_key")
+      nil
+
+  """
+  @spec get(atom, any) :: any
+  deft get(cache, key) do
+    case :ets.lookup(cache, key) do
+      [{ ^key, value }] -> value
+      _unrecognised_val -> nil
+    end
+  end
+
+  @doc """
+  Retrieves all keys from the cache, and returns them as an (unordered) list.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key1", "value1")
+      iex> Stash.set(:my_cache, "key2", "value2")
+      iex> Stash.set(:my_cache, "key3", "value3")
+      iex> Stash.keys(:my_cache)
+      [ "key2", "key1", "key3" ]
+
+      iex> Stash.keys(:empty_cache)
+      []
+
+  """
+  @spec keys(atom) :: [any]
+  deft keys(cache) do
+    :ets.foldr(fn({ key, _value }, keys) ->
+      [key|keys]
+    end, [], cache)
+  end
+
+  @doc """
+  Sets a value in the cache against a given key.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key", "value")
+      true
+
+  """
+  @spec set(atom, any, any) :: true
+  deft set(cache, key, value) do
+    :ets.insert(cache, { key, value })
+  end
+
+  @doc """
+  Increments a key directly in the cache by `count`. If the key does not exist
+  it is set to `initial` before **then** being incremented.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key", 1)
+      iex> Stash.inc(:my_cache, "key")
+      2
+
+      iex> Stash.inc(:my_cache, "key", 2)
+      4
+
+      iex> Stash.inc(:my_cache, "missing_key", 1)
+      1
+
+      iex> Stash.inc(:my_cache, "a_missing_key", 1, 5)
+      6
+
+  """
+  @spec inc(atom, any, number, number) :: number
+  def inc(cache, key, count \\ 1, initial \\ 0)
+  deft inc(cache, key, count, initial)
+  when is_number(count) and is_number(initial) do
+    :ets.update_counter(
+      cache, key, { 2, count }, { key, initial }
+    )
+  end
+
+  @doc """
+  Removes a value from the cache.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key", "value")
+      iex> Stash.get(:my_cache, "key")
+      "value"
+
+      iex> Stash.delete(:my_cache, "key")
+      true
+
+      iex> Stash.get(:my_cache, "key")
+      nil
+
+  """
+  @spec delete(atom, any) :: true
+  deft delete(cache, key), do: :ets.delete(cache, key)
+
+  @doc """
+  Removes a key from the cache, whilst also returning the last known value.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key", "value")
+      iex> Stash.remove(:my_cache, "key")
+      "value"
+
+      iex> Stash.get(:my_cache, "key")
+      nil
+
+      iex> Stash.remove(:my_cache, "missing_key")
+      nil
+
+  """
+  @spec remove(atom, any) :: any
+  deft remove(cache, key) do
+    case :ets.take(cache, key) do
+      [{ ^key, value }] -> value
+      _unrecognised_val -> nil
+    end
+  end
+
+  @doc """
+  Removes all items in the cache.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key1", "value1")
+      iex> Stash.set(:my_cache, "key2", "value2")
+      iex> Stash.set(:my_cache, "key3", "value3")
+      iex> Stash.size(:my_cache)
+      3
+
+      iex> Stash.clear(:my_cache)
+      true
+
+      iex> Stash.size(:my_cache)
+      0
+
+  """
+  @spec clear(atom) :: true
+  deft clear(cache), do: :ets.delete_all_objects(cache)
+
+  @doc """
+  Returns information about the backing ETS table.
+
+  ## Examples
+
+      iex> Stash.info(:my_cache)
+      [read_concurrency: true, write_concurrency: true, compressed: false,
+       memory: 1361, owner: #PID<0.126.0>, heir: :none, name: :my_cache, size: 2,
+       node: :nonode@nohost, named_table: true, type: :set, keypos: 1,
+       protection: :public]
+
+  """
+  @spec info(atom) :: [ { atom, any } ]
+  deft info(cache), do: :ets.info(cache)
+
+  @doc """
+  Checks whether the cache is empty.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key1", "value1")
+      iex> Stash.set(:my_cache, "key2", "value2")
+      iex> Stash.set(:my_cache, "key3", "value3")
+      iex> Stash.empty?(:my_cache)
+      false
+
+      iex> Stash.clear(:my_cache)
+      true
+
+      iex> Stash.empty?(:my_cache)
+      true
+
+  """
+  @spec empty?(atom) :: true | false
+  deft empty?(cache), do: size(cache) == 0
+
+  @doc """
+  Determines whether a given key exists inside the cache.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key", "value")
+      iex> Stash.exists?(:my_cache, "key")
+      true
+
+      iex> Stash.exists?(:my_cache, "missing_key")
+      false
+
+  """
+  @spec exists?(atom, any) :: true | false
+  deft exists?(cache, key), do: :ets.member(cache, key)
+
+  @doc """
+  Determines the size of the cache.
+
+  ## Examples
+
+      iex> Stash.set(:my_cache, "key1", "value1")
+      iex> Stash.set(:my_cache, "key2", "value2")
+      iex> Stash.set(:my_cache, "key3", "value3")
+      iex> Stash.size(:my_cache)
+      3
+
+  """
+  @spec size(atom) :: number
+  deft size(cache), do: info(cache)[:size]
+
+  @doc """
+  Loads a cache into memory from DTS storage.
+
+  ## Examples
+
+      iex> Stash.load(:my_cache, "/tmp/temporary.dat")
+      :ok
+
+  """
+  @spec load(atom, binary) :: atom
+  deft load(cache, path) when is_binary(path) do
+    case :dets.open_file(path, gen_dts_args(cache)) do
+      { :ok, ^path } ->
+        :dets.to_ets(path, cache)
+        :dets.close(path)
+      error_state -> error_state
+    end
+  end
+
+  @doc """
+  Persists a cache onto disk to allow reload after the process dies.
+
+  ## Examples
+
+      iex> Stash.persist(:my_cache, "/tmp/temporary.dat")
+      :ok
+
+  """
+  @spec persist(atom, binary) :: atom
+  deft persist(cache, path) when is_binary(path) do
+    case :dets.open_file(path, gen_dts_args(cache)) do
+      { :ok, ^path } ->
+        :dets.from_ets(path, cache)
+        :dets.close(path)
+      error_state -> error_state
+    end
+  end
+
+  # Generates the arguments for a DTS table based on a passed in ETS table
+  defp gen_dts_args(cache) do
+    info = info(cache)
+    [ keypos: info[:keypos], type: info[:type] ]
+  end
+
+end