Copyright	(c) 2023 Apache OpenDAL
License	Apache-2.0
Maintainer	OpenDAL Contributors <dev@opendal.apache.org>"
Stability	experimental
Portability	non - portable (GHC extensions)
Safe Haskell	Safe-Inferred
Language	Haskell2010

OpenDAL

Contents

Operator APIs
- Types
- Functions
Writer Option Functions
Lister APIs
Writer APIs
Operator Raw APIs

Description

This module provides Haskell bindings for Apache OpenDAL.

Synopsis

data OperatorConfig = OperatorConfig {
- ocScheme :: String
- ocConfig :: HashMap String String
- ocLogAction :: Maybe (LogAction IO Message)
}
data Operator
data Lister
data Writer
data WriterOption = WriterOption {
- woAppend :: Bool
}
data OpenDALError = OpenDALError {
- errorCode :: ErrorCode
- message :: String
}
data ErrorCode
- = FFIError
- | Unexpected
- | Unsupported
- | ConfigInvalid
- | NotFound
- | PermissionDenied
- | IsADirectory
- | NotADirectory
- | AlreadyExists
- | RateLimited
- | IsSameFile
data EntryMode
- = File
- | Dir
- | Unknown
data Metadata = Metadata {
- mMode :: EntryMode
- mCacheControl :: Maybe String
- mContentDisposition :: Maybe String
- mContentLength :: Integer
- mContentMD5 :: Maybe String
- mContentType :: Maybe String
- mETag :: Maybe String
- mLastModified :: Maybe UTCTime
}
newtype OperatorT m a = OperatorT {
- runOperatorT :: ReaderT Operator (ExceptT OpenDALError m) a
}
class Monad m => MonadOperation m where
- readOp :: String -> m ByteString
- writeOp :: String -> ByteString -> m ()
- isExistOp :: String -> m Bool
- createDirOp :: String -> m ()
- copyOp :: String -> String -> m ()
- renameOp :: String -> String -> m ()
- deleteOp :: String -> m ()
- statOp :: String -> m Metadata
- listOp :: String -> m Lister
- scanOp :: String -> m Lister
- removeAllOp :: String -> m ()
runOp :: Operator -> OperatorT m a -> m (Either OpenDALError a)
newOperator :: OperatorConfig -> IO (Either OpenDALError Operator)
defaultWriterOption :: WriterOption
appendWriterOption :: WriterOption
nextLister :: Lister -> IO (Either OpenDALError (Maybe String))
writerOpRaw :: Operator -> String -> WriterOption -> IO (Either OpenDALError Writer)
writerWrite :: Writer -> ByteString -> IO (Either OpenDALError ())
writerClose :: Writer -> IO (Either OpenDALError Metadata)
readOpRaw :: Operator -> String -> IO (Either OpenDALError ByteString)
writeOpRaw :: Operator -> String -> ByteString -> IO (Either OpenDALError ())
isExistOpRaw :: Operator -> String -> IO (Either OpenDALError Bool)
createDirOpRaw :: Operator -> String -> IO (Either OpenDALError ())
copyOpRaw :: Operator -> String -> String -> IO (Either OpenDALError ())
renameOpRaw :: Operator -> String -> String -> IO (Either OpenDALError ())
deleteOpRaw :: Operator -> String -> IO (Either OpenDALError ())
statOpRaw :: Operator -> String -> IO (Either OpenDALError Metadata)
listOpRaw :: Operator -> String -> IO (Either OpenDALError Lister)
scanOpRaw :: Operator -> String -> IO (Either OpenDALError Lister)
operatorInfoRaw :: Operator -> IO (Either OpenDALError String)
removeAllOpRaw :: Operator -> String -> IO (Either OpenDALError ())

Operator APIs

Types

data OperatorConfig Source #

OperatorConfig is the configuration for an Operator. We recommend using OverloadedStrings to construct a default config.

For example:

default config

newOperator "memory"

custom services config

newOperator "memory" {ocConfig = HashMap.fromList [("root", "/tmp")]}

enable logging

newOperator "memory" {ocLogAction = Just simpleMessageAction}

Constructors

