defmodule PropertyTable do
  @moduledoc File.read!("README.md")
             |> String.split("<!-- MODULEDOC -->")
             |> Enum.fetch!(1)

  alias PropertyTable.Updater

  @typedoc """
  A table_id identifies a group of properties
  """
  @type table_id() :: atom()

  @typedoc """
  Properties
  """
  @type property() :: any()
  @type pattern() :: any()
  @type value() :: any()
  @type property_value() :: {property(), value()}

  @typedoc """
  PropertyTable configuration options

  See `start_link/2` for usage.
  """
  @type option() ::
          {:name, table_id()} | {:properties, [property_value()]} | {:tuple_events, boolean()}

  @doc """
  Start a PropertyTable's supervision tree

  To create a PropertyTable for your application or library, add the following
  `child_spec` to one of your supervision trees:

  ```elixir
  {PropertyTable, name: MyTableName}
  ```

  The `:name` option is required. All calls to `PropertyTable` will need to
  know it and the process will be registered under than name so be sure it's
  unique.

  Additional options are:

  * `:properties` - a list of `{property, value}` tuples to initially populate
    the `PropertyTable`
  * `:matcher` - set the format for how properties and how they should be
    matched for triggering events. See `PropertyTable.Matcher`.
  * `:tuple_events` - set to `true` for change events to be in the old tuple
    format. This is not recommended for new code and hopefully will be removed
    in the future.

  Persistent options:

  * You MUST set at least `:persist_data_path` for any of the other options to be respected!
  * If the table can restore its data from disk, it will IGNORE your initial `:properties` value.

  * `:persist_data_path` - set to a directory where PropertyTable will
    persist the contents of the table to disk, snapshots will also be stored here.
  * `:persist_interval` - if set PropertyTable will persist the contents of
    tables to disk in intervals of the provided value (in milliseconds) automatically.
  * `:persist_max_snapshots` - Maximum number of manual snapshots to keep on disk before they
    are replaced - (oldest snapshots are replaced first.) Defaults to 25.
  * `:persist_compression` - `0..9` range to compress the terms when written to disk, see `:erlang.term_to_binary/2`. Defaults to 6.
  """
  @spec start_link([option()]) :: Supervisor.on_start()
  def start_link(options) do
    name =
      case Keyword.fetch(options, :name) do
        {:ok, name} when is_atom(name) ->
          name

        {:ok, other} ->
          raise ArgumentError, "expected :name to be an atom, got: #{inspect(other)}"

        :error ->
          raise ArgumentError, "expected :name option to be present"
      end

    tuple_events = Keyword.get(options, :tuple_events, false)

    unless is_boolean(tuple_events) do
      raise ArgumentError, "expected :tuple_events to be boolean, got: #{inspect(tuple_events)}"
    end

    matcher = Keyword.get(options, :matcher, PropertyTable.Matcher.StringPath)

    unless is_atom(matcher) do
      raise ArgumentError, "expected :matcher to be module, got: #{inspect(matcher)}"
    end

    properties = Keyword.get(options, :properties, [])

    unless Enum.all?(properties, fn {k, _} -> matcher.check_property(k) == :ok end) do
      raise ArgumentError,
            "expected :properties to contain valid properties, got: #{inspect(properties)}"
    end

    persistence_options = maybe_get_persistence_options(options)

    Supervisor.start_link(
      __MODULE__.Supervisor,
      %{
        table: name,
        properties: properties,
        tuple_events: tuple_events,
        matcher: matcher,
        persistence_options: persistence_options
      },
      name: name
    )
  end

  @doc """
  Returns a specification to start a property_table under a supervisor.
  See `Supervisor`.
  """
  @spec child_spec(keyword()) :: Supervisor.child_spec()
  def child_spec(opts) do
    %{
      id: Keyword.get(opts, :name, PropertyTable),
      start: {PropertyTable, :start_link, [opts]},
      type: :supervisor
    }
  end

  @doc """
  Subscribe to receive events
  """
  @spec subscribe(table_id(), pattern()) :: :ok
  def subscribe(table, pattern) do
    registry = PropertyTable.Supervisor.registry_name(table)
    {:ok, matcher} = Registry.meta(registry, :matcher)

    case matcher.check_pattern(pattern) do
      :ok ->
        {:ok, _} = Registry.register(registry, :subscriptions, pattern)
        :ok

      {:error, error} ->
        raise error
    end
  end

  @doc """
  Stop subscribing to a property
  """
  @spec unsubscribe(table_id(), pattern()) :: :ok
  def unsubscribe(table, pattern) do
    registry = PropertyTable.Supervisor.registry_name(table)
    Registry.unregister_match(registry, :subscriptions, pattern)
  end

  @doc """
  Get the current value of a property
  """
  @spec get(table_id(), property(), value()) :: value()
  def get(table, property, default \\ nil) do
    case :ets.lookup(table, property) do
      [{_property, value, _timestamp}] -> value
      [] -> default
    end
  end

  @doc """
  Fetch a property with the time that it was set

  Timestamps come from `System.monotonic_time()`
  """
  @spec fetch_with_timestamp(table_id(), property()) :: {:ok, value(), integer()} | :error
  def fetch_with_timestamp(table, property) do
    case :ets.lookup(table, property) do
      [{_property, value, timestamp}] -> {:ok, value, timestamp}
      [] -> :error
    end
  end

  @doc """
  Get all properties

  This function might return a really long list so it's mainly intended for
  debug or convenience when you know that the table only contains a few
  properties.
  """
  @spec get_all(table_id()) :: [{property(), value()}]
  def get_all(table) do
    :ets.foldl(
      fn {property, value, _timestamp}, acc -> [{property, value} | acc] end,
      [],
      table
    )
  end

  @doc """
  Get a list of all properties matching the specified property pattern
  """
  @spec match(table_id(), pattern()) :: [{property(), value()}]
  def match(table, pattern) do
    registry = PropertyTable.Supervisor.registry_name(table)
    {:ok, matcher} = Registry.meta(registry, :matcher)

    :ets.foldl(
      fn {property, value, _timestamp}, acc ->
        if matcher.matches?(pattern, property) do
          [{property, value} | acc]
        else
          acc
        end
      end,
      [],
      table
    )
  end

  @doc """
  Update a property and notify listeners
  """
  @spec put(table_id(), property(), value()) :: :ok
  defdelegate put(table, property, value), to: Updater

  @doc """
  Update many properties

  This is similar to calling `put/3` several times in a row, but atomically. It is
  also slightly more efficient when updating more than one property.
  """
  @spec put_many(table_id(), [{property(), value()}]) :: :ok
  defdelegate put_many(table, properties), to: Updater

  @doc """
  Delete the specified property
  """
  @spec delete(table_id(), property()) :: :ok
  defdelegate delete(table, property), to: Updater

  @doc """
  Delete all properties that match a pattern
  """
  @spec delete_matches(table_id(), pattern()) :: :ok
  defdelegate delete_matches(table, pattern), to: Updater

  @doc """
  If persistence is enabled for this property table, save the current state
  and copy a snapshot of it into the `/snapshots` sub-directory of the set
  data directory.
  """
  @spec snapshot(table_id()) :: {:ok, String.t()} | :noop
  defdelegate snapshot(table), to: Updater

  @doc """
  If persistence is enabled for this property table, save the current state
  to disk immediately.
  """
  @spec flush_to_disk(table_id()) :: :ok
  defdelegate flush_to_disk(table), to: Updater

  @doc """
  Returns a list of availiable snapshot IDs and full name tuples for
  a property table with persistence enable
  """
  @spec get_snapshots(table_id()) :: [{String.t(), String.t()}]
  defdelegate get_snapshots(table), to: Updater

  @doc """
  If persistence is enabled for this property table, restore the current state of the
  PropertyTable to that of a past named snapshot
  """
  @spec restore_snapshot(table_id(), String.t()) :: :ok | :noop
  defdelegate restore_snapshot(table, snapshot_name), to: Updater

  defp maybe_get_persistence_options(options) do
    if Keyword.has_key?(options, :persist_data_path) do
      table_name = Keyword.get(options, :name) |> Atom.to_string()

      # Set persistence options, and clean out any nil values
      # they will be filled with defaults in `PropertyTable.Persist`
      [
        data_directory: Keyword.get(options, :persist_data_path),
        table_name: table_name,
        interval: Keyword.get(options, :persist_interval),
        max_snapshots: Keyword.get(options, :persist_max_snapshots),
        compression: Keyword.get(options, :persist_compression)
      ]
      |> Enum.filter(fn {_, v} -> v != nil end)
    else
      # :persist_data_path must be set for any of the other options to be respected
      # no persistence will be configured
      nil
    end
  end
end