Hercules.CNix.Expr.Schema

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

Core

data PSObject (a :: Type)

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

ToRawValue (PSObject a)

Defined in Hercules.CNix.Expr.Schema

Methods

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

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

Defined in Hercules.CNix.Expr.Schema

Associated Types

type NixTypeFor (PSObject t)

Methods

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

type NixTypeFor (PSObject t)

Defined in Hercules.CNix.Expr.Schema

type NixTypeFor (PSObject t)

type MonadEval m = (MonadIO m, MonadReader (Ptr EvalState) m)

Error handling

data Provenance

Constructors

File FilePath

Other Text

Data

Attribute Provenance Text

ListItem Provenance Int

Application Provenance Provenance

Instances

Show Provenance

Defined in Hercules.CNix.Expr.Schema

Methods

showsPrec :: Int -> Provenance -> ShowS

show :: Provenance -> String

showList :: [Provenance] -> ShowS

Eq Provenance

Defined in Hercules.CNix.Expr.Schema

Methods

(==) :: Provenance -> Provenance -> Bool

(/=) :: Provenance -> Provenance -> Bool

Ord Provenance

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

Constructors

MissingAttribute Provenance Text

TypeError

Fields

• Provenance
• RawValueType

  actual

• [RawValueType]

  expected

InvalidText Provenance UnicodeException

StringContextNotAllowed Provenance

InvalidValue Provenance Text

Instances

Exception NixException

Defined in Hercules.CNix.Expr.Schema

Methods

toException :: NixException -> SomeException

fromException :: SomeException -> Maybe NixException

displayException :: NixException -> String

Show NixException

Defined in Hercules.CNix.Expr.Schema

Methods

showsPrec :: Int -> NixException -> ShowS

show :: NixException -> String

showList :: [NixException] -> ShowS

Eq NixException

Defined in Hercules.CNix.Expr.Schema

Methods

(==) :: NixException -> NixException -> Bool

(/=) :: NixException -> NixException -> Bool

appendProvenance :: Provenance -> [Char]

Alternatives

data a |. b

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

Force and check type, then continue without backtracking

Functions

data a ->. b infixr 1

Function schema.

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

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

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

type (->?) a b = (a ->. b) |. b infixr 1

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)

Optional application.

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

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

Simple types

data StringWithoutContext

Instances

FromPSObject StringWithoutContext ByteString

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m ByteString

FromPSObject StringWithoutContext Text

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m Text

FromPSObject StringWithoutContext [Char]

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m [Char]

Attribute sets

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

data Attrs' (as :: [Attr]) w

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

Attribute sets as records

type Attrs as = Attrs' as Void

Attribute set schema with known attributes only

type (::.) a b = a ':. b infix 0

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

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

type (.) as s = AttrType' as as s

(#.) :: (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (PSObject (as . s)) infixl 9

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

(>>.) :: (KnownSymbol s, MonadEval m) => m (PSObject (Attrs' as w)) -> AttrLabel s -> m (PSObject (as . s)) infixl 9

A combination of >>= and #..

type (::?) a b = a ':? b infix 0

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 b = a ':? (Null |. b)

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 s = OptionalAttrType' as as s

(#?) :: (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (Maybe (PSObject (as ? s)))

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.

(>>?) :: (KnownSymbol s, MonadEval m) => m (PSObject (Attrs' as w)) -> AttrLabel s -> m (Maybe (PSObject (as ? s)))

A combination of >>= and #?.

(#?!) :: (KnownSymbol s, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (PSObject (as ? s))

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' '[]

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

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

lookupDict :: MonadEval m => Text -> PSObject (Attrs' as w) -> m (Maybe (PSObject w))

lookupDictBS :: MonadEval m => ByteString -> PSObject (Attrs' as w) -> m (Maybe (PSObject w))

requireDict :: MonadEval m => Text -> PSObject (Attrs' as w) -> m (PSObject w)

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

requireDictBS :: MonadEval m => ByteString -> PSObject (Attrs' as w) -> m (PSObject w)

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

Serialization

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

class FromPSObject schema a where

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

Methods

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

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

Instances

FromPSObject Int64 Int64

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject Int64 -> m Int64

FromPSObject StringWithoutContext ByteString

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m ByteString

FromPSObject StringWithoutContext Text

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m Text

FromPSObject Bool Bool

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject Bool -> m Bool

FromPSObject StringWithoutContext [Char]

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject StringWithoutContext -> m [Char]

FromPSObject a b => FromPSObject [a] [b]

Defined in Hercules.CNix.Expr.Schema

Methods

fromPSObject :: MonadEval m => PSObject [a] -> m [b]

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

Force a value and check against schema.

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

Ignores string context.

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

Ignores string context.

Parsing Nix

exprWithBasePath

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

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 :: forall (a :: Type) (b :: Type). PSObject a -> PSObject b

englishOr :: [Text] -> Text

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

(#??) :: (KnownSymbol s, (as ? s) ~ (Null |. b), PossibleTypesForSchema b, MonadEval m) => PSObject (Attrs' as w) -> AttrLabel s -> m (Maybe (PSObject b))

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.