OperatorConfig
Fields ocScheme :: String The scheme of the operator. For example, "s3" or "gcs". ocConfig :: HashMap String String The config for the operator services. For example, "endpoint" and "access_key_id" for s3. The config is same as rust core. ocLogAction :: Maybe (LogAction IO Message) The log action for the operator. If it's `Nothing`, the operator won't enable logging.

Instances

Instances details

IsString OperatorConfig Source #
Instance details Defined in OpenDAL Methods fromString :: String -> OperatorConfig

data Operator Source #

Operator is the entry for all public blocking APIs. Create an Operator with newOperator.

Instances

Instances details

Monad m => MonadReader Operator (OperatorT m) Source #
Instance details Defined in OpenDAL Methods ask :: OperatorT m Operator local :: (Operator -> Operator) -> OperatorT m a -> OperatorT m a reader :: (Operator -> a) -> OperatorT m a

data Lister Source #

Lister is designed to list entries at given path in a blocking manner. Users can construct Lister by listOp or scanOp.

data Writer Source #

Writer is designed to write bytes into given path.

data WriterOption Source #

Options for creating a Writer.

Constructors

WriterOption
Fields woAppend :: Bool Whether to append to the file instead of overwriting it.

Instances

Instances details

Show WriterOption Source #
Instance details Defined in OpenDAL Methods showsPrec :: Int -> WriterOption -> ShowS show :: WriterOption -> String showList :: [WriterOption] -> ShowS
Eq WriterOption Source #
Instance details Defined in OpenDAL Methods (==) :: WriterOption -> WriterOption -> Bool (/=) :: WriterOption -> WriterOption -> Bool

data OpenDALError Source #

Represents an error that can occur when using OpenDAL.

Constructors

OpenDALError
Fields errorCode :: ErrorCode The error code. message :: String The error message.

Instances

Instances details

Show OpenDALError Source #
Instance details Defined in OpenDAL Methods showsPrec :: Int -> OpenDALError -> ShowS show :: OpenDALError -> String showList :: [OpenDALError] -> ShowS
Eq OpenDALError Source #
Instance details Defined in OpenDAL Methods (==) :: OpenDALError -> OpenDALError -> Bool (/=) :: OpenDALError -> OpenDALError -> Bool
Monad m => MonadError OpenDALError (OperatorT m) Source #
Instance details Defined in OpenDAL Methods throwError :: OpenDALError -> OperatorT m a catchError :: OperatorT m a -> (OpenDALError -> OperatorT m a) -> OperatorT m a

data ErrorCode Source #

Represents the possible error codes that can be returned by OpenDAL.

Constructors

FFIError	An error occurred in the FFI layer.
Unexpected	OpenDAL don't know what happened here, and no actions other than just returning it back. For example, s3 returns an internal service error.
Unsupported	Underlying service doesn't support this operation.
ConfigInvalid	The config for backend is invalid.
NotFound	The given path is not found.
PermissionDenied	The given path doesn't have enough permission for this operation.
IsADirectory	The given path is a directory.
NotADirectory	The given path is not a directory.
AlreadyExists	The given path already exists thus we failed to the specified operation on it.
RateLimited	Requests that sent to this path is over the limit, please slow down.
IsSameFile	The given file paths are same.

Instances

Instances details

Show ErrorCode Source #
Instance details Defined in OpenDAL Methods showsPrec :: Int -> ErrorCode -> ShowS show :: ErrorCode -> String showList :: [ErrorCode] -> ShowS
Eq ErrorCode Source #
Instance details Defined in OpenDAL Methods (==) :: ErrorCode -> ErrorCode -> Bool (/=) :: ErrorCode -> ErrorCode -> Bool

data EntryMode Source #

Represents the mode of an entry in a storage system (e.g., file or directory).

Constructors

File
Dir
Unknown

Instances

Instances details

Show EntryMode Source #
Instance details Defined in OpenDAL Methods showsPrec :: Int -> EntryMode -> ShowS show :: EntryMode -> String showList :: [EntryMode] -> ShowS
Eq EntryMode Source #
Instance details Defined in OpenDAL Methods (==) :: EntryMode -> EntryMode -> Bool (/=) :: EntryMode -> EntryMode -> Bool

data Metadata Source #

Represents metadata for an entry in a storage system.

Constructors

Metadata

Fields

