Safe Haskell	None
Language	Haskell2010

Hercules.CNix.Expr.Schema

Contents

Core
Error handling
Alternatives
Functions
Simple types
Attribute sets
Attribute sets as records
Attribute sets as used as dictionaries
Serialization
Parsing Nix
Utilities

Description

Types and functions to represent interfaces between Nix code and Haskell code.

Synopsis

data PSObject a = PSObject {
- provenance :: Provenance
- value :: RawValue
}
type MonadEval (m :: Type -> Type) = (MonadIO m, MonadReader (Ptr EvalState) m)
data Provenance
- = File FilePath
- | Other Text
- | Data
- | Attribute Provenance Text
- | ListItem Provenance Int
- | Application Provenance Provenance
data NixException
- = MissingAttribute Provenance Text
- | TypeError Provenance RawValueType [RawValueType]
- | InvalidText Provenance UnicodeException
- | StringContextNotAllowed Provenance
- | InvalidValue Provenance Text
appendProvenance :: Provenance -> [Char]
data (a :: k) |. (b :: k1)
(|!) :: forall a b c m. (CheckType (NixTypeForSchema a), MonadEval m, PossibleTypesForSchema a, PossibleTypesForSchema b) => (PSObject a -> m c) -> (PSObject b -> m c) -> PSObject (a |. b) -> m c
data (a :: k) ->. (b :: k1)
(.$) :: MonadIO m => PSObject (a ->. b) -> PSObject a -> m (PSObject b)
(>>$.) :: MonadEval m => m (PSObject (a ->. b)) -> m (PSObject a) -> m (PSObject b)
type (->?) (a :: k) (b :: k1) = (a ->. b) |. b
($?) :: (MonadEval m, PossibleTypesForSchema b) => PSObject (a ->? b) -> PSObject a -> m (PSObject b)
(>>$?) :: (MonadEval m, PossibleTypesForSchema b) => m (PSObject (a ->? b)) -> m (PSObject a) -> m (PSObject b)
data StringWithoutContext
basicAttrsWithProvenance :: Value NixAttrs -> Provenance -> PSObject (Attrs ('[] :: [Attr]))
data Attrs' (as :: [Attr]) (w :: k)
type Attrs (as :: [Attr]) = Attrs' as Void
type (::.) (a :: Symbol) b = a ':. b
type (.) (as :: [Attr]) (s :: Symbol) = AttrType' as as s
(#.) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (PSObject (as . s))
(>>.) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => m (PSObject (Attrs' as w)) -> AttrLabel s -> m (PSObject (as . s))
type (::?) (a :: Symbol) b = a ':? b
type (::??) (a :: Symbol) (b :: k) = a ':? (Null |. b)
type (?) (as :: [Attr]) (s :: Symbol) = OptionalAttrType' as as s
(#?) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (Maybe (PSObject (as ? s)))
(>>?) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => m (PSObject (Attrs' as w)) -> AttrLabel s -> m (Maybe (PSObject (as ? s)))
(#?!) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (PSObject (as ? s))
type Dictionary = Attrs' ('[] :: [Attr]) :: k -> Type
dictionaryToMap :: MonadEval m => PSObject (Dictionary w) -> m (Map ByteString (PSObject w))
lookupDict :: forall m (as :: [Attr]) w. MonadEval m => Text -> PSObject (Attrs' as w) -> m (Maybe (PSObject w))
lookupDictBS :: forall m (as :: [Attr]) w. MonadEval m => ByteString -> PSObject (Attrs' as w) -> m (Maybe (PSObject w))
requireDict :: forall m (as :: [Attr]) w. MonadEval m => Text -> PSObject (Attrs' as w) -> m (PSObject w)
requireDictBS :: forall m (as :: [Attr]) w. MonadEval m => ByteString -> PSObject (Attrs' as w) -> m (PSObject w)
toPSObject :: (MonadEval m, ToRawValue a) => a -> m (PSObject (NixTypeFor a))
class FromPSObject schema a where
- fromPSObject :: MonadEval m => PSObject schema -> m a
check :: (CheckType (NixTypeForSchema schema), HasRawValueType (NixTypeForSchema schema), MonadEval m) => PSObject schema -> m (Value (NixTypeForSchema schema))
getText_ :: MonadEval m => PSObject NixString -> m Text
getByteString_ :: MonadEval m => PSObject NixString -> m ByteString
exprWithBasePath :: forall schema m. MonadEval m => Text -> FilePath -> Proxy schema -> m (PSObject schema)
exprWithBasePathBS :: forall schema m. MonadEval m => ByteString -> FilePath -> Proxy schema -> m (PSObject schema)
uncheckedCast :: PSObject a -> PSObject b
englishOr :: [Text] -> Text
traverseArray :: MonadEval m => (PSObject a -> m b) -> PSObject [a] -> m [b]
(#??) :: forall {k} (s :: Symbol) (as :: [Attr]) b m (w :: k). (KnownSymbol s, (as ? s) ~ (Null |. b), PossibleTypesForSchema b, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (Maybe (PSObject b))

Core

data PSObject a Source #

An object (thunk or value) with its Provenance and an expected schema type attached as a phantom type.

The phantom specifies the expactation, not a checked type.

Constructors

PSObject
Fields provenance :: Provenance Tracks the origin of the object, which is useful informaton for error messages. value :: RawValue The Nix object, which may be a thunk (producing errors, non-termination, etc) or a `Value` of any type. Use `check` and/or `\|.` to evaluate it (whnf) and narrow down its runtime type to a specific `Value`.

Instances

Instances details

ToRawValue (PSObject a) Source #

Instance details

Defined in Hercules.CNix.Expr.Schema

Methods

toRawValue :: Ptr EvalState -> PSObject a -> IO RawValue Source #

(CheckType (NixTypeForSchema t), HasRawValueType (NixTypeForSchema t)) => ToValue (PSObject t) Source #

Instance details

Defined in Hercules.CNix.Expr.Schema

Associated Types

type NixTypeFor (PSObject t)
Instance details Defined in Hercules.CNix.Expr.Schema type NixTypeFor (PSObject t)

Methods

toValue :: Ptr EvalState -> PSObject t -> IO (Value (NixTypeFor (PSObject t))) Source #

type NixTypeFor (PSObject t) Source #

Instance details

Defined in Hercules.CNix.Expr.Schema

type NixTypeFor (PSObject t)

type MonadEval (m :: Type -> Type) = (MonadIO m, MonadReader (Ptr EvalState) m) Source #

Error handling

data Provenance Source #

Constructors

File FilePath
Other Text
Data
Attribute Provenance Text
ListItem Provenance Int
Application Provenance Provenance

Instances

Instances details

Show Provenance Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods showsPrec :: Int -> Provenance -> ShowS # show :: Provenance -> String # showList :: [Provenance] -> ShowS #
Eq Provenance Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods (==) :: Provenance -> Provenance -> Bool # (/=) :: Provenance -> Provenance -> Bool #
Ord Provenance Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods compare :: Provenance -> Provenance -> Ordering # (<) :: Provenance -> Provenance -> Bool # (<=) :: Provenance -> Provenance -> Bool # (>) :: Provenance -> Provenance -> Bool # (>=) :: Provenance -> Provenance -> Bool # max :: Provenance -> Provenance -> Provenance # min :: Provenance -> Provenance -> Provenance #

data NixException Source #

Constructors

MissingAttribute Provenance Text
TypeError
Fields Provenance RawValueType actual [RawValueType] expected
InvalidText Provenance UnicodeException
StringContextNotAllowed Provenance
InvalidValue Provenance Text

Instances

Instances details

Exception NixException Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods toException :: NixException -> SomeException # fromException :: SomeException -> Maybe NixException # displayException :: NixException -> String #
Show NixException Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods showsPrec :: Int -> NixException -> ShowS # show :: NixException -> String # showList :: [NixException] -> ShowS #
Eq NixException Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods (==) :: NixException -> NixException -> Bool # (/=) :: NixException -> NixException -> Bool #

appendProvenance :: Provenance -> [Char] Source #

Alternatives

data (a :: k) |. (b :: k1) Source #

Alternative schema. The value only needs to satisfy one subschema.

(|!) :: forall a b c m. (CheckType (NixTypeForSchema a), MonadEval m, PossibleTypesForSchema a, PossibleTypesForSchema b) => (PSObject a -> m c) -> (PSObject b -> m c) -> PSObject (a |. b) -> m c Source #

Force and check type, then continue without backtracking

Functions

data (a :: k) ->. (b :: k1) infixr 1 Source #

Function schema.

(.$) :: MonadIO m => PSObject (a ->. b) -> PSObject a -> m (PSObject b) Source #

(>>$.) :: MonadEval m => m (PSObject (a ->. b)) -> m (PSObject a) -> m (PSObject b) Source #

Application. Like $. but takes care of monadic binding as a convenience.

type (->?) (a :: k) (b :: k1) = (a ->. b) |. b infixr 1 Source #

Optional function. If the value is not a function, use it as the result.

($?) :: (MonadEval m, PossibleTypesForSchema b) => PSObject (a ->? b) -> PSObject a -> m (PSObject b) Source #

Optional application.

(>>$?) :: (MonadEval m, PossibleTypesForSchema b) => m (PSObject (a ->? b)) -> m (PSObject a) -> m (PSObject b) Source #

Optional application. Like $? but takes care of monadic binding as a convenience.

Simple types

data StringWithoutContext Source #

Instances

Instances details

FromPSObject StringWithoutContext ByteString Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m ByteString Source #
FromPSObject StringWithoutContext Text Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m Text Source #
FromPSObject StringWithoutContext [Char] Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m [Char] Source #

Attribute sets

basicAttrsWithProvenance :: Value NixAttrs -> Provenance -> PSObject (Attrs ('[] :: [Attr])) Source #

data Attrs' (as :: [Attr]) (w :: k) Source #

Attribute set schema with known attributes and wildcard type for remaining attributes.

Attribute sets as records

type Attrs (as :: [Attr]) = Attrs' as Void Source #

Attribute set schema with known attributes only

type (::.) (a :: Symbol) b = a ':. b infix 0 Source #

Required (_.) attribute name and type (::_)

Note that the type may still be nullable, but the attribute is expected to exist.

type (.) (as :: [Attr]) (s :: Symbol) = AttrType' as as s Source #

(#.) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (PSObject (as . s)) infixl 9 Source #

Attribute selector. a #. #b is a.b in Nix. Operates on attributes that are required (_.) in the schema, throwing an error if necessary.

(>>.) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => m (PSObject (Attrs' as w)) -> AttrLabel s -> m (PSObject (as . s)) infixl 9 Source #

A combination of >>= and #..

type (::?) (a :: Symbol) b = a ':? b infix 0 Source #

Optional (_?) attribute name and type (::_)

This indicates that the attribute may be omitted in its entirety, which is distinct from an attribute that may be null.

type (::??) (a :: Symbol) (b :: k) = a ':? (Null |. b) Source #

Optional (_?) attribute name and type (::_)

This indicates that the attribute may be omitted in its entirety, which is distinct from an attribute that may be null.

type (?) (as :: [Attr]) (s :: Symbol) = OptionalAttrType' as as s Source #

(#?) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (Maybe (PSObject (as ? s))) Source #

Attribute selector. a #? #b is a.b in Nix, but handles the missing case without exception. Operates on attributes that are optional (_?) in the schema, throwing an error if necessary.

(>>?) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => m (PSObject (Attrs' as w)) -> AttrLabel s -> m (Maybe (PSObject (as ? s))) Source #

A combination of >>= and #?.

(#?!) :: forall {k} (s :: Symbol) m (as :: [Attr]) (w :: k). (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (PSObject (as ? s)) Source #

Retrieve an optional attribute but throw if it's missing.

It provides a decent error message with attrset provenance, but can't provide extra context like you can when manually handling the a #? b Nothing case.

Attribute sets as used as dictionaries

type Dictionary = Attrs' ('[] :: [Attr]) :: k -> Type Source #

Attribute set functioning as a "dictionary" from string keys to a certain type.

dictionaryToMap :: MonadEval m => PSObject (Dictionary w) -> m (Map ByteString (PSObject w)) Source #

lookupDict :: forall m (as :: [Attr]) w. MonadEval m => Text -> PSObject (Attrs' as w) -> m (Maybe (PSObject w)) Source #

lookupDictBS :: forall m (as :: [Attr]) w. MonadEval m => ByteString -> PSObject (Attrs' as w) -> m (Maybe (PSObject w)) Source #

requireDict :: forall m (as :: [Attr]) w. MonadEval m => Text -> PSObject (Attrs' as w) -> m (PSObject w) Source #

Like #?!. Throws an acceptable but not great error message.

requireDictBS :: forall m (as :: [Attr]) w. MonadEval m => ByteString -> PSObject (Attrs' as w) -> m (PSObject w) Source #

Like #?!. Throws an acceptable but not great error message.

Serialization

toPSObject :: (MonadEval m, ToRawValue a) => a -> m (PSObject (NixTypeFor a)) Source #

class FromPSObject schema a where Source #

Schema-based parsing type class that constrains neither types nor schemas.

Methods

fromPSObject :: MonadEval m => PSObject schema -> m a Source #

Parse an object assumed to be in schema schema into a value of type a or throw a NixException.

Instances

Instances details

FromPSObject Int64 Int64 Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject Int64 -> m Int64 Source #
FromPSObject StringWithoutContext ByteString Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m ByteString Source #
FromPSObject StringWithoutContext Text Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m Text Source #
FromPSObject Bool Bool Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject Bool -> m Bool Source #
FromPSObject StringWithoutContext [Char] Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m [Char] Source #
FromPSObject a b => FromPSObject [a] [b] Source #
Instance details Defined in Hercules.CNix.Expr.Schema Methods fromPSObject :: MonadEval m => PSObject [a] -> m [b] Source #

check :: (CheckType (NixTypeForSchema schema), HasRawValueType (NixTypeForSchema schema), MonadEval m) => PSObject schema -> m (Value (NixTypeForSchema schema)) Source #

Force a value and check against schema.

getText_ :: MonadEval m => PSObject NixString -> m Text Source #

Ignores string context.

getByteString_ :: MonadEval m => PSObject NixString -> m ByteString Source #

Ignores string context.

Parsing Nix

exprWithBasePath Source #

Arguments

:: forall schema m. MonadEval m
=> Text	Expression text in the Nix language.
-> FilePath	Base path for relative path references in the expression text.
-> Proxy schema	A schema that the expression should satisfy.
-> m (PSObject schema)

Parses an expression from string

exprWithBasePathBS Source #

Arguments

:: forall schema m. MonadEval m
=> ByteString	Expression text in the Nix language.
-> FilePath	Base path for relative path references in the expression text.
-> Proxy schema	A schema that the expression should satisfy.
-> m (PSObject schema)

Parses an expression from string

Utilities

uncheckedCast :: PSObject a -> PSObject b Source #

englishOr :: [Text] -> Text Source #

traverseArray :: MonadEval m => (PSObject a -> m b) -> PSObject [a] -> m [b] Source #

(#??) :: forall {k} (s :: Symbol) (as :: [Attr]) b m (w :: k). (KnownSymbol s, (as ? s) ~ (Null |. b), PossibleTypesForSchema b, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (Maybe (PSObject b)) Source #

Attribute selector. a #? #b is a.b in Nix, but handles the missing case and the null case without exception. Operates on attributes that are optional (_?) and nullable (Null |., () |.) in the schema.