-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Candid integration
--   
--   This package brings the Candid interface definition language to
--   Haskell, supporting serialization, deserialization, importing type
--   definition and other features.
--   
--   See <a>Codec.Candid</a> for an overview and
--   <a>https://github.com/dfinity/candid</a> to learn more about Candid.
@package candid
@version 0.2

module Codec.Candid.Tuples

-- | A newtype to stand in for the unary tuple
newtype Unary a
Unary :: a -> Unary a
[unUnary] :: Unary a -> a
type Tuplable a = (AsTuple_ a (IsTuple a))
type AsTuple a = If (IsTuple a) a (Unary a)
asTuple :: AsTuple_ a b => a -> AsTuple a
fromTuple :: AsTuple_ a b => AsTuple a -> a
instance GHC.Show.Show a => GHC.Show.Show (Codec.Candid.Tuples.Unary a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Codec.Candid.Tuples.Unary a)
instance (Codec.Candid.Tuples.IsTuple a GHC.Types.~ 'GHC.Types.True) => Codec.Candid.Tuples.AsTuple_ a 'GHC.Types.True
instance (Codec.Candid.Tuples.IsTuple a GHC.Types.~ 'GHC.Types.False) => Codec.Candid.Tuples.AsTuple_ a 'GHC.Types.False


-- | This modules exports internals soley for the purpose of importing them
--   in the test suite
module Codec.Candid.TestExports
data DidFile
DidFile :: [DidDef TypeName] -> DidService TypeName -> DidFile
[defs] :: DidFile -> [DidDef TypeName]
[service] :: DidFile -> DidService TypeName
data TestAssertion
CanParse :: TestInput -> TestAssertion
CannotParse :: TestInput -> TestAssertion
ParseEq :: Bool -> TestInput -> TestInput -> TestAssertion
data TestInput
FromTextual :: Text -> TestInput
FromBinary :: ByteString -> TestInput
data CandidTest a
CandidTest :: Int -> TestAssertion -> [Type a] -> Maybe Text -> CandidTest a
[testLine] :: CandidTest a -> Int
[testAssertion] :: CandidTest a -> TestAssertion
[testType] :: CandidTest a -> [Type a]
[testDesc] :: CandidTest a -> Maybe Text

-- | A candid test file
--   
--   (no support for type definitions yet)
data CandidTestFile
CandidTestFile :: [DidDef TypeName] -> [CandidTest TypeName] -> CandidTestFile
[testDefs] :: CandidTestFile -> [DidDef TypeName]
[testTests] :: CandidTestFile -> [CandidTest TypeName]

-- | Parses a candid spec test file from a string
parseCandidTests :: String -> String -> Either String CandidTestFile

-- | Turns all candid type definitions into newtypes Used, so far, only in
--   the Candid test suite runner
generateCandidDefs :: [DidDef TypeName] -> Q ([Dec], TypeName -> Q Name)
candidTypeQ :: [Type Name] -> TypeQ

-- | Inversion of the Candid field label hash
invertHash :: Word32 -> Maybe Text


-- | This module provides preliminary Haskell supprot for decoding and
--   encoding the <b>Candid</b> data format. See
--   <a>https://github.com/dfinity/candid/blob/master/spec/Candid.md</a>
--   for the official Candid specification.
--   
--   <b>Warning:</b> The interface of this library is still in flux, as we
--   are yet learning the best idioms around Candid and Haskell.
module Codec.Candid

-- | Encode based on Haskell type
encode :: CandidArg a => a -> ByteString

-- | Encode to a <a>Builder</a> based on Haskell type
encodeBuilder :: forall a. CandidArg a => a -> Builder

-- | Decode to Haskell type
decode :: forall a. CandidArg a => ByteString -> Either String a

-- | The class of Haskell types that can be converted to Candid.
--   
--   You can create intances of this class for your own types, see the
--   tutorial above for examples. The default instance is mostly for
--   internal use.
class (Typeable a, CandidVal (AsCandid a)) => Candid a where {
    type family AsCandid a;
    type AsCandid a = a;
}
toCandid :: Candid a => a -> AsCandid a
fromCandid :: Candid a => AsCandid a -> a
toCandid :: (Candid a, a ~ AsCandid a) => a -> AsCandid a
fromCandid :: (Candid a, a ~ AsCandid a) => AsCandid a -> a
type CandidRow r = (Typeable r, AllUniqueLabels r, AllUniqueLabels (Map (Either String) r), Forall r Candid, Forall r Unconstrained1)

-- | The class of types that can be used as Candid argument sequences.
--   Essentially all types that are in <a>Candid</a>, but tuples need to be
--   treated specially.
type CandidArg a = (CandidSeq (AsTuple a), Tuplable a, Typeable a)

-- | The internal class of Haskell types that canonically map to Candid.
--   You would add instances to the <a>Candid</a> type class.
class Typeable a => CandidVal a

-- | Calculate a Candid type description from a Haskell type. The
--   <a>SeqDesc</a> type is roughly <tt>[Type]</tt>, with extra bookkeeping
--   for recursive types
seqDesc :: forall a. CandidArg a => SeqDesc
data SeqDesc

-- | This takes a type description and replaces all named types with their
--   definition.
--   
--   This produces an infinite type! Only use this in sufficiently lazy
--   contexts.
tieKnot :: SeqDesc -> [Type Void]

-- | NB: This will loop with recursive types!
typeDesc :: forall a. Candid a => Type Void

-- | A newtype to stand in for the unary tuple
newtype Unary a
Unary :: a -> Unary a
[unUnary] :: Unary a -> a
newtype Principal
Principal :: ByteString -> Principal
[rawPrincipal] :: Principal -> ByteString
prettyPrincipal :: Principal -> Text
parsePrincipal :: Text -> Either String Principal
data Reserved
Reserved :: Reserved
data FuncRef r
FuncRef :: Principal -> Text -> FuncRef r
[service] :: FuncRef r -> Principal
[method] :: FuncRef r -> Text

-- | Type-level <a>True</a>, to be used in method types annotations
data AnnTrue

-- | Type-level <a>False</a>, to be used in method types annotations
data AnnFalse
newtype ServiceRef (r :: Row *)
ServiceRef :: Principal -> ServiceRef (r :: Row *)
[rawServiceRef] :: ServiceRef (r :: Row *) -> Principal

-- | This newtype encodes a Haskell record type using generic programming.
--   Best used with <tt>DerivingVia</tt>, as shown in the tutorial.
newtype AsRecord a
AsRecord :: a -> AsRecord a
[unAsRecord] :: AsRecord a -> a

-- | This newtype encodes a Haskell data type as a variant using generic
--   programming. Best used with <tt>DerivingVia</tt>, as shown in the
--   tutorial.
newtype AsVariant a
AsVariant :: a -> AsVariant a
[unAsVariant] :: AsVariant a -> a

-- | A Candid service. The <tt>r</tt> describes the type of a <a>Rec</a>.
type CandidService m r = (Forall r (CandidMethod m), AllUniqueLabels r)

-- | A raw service, operating on bytes
type RawService m = Text -> ByteString -> m ByteString

-- | Turns a raw service (function operating on bytes) into a typed Candid
--   service (a record of typed methods). The raw service is typically code
--   that talks over the network.
toCandidService :: forall m r. CandidService m r => (forall a. String -> m a) -> RawService m -> Rec r

-- | Turns a typed candid service into a raw service. Typically used in a
--   framework warpping Candid services.
fromCandidService :: forall m r. CandidService m r => (forall a. Text -> m a) -> (forall a. String -> m a) -> Rec r -> RawService m

-- | This quasi-quoter turns a Candid description into a Haskell type. It
--   assumes a type variable <tt>m</tt> to be in scope.
candid :: QuasiQuoter

-- | As <a>candid</a>, but takes a filename
candidFile :: QuasiQuoter

-- | This quasi-quoter turns works on individual candid types, e.g.
--   
--   <pre>
--   type InstallMode = [candidType| variant {install : null; reinstall : null; upgrade : null}; |]
--   </pre>
candidType :: QuasiQuoter
data Type a
NatT :: Type a
Nat8T :: Type a
Nat16T :: Type a
Nat32T :: Type a
Nat64T :: Type a
IntT :: Type a
Int8T :: Type a
Int16T :: Type a
Int32T :: Type a
Int64T :: Type a
Float32T :: Type a
Float64T :: Type a
BoolT :: Type a
TextT :: Type a
NullT :: Type a
ReservedT :: Type a
EmptyT :: Type a
OptT :: Type a -> Type a
VecT :: Type a -> Type a
RecT :: Fields a -> Type a
VariantT :: Fields a -> Type a
FuncT :: MethodType a -> Type a
ServiceT :: [(Text, MethodType a)] -> Type a
PrincipalT :: Type a

-- | a short-hand for <a>VecT</a> <a>Nat8T</a> for recursive types
BlobT :: Type a

-- | A reference to a named type
RefT :: a -> Type a

-- | The type of a candid method
data MethodType a
MethodType :: [Type a] -> [Type a] -> Bool -> Bool -> MethodType a
[methParams] :: MethodType a -> [Type a]
[methResults] :: MethodType a -> [Type a]
[methQuery] :: MethodType a -> Bool
[methOneway] :: MethodType a -> Bool
type Fields a = [(FieldName, Type a)]

-- | A type for a Candid field name. Essentially a <a>Word32</a> with maybe
--   a textual label attached
data FieldName

-- | Create a <a>FieldName</a> from a label
labledField :: Text -> FieldName

-- | Create a <a>FieldName</a> from the raw hash
hashedField :: Word32 -> FieldName

-- | Extract the raw field hash value
fieldHash :: FieldName -> Word32

-- | Represent a <a>FieldName</a> (which may be numeric) in contexts where
--   only text is allowed, using the same encoding/decoding algorithm as
--   Motoko.
--   
--   This used in the <a>Candid</a> instance for <a>Rec</a> and <a>Vec</a>
escapeFieldName :: FieldName -> Text

-- | The inverse of <a>escapeFieldName</a>
unescapeFieldName :: Text -> FieldName

-- | The Candid field label hashing algorithm
candidHash :: Text -> Word32
data Value
NumV :: Scientific -> Value
NatV :: Natural -> Value
Nat8V :: Word8 -> Value
Nat16V :: Word16 -> Value
Nat32V :: Word32 -> Value
Nat64V :: Word64 -> Value
IntV :: Integer -> Value
Int8V :: Int8 -> Value
Int16V :: Int16 -> Value
Int32V :: Int32 -> Value
Int64V :: Int64 -> Value
Float32V :: Float -> Value
Float64V :: Double -> Value
BoolV :: Bool -> Value
TextV :: Text -> Value
NullV :: Value
ReservedV :: Value
OptV :: Maybe Value -> Value
VecV :: Vector Value -> Value
RecV :: [(FieldName, Value)] -> Value
TupV :: [Value] -> Value
VariantV :: FieldName -> Value -> Value
FuncV :: Principal -> Text -> Value
ServiceV :: Principal -> Value
PrincipalV :: Principal -> Value
BlobV :: ByteString -> Value
AnnV :: Value -> Type Void -> Value

-- | Decode binay value into the type description and the untyped value
--   representation.
decodeVals :: ByteString -> Either String (SeqDesc, [Value])

-- | Decode (dynamic) values to Haskell type
--   
--   This applies some best-effort subtyping/coercion, suitable for liberal
--   parsing of the textual representation, but not the coercion algorithm
--   as specified in the specification, which requires a provided type.
fromCandidVals :: CandidArg a => [Value] -> Either String a

-- | Turn haskell types into a dynamic Candid value. This may lose type
--   information.
toCandidVals :: CandidArg a => a -> [Value]

-- | Encodes a Candid value given in the dynamic <a>Value</a> form, at
--   inferred type.
--   
--   This may fail if the values have inconsistent types. It does not use
--   the <tt>reserved</tt> supertype (unless explicitly told to).
--   
--   Not all possible values are encodable this way. For example, all
--   function references will be encoded at type <tt>() - ()</tt>.
encodeDynValues :: [Value] -> Either String Builder

-- | Encodes a Candid value given in textual form.
--   
--   This may fail if the textual form cannot be parsed or has inconsistent
--   types. It does not use the <tt>reserved</tt> supertype (unless
--   explicitly told to).
encodeTextual :: String -> Either String ByteString
data DidFile

-- | Parses a Candid description (<tt>.did</tt>) from a string
parseDid :: String -> Either String DidFile

-- | Parses a Candid textual value from a string
parseValue :: String -> Either String Value

-- | Parses a sequence of Candid textual values from a string
parseValues :: String -> Either String [Value]