mMode :: EntryMode
The mode of the entry.
mCacheControl :: Maybe String
The cache control of the entry.
mContentDisposition :: Maybe String
The content disposition of the entry.
mContentLength :: Integer
The content length of the entry.
mContentMD5 :: Maybe String
The content MD5 of the entry.
mContentType :: Maybe String
The content type of the entry.
mETag :: Maybe String
The ETag of the entry.
mLastModified :: Maybe UTCTime
The last modified time of the entry.

Instances

Instances details

Show Metadata Source #
Instance details Defined in OpenDAL Methods showsPrec :: Int -> Metadata -> ShowS show :: Metadata -> String showList :: [Metadata] -> ShowS
Eq Metadata Source #
Instance details Defined in OpenDAL Methods (==) :: Metadata -> Metadata -> Bool (/=) :: Metadata -> Metadata -> Bool

newtype OperatorT m a Source #

newtype wrapper ReaderT that keeps Operator in its context.

Constructors

OperatorT
Fields runOperatorT :: ReaderT Operator (ExceptT OpenDALError m) a

Instances

Instances details

MonadTrans OperatorT Source #
Instance details Defined in OpenDAL Methods lift :: Monad m => m a -> OperatorT m a
Monad m => MonadError OpenDALError (OperatorT m) Source #
Instance details Defined in OpenDAL Methods throwError :: OpenDALError -> OperatorT m a catchError :: OperatorT m a -> (OpenDALError -> OperatorT m a) -> OperatorT m a
Monad m => MonadReader Operator (OperatorT m) Source #
Instance details Defined in OpenDAL Methods ask :: OperatorT m Operator local :: (Operator -> Operator) -> OperatorT m a -> OperatorT m a reader :: (Operator -> a) -> OperatorT m a
MonadIO m => MonadIO (OperatorT m) Source #
Instance details Defined in OpenDAL Methods liftIO :: IO a -> OperatorT m a #
Monad m => Applicative (OperatorT m) Source #
Instance details Defined in OpenDAL Methods pure :: a -> OperatorT m a # (<>) :: OperatorT m (a -> b) -> OperatorT m a -> OperatorT m b liftA2 :: (a -> b -> c) -> OperatorT m a -> OperatorT m b -> OperatorT m c (>) :: OperatorT m a -> OperatorT m b -> OperatorT m b (<*) :: OperatorT m a -> OperatorT m b -> OperatorT m a
Functor m => Functor (OperatorT m) Source #
Instance details Defined in OpenDAL Methods fmap :: (a -> b) -> OperatorT m a -> OperatorT m b # (<$) :: a -> OperatorT m b -> OperatorT m a #
Monad m => Monad (OperatorT m) Source #
Instance details Defined in OpenDAL Methods (>>=) :: OperatorT m a -> (a -> OperatorT m b) -> OperatorT m b (>>) :: OperatorT m a -> OperatorT m b -> OperatorT m b return :: a -> OperatorT m a #
MonadIO m => MonadOperation (OperatorT m) Source #
Instance details Defined in OpenDAL Methods readOp :: String -> OperatorT m ByteString Source # writeOp :: String -> ByteString -> OperatorT m () Source # isExistOp :: String -> OperatorT m Bool Source # createDirOp :: String -> OperatorT m () Source # copyOp :: String -> String -> OperatorT m () Source # renameOp :: String -> String -> OperatorT m () Source # deleteOp :: String -> OperatorT m () Source # statOp :: String -> OperatorT m Metadata Source # listOp :: String -> OperatorT m Lister Source # scanOp :: String -> OperatorT m Lister Source # removeAllOp :: String -> OperatorT m () Source #

class Monad m => MonadOperation m where Source #

A type class for monads that can perform OpenDAL operations.

Methods

readOp :: String -> m ByteString Source #

Read the whole path into a bytes.

writeOp :: String -> ByteString -> m () Source #

Write bytes into given path.

isExistOp :: String -> m Bool Source #

Check if this path exists or not.

createDirOp :: String -> m () Source #

Create a dir at given path.

copyOp :: String -> String -> m () Source #

Copy a file from srcPath to dstPath.

renameOp :: String -> String -> m () Source #

Rename a file from srcPath to dstPath.

deleteOp :: String -> m () Source #

Delete given path.

statOp :: String -> m Metadata Source #

