(ns Access
  "Elixir Access module — nested data access and update.

   In CljElixir: Provides access functions used with get-in, update-in, etc.
   Access functions create composable paths for nested data manipulation.")

(defn key
  "Accesses a key in a map. Returns `default` if key is missing.
   (get-in data [(Access/key :user) (Access/key :name)])"
  ([key])
  ([key default]))

(defn key!
  "Accesses a key in a map. Raises if key is missing."
  [key])

(defn elem
  "Accesses an element in a tuple by index.
   (get-in data [(Access/elem 0)])"
  [index])

(defn at
  "Accesses an element in a list by index.
   (get-in data [(Access/at 0)])"
  ([index])
  ([index default]))

(defn at!
  "Accesses a list element by index. Raises on out of bounds."
  [index])

(defn all
  "Accesses all elements in a list.
   (get-in data [(Access/all)])"
  [])

(defn filter
  "Filters elements in a list.
   (update-in data [(Access/filter (fn [x] (> x 2)))] inc)"
  [fun])

(defn find
  "Finds the first element matching `fun`.
   (get-in data [(Access/find (fn [x] (> x 2)))])"
  [fun])

(defn slice
  "Accesses a slice of a list.
   (get-in data [(Access/slice 1 3)])"
  [range-or-index])

(defn pop
  "Pops a key from a map or index from a list."
  [key])

(defn fetch
  "Fetches a value with {:ok value} or :error semantics."
  [container key])

(defn fetch!
  "Fetches a value. Raises on missing key."
  [container key])

(defn get
  "Gets a value from a container with optional default."
  ([container key])
  ([container key default]))

(defn get-and-update
  "Gets and updates a key in one operation."
  [container key fun])

(defn get-and-update!
  "Gets and updates. Raises if container doesn't implement Access."
  [container key fun])