{-# OPTIONS_HADDOCK prune not-home #-}

{- |
Copyright   : (c) 2018-2022 Tim Emiola
SPDX-License-Identifier: BSD3
Maintainer  : Tim Emiola <tim@emio.la>

Declares the abstract @'Handle'@ and combinators used to load and save keyed values.
-}
module KeyedVals.Handle (
  -- * 'Handle' and related types and functions
  Handle (),
  HandleErr (..),
  countKVs,
  loadVal,
  saveVal,
  loadKVs,
  saveKVs,
  updateKVs,
  loadSlice,
  loadFrom,
  saveTo,
  deleteKeys,
  deleteKeysFrom,
  deleteMatches,
  deleteMatchesFrom,
  deleteSelected,
  deleteSelectedFrom,
  close,

  -- * 'Selection' and 'Glob'
  Selection (..),
  Glob,
  mkGlob,
  globPattern,
  isIn,

  -- * aliases used by the 'Handle' functions
  Key,
  Val,
  ValsByKey,
) where

import Data.List.NonEmpty (NonEmpty)
import KeyedVals.Handle.Internal
import Numeric.Natural (Natural)


-- | Loads the saved 'Val' corresponding to a 'Key'.
loadVal :: Handle m -> Key -> m (Either HandleErr (Maybe Val))
loadVal :: forall (m :: * -> *).
Handle m -> Key -> m (Either HandleErr (Maybe Key))
loadVal = forall (m :: * -> *).
Handle m -> Key -> m (Either HandleErr (Maybe Key))
hLoadVal


-- | Saves a 'Val' for 'Key'.
saveVal :: Handle m -> Key -> Val -> m (Either HandleErr ())
saveVal :: forall (m :: * -> *).
Handle m -> Key -> Key -> m (Either HandleErr ())
saveVal = forall (m :: * -> *).
Handle m -> Key -> Key -> m (Either HandleErr ())
hSaveVal


-- | Loads a @'ValsByKey'@.
loadKVs :: Handle m -> Key -> m (Either HandleErr ValsByKey)
loadKVs :: forall (m :: * -> *).
Handle m -> Key -> m (Either HandleErr ValsByKey)
loadKVs = forall (m :: * -> *).
Handle m -> Key -> m (Either HandleErr ValsByKey)
hLoadKVs


-- | Saves a @'ValsByKey'@ .
saveKVs :: Handle m -> Key -> ValsByKey -> m (Either HandleErr ())
saveKVs :: forall (m :: * -> *).
Handle m -> Key -> ValsByKey -> m (Either HandleErr ())
saveKVs = forall (m :: * -> *).
Handle m -> Key -> ValsByKey -> m (Either HandleErr ())
hSaveKVs


-- | Loads a @'Val'@ from a @'ValsByKey'@.
loadFrom :: Handle m -> Key -> Key -> m (Either HandleErr (Maybe Val))
loadFrom :: forall (m :: * -> *).
Handle m -> Key -> Key -> m (Either HandleErr (Maybe Key))
loadFrom = forall (m :: * -> *).
Handle m -> Key -> Key -> m (Either HandleErr (Maybe Key))
hLoadFrom


-- | Saves a @'Val'@ in a @'ValsByKey'@.
saveTo :: Handle m -> Key -> Key -> Val -> m (Either HandleErr ())
saveTo :: forall (m :: * -> *).
Handle m -> Key -> Key -> Key -> m (Either HandleErr ())
saveTo = forall (m :: * -> *).
Handle m -> Key -> Key -> Key -> m (Either HandleErr ())
hSaveTo


-- | Loads a @'ValsByKey'@ that only includes @'Val's@ whose keys match a @Selection@.
loadSlice :: Handle m -> Key -> Selection -> m (Either HandleErr ValsByKey)
loadSlice :: forall (m :: * -> *).
Handle m -> Key -> Selection -> m (Either HandleErr ValsByKey)
loadSlice = forall (m :: * -> *).
Handle m -> Key -> Selection -> m (Either HandleErr ValsByKey)
hLoadSlice


-- | Updates the stored @'ValsByKey'@ from the given @'ValsByKey'@.
updateKVs :: Handle m -> Key -> ValsByKey -> m (Either HandleErr ())
updateKVs :: forall (m :: * -> *).
Handle m -> Key -> ValsByKey -> m (Either HandleErr ())
updateKVs = forall (m :: * -> *).
Handle m -> Key -> ValsByKey -> m (Either HandleErr ())
hUpdateKVs


-- | Deletes @'Val's@ stored with the given @'Key's@.
deleteKeys :: Handle m -> NonEmpty Key -> m (Either HandleErr ())
deleteKeys :: forall (m :: * -> *).
Handle m -> NonEmpty Key -> m (Either HandleErr ())
deleteKeys Handle m
h NonEmpty Key
keys = forall (m :: * -> *).
Handle m -> Selection -> m (Either HandleErr ())
deleteSelected Handle m
h forall a b. (a -> b) -> a -> b
$ NonEmpty Key -> Selection
AllOf NonEmpty Key
keys


-- | Deletes @'Val's@ that match a @'Selection'@.
deleteSelected :: Handle m -> Selection -> m (Either HandleErr ())
deleteSelected :: forall (m :: * -> *).
Handle m -> Selection -> m (Either HandleErr ())
deleteSelected = forall (m :: * -> *).
Handle m -> Selection -> m (Either HandleErr ())
hDeleteSelected


-- | Deletes @'Val's@ whose @Keys@ match a @Glob@.
deleteMatches :: Handle m -> Glob -> m (Either HandleErr ())
deleteMatches :: forall (m :: * -> *). Handle m -> Glob -> m (Either HandleErr ())
deleteMatches Handle m
h Glob
g = forall (m :: * -> *).
Handle m -> Selection -> m (Either HandleErr ())
deleteSelected Handle m
h forall a b. (a -> b) -> a -> b
$ Glob -> Selection
Match Glob
g


-- | Deletes @'Val's@ for the given @Keys@ from a @'ValsByKey'@.
deleteKeysFrom :: Handle m -> Key -> NonEmpty Key -> m (Either HandleErr ())
deleteKeysFrom :: forall (m :: * -> *).
Handle m -> Key -> NonEmpty Key -> m (Either HandleErr ())
deleteKeysFrom Handle m
h Key
key NonEmpty Key
ks = forall (m :: * -> *).
Handle m -> Key -> Selection -> m (Either HandleErr ())
deleteSelectedFrom Handle m
h Key
key forall a b. (a -> b) -> a -> b
$ NonEmpty Key -> Selection
AllOf NonEmpty Key
ks


-- | Deletes @'Val's@ whose @Keys@  match a @Selection@ from a @'ValsByKey'@
deleteSelectedFrom :: Handle m -> Key -> Selection -> m (Either HandleErr ())
deleteSelectedFrom :: forall (m :: * -> *).
Handle m -> Key -> Selection -> m (Either HandleErr ())
deleteSelectedFrom = forall (m :: * -> *).
Handle m -> Key -> Selection -> m (Either HandleErr ())
hDeleteSelectedKVs


-- | Deletes @'Val's@ whose @Keys@  match a @Glob@ from a @'ValsByKey'@
deleteMatchesFrom :: Handle m -> Key -> Glob -> m (Either HandleErr ())
deleteMatchesFrom :: forall (m :: * -> *).
Handle m -> Key -> Glob -> m (Either HandleErr ())
deleteMatchesFrom Handle m
h Key
key Glob
g = forall (m :: * -> *).
Handle m -> Key -> Selection -> m (Either HandleErr ())
deleteSelectedFrom Handle m
h Key
key forall a b. (a -> b) -> a -> b
$ Glob -> Selection
Match Glob
g


-- | Determines the number of @'Val's@ in a @'ValsByKey'@.
countKVs :: Handle m -> Key -> m (Either HandleErr Natural)
countKVs :: forall (m :: * -> *).
Handle m -> Key -> m (Either HandleErr Natural)
countKVs = forall (m :: * -> *).
Handle m -> Key -> m (Either HandleErr Natural)
hCountKVs


close :: Handle m -> m ()
close :: forall (m :: * -> *). Handle m -> m ()
close = forall (m :: * -> *). Handle m -> m ()
hClose