Get given path's metadata without cache directly.

listOp :: String -> m Lister Source #

List current dir path. This function will create a new handle to list entries. An error will be returned if path doesn't end with /.

scanOp :: String -> m Lister Source #

List dir in flat way. Also, this function can be used to list a prefix. An error will be returned if given path doesn't end with /.

removeAllOp :: String -> m () Source #

Remove all files and directories recursively.

Instances

Instances details

MonadIO m => MonadOperation (OperatorT m) Source #

Instance details

Defined in OpenDAL

Methods

readOp :: String -> OperatorT m ByteString Source #

writeOp :: String -> ByteString -> OperatorT m () Source #

isExistOp :: String -> OperatorT m Bool Source #

createDirOp :: String -> OperatorT m () Source #

copyOp :: String -> String -> OperatorT m () Source #

renameOp :: String -> String -> OperatorT m () Source #

deleteOp :: String -> OperatorT m () Source #

statOp :: String -> OperatorT m Metadata Source #

listOp :: String -> OperatorT m Lister Source #

scanOp :: String -> OperatorT m Lister Source #

removeAllOp :: String -> OperatorT m () Source #

Functions

runOp :: Operator -> OperatorT m a -> m (Either OpenDALError a) Source #

Runner for OperatorT monad. This function will run given OperatorT monad with given Operator.

Let's see an example:

operation :: MonadOperation m => m ()
operation = do
   writeOp op "key1" "value1"
   writeOp op "key2" "value2"
   value1 <- readOp op "key1"
   value2 <- readOp op "key2"

You can run this operation with runOp function:

runOp operator operation

newOperator :: OperatorConfig -> IO (Either OpenDALError Operator) Source #

Creates a new OpenDAL operator via OperatorConfig.

Writer Option Functions

defaultWriterOption :: WriterOption Source #

Default WriterOption for writing (overwriting).

appendWriterOption :: WriterOption Source #

WriterOption for appending to a file.

Lister APIs

nextLister :: Lister -> IO (Either OpenDALError (Maybe String)) Source #

Get next entry path from Lister.

Writer APIs

writerOpRaw :: Operator -> String -> WriterOption -> IO (Either OpenDALError Writer) Source #

Create a new writer for given path with specified options.

writerWrite :: Writer -> ByteString -> IO (Either OpenDALError ()) Source #

Writes bytes into given writer.

writerClose :: Writer -> IO (Either OpenDALError Metadata) Source #

Closes given writer.

Operator Raw APIs

Functions for performing raw OpenDAL operations are defined below. These functions are not meant to be used directly in most cases. Instead, use the high-level interface provided by the MonadOperation type class.

readOpRaw :: Operator -> String -> IO (Either OpenDALError ByteString) Source #

Read the whole path into a bytes.

writeOpRaw :: Operator -> String -> ByteString -> IO (Either OpenDALError ()) Source #

Write bytes into given path.

isExistOpRaw :: Operator -> String -> IO (Either OpenDALError Bool) Source #

Check if this path exists or not.

createDirOpRaw :: Operator -> String -> IO (Either OpenDALError ()) Source #

Create a dir at given path.

copyOpRaw :: Operator -> String -> String -> IO (Either OpenDALError ()) Source #

Copy a file from srcPath to dstPath.

renameOpRaw :: Operator -> String -> String -> IO (Either OpenDALError ()) Source #

Rename a file from srcPath to dstPath.

deleteOpRaw :: Operator -> String -> IO (Either OpenDALError ()) Source #

Delete given path.

statOpRaw :: Operator -> String -> IO (Either OpenDALError Metadata) Source #

Get given path's metadata without cache directly.

listOpRaw :: Operator -> String -> IO (Either OpenDALError Lister) Source #

List current dir path. This function will create a new handle to list entries. An error will be returned if path doesn't end with /.

scanOpRaw :: Operator -> String -> IO (Either OpenDALError Lister) Source #

List dir in flat way. Also, this function can be used to list a prefix. An error will be returned if given path doesn't end with /.

operatorInfoRaw :: Operator -> IO (Either OpenDALError String) Source #

Get operator info (scheme).

removeAllOpRaw :: Operator -> String -> IO (Either OpenDALError ()) Source #

Remove all files and directories recursively.