-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Write Haskell source files including C code inline. No FFI required. -- -- See https://github.com/fpco/inline-c/blob/master/README.md. @package inline-c @version 0.5.6.0 -- | A parser for C99 declarations. Currently, the parser has the following -- limitations: -- -- -- -- The parser is incremental and generic (see CParser). -- Pretty and Arbitrary instances are provided for all the -- data types. -- -- The entry point if you want to parse C declarations is -- parameter_declaration. module Language.C.Types.Parse -- | A collection of named types (typedefs) type TypeNames = HashSet CIdentifier data CParserContext i CParserContext :: String -> TypeNames -> (forall m. CParser i m => m i) -> (i -> String) -> CParserContext i [cpcIdentName] :: CParserContext i -> String -- | Function used to determine whether an identifier is a type name. [cpcTypeNames] :: CParserContext i -> TypeNames -- | Parses an identifier, *without consuming whitespace afterwards*. [cpcParseIdent] :: CParserContext i -> forall m. CParser i m => m i [cpcIdentToString] :: CParserContext i -> i -> String -- | A type for C identifiers. data CIdentifier unCIdentifier :: CIdentifier -> String cIdentifierFromString :: String -> Either String CIdentifier cCParserContext :: TypeNames -> CParserContext CIdentifier -- | All the parsing is done using the type classes provided by the -- parsers package. You can use the parsing routines with any of -- the parsers that implement the classes, such as parsec or -- trifecta. -- -- We parametrize the parsing by the type of the variable identifiers, -- i. We do so because we use this parser to implement -- anti-quoters referring to Haskell variables, and thus we need to parse -- Haskell identifiers in certain positions. type CParser i m = (Monad m, Functor m, Applicative m, MonadPlus m, Parsing m, CharParsing m, TokenParsing m, LookAheadParsing m, MonadReader (CParserContext i) m, Hashable i) -- | Runs a CParser using parsec. runCParser :: Stream s Identity Char => CParserContext i -> String -> s -> (ReaderT (CParserContext i) (Parsec s ()) a) -> Either ParseError a -- | Useful for quick testing. Uses "quickCParser" as source name, -- and throws an error if parsing fails. quickCParser :: CParserContext i -> String -> (ReaderT (CParserContext i) (Parsec String ()) a) -> a -- | Like quickCParser, but uses cCParserContext -- (const False) as CParserContext. quickCParser_ :: String -> (ReaderT (CParserContext CIdentifier) (Parsec String ()) a) -> a identifier_no_lex :: CParser i m => m i data DeclarationSpecifier StorageClassSpecifier :: StorageClassSpecifier -> DeclarationSpecifier TypeSpecifier :: TypeSpecifier -> DeclarationSpecifier TypeQualifier :: TypeQualifier -> DeclarationSpecifier FunctionSpecifier :: FunctionSpecifier -> DeclarationSpecifier declaration_specifiers :: CParser i m => m [DeclarationSpecifier] data StorageClassSpecifier TYPEDEF :: StorageClassSpecifier EXTERN :: StorageClassSpecifier STATIC :: StorageClassSpecifier AUTO :: StorageClassSpecifier REGISTER :: StorageClassSpecifier storage_class_specifier :: CParser i m => m StorageClassSpecifier data TypeSpecifier VOID :: TypeSpecifier CHAR :: TypeSpecifier SHORT :: TypeSpecifier INT :: TypeSpecifier LONG :: TypeSpecifier FLOAT :: TypeSpecifier DOUBLE :: TypeSpecifier SIGNED :: TypeSpecifier UNSIGNED :: TypeSpecifier Struct :: CIdentifier -> TypeSpecifier Enum :: CIdentifier -> TypeSpecifier TypeName :: CIdentifier -> TypeSpecifier type_specifier :: CParser i m => m TypeSpecifier data TypeQualifier CONST :: TypeQualifier RESTRICT :: TypeQualifier VOLATILE :: TypeQualifier type_qualifier :: CParser i m => m TypeQualifier data FunctionSpecifier INLINE :: FunctionSpecifier function_specifier :: CParser i m => m FunctionSpecifier data Declarator i Declarator :: [Pointer] -> (DirectDeclarator i) -> Declarator i [declaratorPointers] :: Declarator i -> [Pointer] [declaratorDirect] :: Declarator i -> (DirectDeclarator i) declarator :: CParser i m => m (Declarator i) data DirectDeclarator i DeclaratorRoot :: i -> DirectDeclarator i ArrayOrProto :: (DirectDeclarator i) -> (ArrayOrProto i) -> DirectDeclarator i DeclaratorParens :: (Declarator i) -> DirectDeclarator i direct_declarator :: CParser i m => m (DirectDeclarator i) data ArrayOrProto i Array :: (ArrayType i) -> ArrayOrProto i Proto :: [ParameterDeclaration i] -> ArrayOrProto i array_or_proto :: CParser i m => m (ArrayOrProto i) data ArrayType i VariablySized :: ArrayType i Unsized :: ArrayType i SizedByInteger :: Integer -> ArrayType i SizedByIdentifier :: i -> ArrayType i array_type :: CParser i m => m (ArrayType i) data Pointer Pointer :: [TypeQualifier] -> Pointer pointer :: CParser i m => m Pointer data ParameterDeclaration i ParameterDeclaration :: [DeclarationSpecifier] -> DeclaratorOrAbstractDeclarator i -> ParameterDeclaration i [parameterDeclarationSpecifiers] :: ParameterDeclaration i -> [DeclarationSpecifier] [parameterDeclarationDeclarator] :: ParameterDeclaration i -> DeclaratorOrAbstractDeclarator i data DeclaratorOrAbstractDeclarator i IsDeclarator :: (Declarator i) -> DeclaratorOrAbstractDeclarator i IsAbstractDeclarator :: (AbstractDeclarator i) -> DeclaratorOrAbstractDeclarator i parameter_declaration :: CParser i m => m (ParameterDeclaration i) parameter_list :: CParser i m => m [ParameterDeclaration i] data AbstractDeclarator i AbstractDeclarator :: [Pointer] -> Maybe (DirectAbstractDeclarator i) -> AbstractDeclarator i [abstractDeclaratorPointers] :: AbstractDeclarator i -> [Pointer] [abstractDeclaratorDirect] :: AbstractDeclarator i -> Maybe (DirectAbstractDeclarator i) abstract_declarator :: CParser i m => m (AbstractDeclarator i) data DirectAbstractDeclarator i ArrayOrProtoHere :: (ArrayOrProto i) -> DirectAbstractDeclarator i ArrayOrProtoThere :: (DirectAbstractDeclarator i) -> (ArrayOrProto i) -> DirectAbstractDeclarator i AbstractDeclaratorParens :: (AbstractDeclarator i) -> DirectAbstractDeclarator i direct_abstract_declarator :: CParser i m => m (DirectAbstractDeclarator i) cIdentStart :: [Char] cIdentLetter :: [Char] cReservedWords :: HashSet String -- | Type used to generate an Arbitrary ParameterDeclaration -- with arbitrary allowed type names. data ParameterDeclarationWithTypeNames i ParameterDeclarationWithTypeNames :: HashSet CIdentifier -> (ParameterDeclaration i) -> ParameterDeclarationWithTypeNames i [pdwtnTypeNames] :: ParameterDeclarationWithTypeNames i -> HashSet CIdentifier [pdwtnParameterDeclaration] :: ParameterDeclarationWithTypeNames i -> (ParameterDeclaration i) arbitraryParameterDeclarationWithTypeNames :: (Arbitrary i, Hashable i) => (i -> String) -> Gen (ParameterDeclarationWithTypeNames i) instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.ParameterDeclarationWithTypeNames i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.ParameterDeclarationWithTypeNames i) instance GHC.Show.Show a => GHC.Show.Show (Language.C.Types.Parse.OneOfSized a) instance GHC.Classes.Eq a => GHC.Classes.Eq (Language.C.Types.Parse.OneOfSized a) instance Data.Traversable.Traversable Language.C.Types.Parse.DirectDeclarator instance Data.Foldable.Foldable Language.C.Types.Parse.DirectDeclarator instance GHC.Base.Functor Language.C.Types.Parse.DirectDeclarator instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.DirectDeclarator i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.DirectDeclarator i) instance Data.Traversable.Traversable Language.C.Types.Parse.Declarator instance Data.Foldable.Foldable Language.C.Types.Parse.Declarator instance GHC.Base.Functor Language.C.Types.Parse.Declarator instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.Declarator i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.Declarator i) instance Data.Traversable.Traversable Language.C.Types.Parse.DeclaratorOrAbstractDeclarator instance Data.Foldable.Foldable Language.C.Types.Parse.DeclaratorOrAbstractDeclarator instance GHC.Base.Functor Language.C.Types.Parse.DeclaratorOrAbstractDeclarator instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.DeclaratorOrAbstractDeclarator i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.DeclaratorOrAbstractDeclarator i) instance Data.Traversable.Traversable Language.C.Types.Parse.ParameterDeclaration instance Data.Foldable.Foldable Language.C.Types.Parse.ParameterDeclaration instance GHC.Base.Functor Language.C.Types.Parse.ParameterDeclaration instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.ParameterDeclaration i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.ParameterDeclaration i) instance Data.Traversable.Traversable Language.C.Types.Parse.ArrayOrProto instance Data.Foldable.Foldable Language.C.Types.Parse.ArrayOrProto instance GHC.Base.Functor Language.C.Types.Parse.ArrayOrProto instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.ArrayOrProto i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.ArrayOrProto i) instance Data.Traversable.Traversable Language.C.Types.Parse.AbstractDeclarator instance Data.Foldable.Foldable Language.C.Types.Parse.AbstractDeclarator instance GHC.Base.Functor Language.C.Types.Parse.AbstractDeclarator instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.AbstractDeclarator i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.AbstractDeclarator i) instance Data.Traversable.Traversable Language.C.Types.Parse.DirectAbstractDeclarator instance Data.Foldable.Foldable Language.C.Types.Parse.DirectAbstractDeclarator instance GHC.Base.Functor Language.C.Types.Parse.DirectAbstractDeclarator instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.DirectAbstractDeclarator i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.DirectAbstractDeclarator i) instance GHC.Show.Show Language.C.Types.Parse.Pointer instance GHC.Classes.Eq Language.C.Types.Parse.Pointer instance Data.Traversable.Traversable Language.C.Types.Parse.ArrayType instance Data.Foldable.Foldable Language.C.Types.Parse.ArrayType instance GHC.Base.Functor Language.C.Types.Parse.ArrayType instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Parse.ArrayType i) instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Parse.ArrayType i) instance GHC.Show.Show Language.C.Types.Parse.DeclarationSpecifier instance GHC.Classes.Eq Language.C.Types.Parse.DeclarationSpecifier instance GHC.Show.Show Language.C.Types.Parse.FunctionSpecifier instance GHC.Classes.Eq Language.C.Types.Parse.FunctionSpecifier instance GHC.Show.Show Language.C.Types.Parse.TypeQualifier instance GHC.Classes.Eq Language.C.Types.Parse.TypeQualifier instance GHC.Show.Show Language.C.Types.Parse.TypeSpecifier instance GHC.Classes.Eq Language.C.Types.Parse.TypeSpecifier instance GHC.Show.Show Language.C.Types.Parse.StorageClassSpecifier instance GHC.Classes.Eq Language.C.Types.Parse.StorageClassSpecifier instance Data.Hashable.Class.Hashable Language.C.Types.Parse.CIdentifier instance GHC.Show.Show Language.C.Types.Parse.CIdentifier instance GHC.Classes.Ord Language.C.Types.Parse.CIdentifier instance GHC.Classes.Eq Language.C.Types.Parse.CIdentifier instance Data.String.IsString Language.C.Types.Parse.CIdentifier instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.Parse.CIdentifier instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.Parse.DeclarationSpecifier instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.Parse.StorageClassSpecifier instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.Parse.TypeSpecifier instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.Parse.TypeQualifier instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.Parse.FunctionSpecifier instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.Parse.Declarator i) instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.Parse.Pointer instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.Parse.DirectDeclarator i) instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.Parse.ArrayOrProto i) instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.Parse.ArrayType i) instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.Parse.ParameterDeclaration i) instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.Parse.AbstractDeclarator i) instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.Parse.DirectAbstractDeclarator i) instance Test.QuickCheck.Arbitrary.Arbitrary Language.C.Types.Parse.CIdentifier instance Test.QuickCheck.Arbitrary.Arbitrary Language.C.Types.Parse.StorageClassSpecifier instance Test.QuickCheck.Arbitrary.Arbitrary Language.C.Types.Parse.TypeQualifier instance Test.QuickCheck.Arbitrary.Arbitrary Language.C.Types.Parse.FunctionSpecifier instance Test.QuickCheck.Arbitrary.Arbitrary Language.C.Types.Parse.Pointer -- | Views of C datatypes. While Language.C.Types.Parse defines -- datatypes for representing the concrete syntax tree of C types, this -- module provides friendlier views of C types, by turning them into a -- data type matching more closely how we read and think about types, -- both in Haskell and in C. To appreciate the difference, look at the -- difference between ParameterDeclaration and -- ParameterDeclaration. -- -- As a bonus, routines are provided for describing types in natural -- language (English) -- see describeParameterDeclaration and -- describeType. module Language.C.Types -- | A type for C identifiers. data CIdentifier unCIdentifier :: CIdentifier -> String cIdentifierFromString :: String -> Either String CIdentifier data StorageClassSpecifier TYPEDEF :: StorageClassSpecifier EXTERN :: StorageClassSpecifier STATIC :: StorageClassSpecifier AUTO :: StorageClassSpecifier REGISTER :: StorageClassSpecifier data TypeQualifier CONST :: TypeQualifier RESTRICT :: TypeQualifier VOLATILE :: TypeQualifier data FunctionSpecifier INLINE :: FunctionSpecifier data ArrayType i VariablySized :: ArrayType i Unsized :: ArrayType i SizedByInteger :: Integer -> ArrayType i SizedByIdentifier :: i -> ArrayType i data Specifiers Specifiers :: [StorageClassSpecifier] -> [TypeQualifier] -> [FunctionSpecifier] -> Specifiers [storageClassSpecifiers] :: Specifiers -> [StorageClassSpecifier] [typeQualifiers] :: Specifiers -> [TypeQualifier] [functionSpecifiers] :: Specifiers -> [FunctionSpecifier] data Type i TypeSpecifier :: Specifiers -> TypeSpecifier -> Type i Ptr :: [TypeQualifier] -> (Type i) -> Type i Array :: (ArrayType i) -> (Type i) -> Type i Proto :: (Type i) -> [ParameterDeclaration i] -> Type i data TypeSpecifier Void :: TypeSpecifier Char :: (Maybe Sign) -> TypeSpecifier Short :: Sign -> TypeSpecifier Int :: Sign -> TypeSpecifier Long :: Sign -> TypeSpecifier LLong :: Sign -> TypeSpecifier Float :: TypeSpecifier Double :: TypeSpecifier LDouble :: TypeSpecifier TypeName :: CIdentifier -> TypeSpecifier Struct :: CIdentifier -> TypeSpecifier Enum :: CIdentifier -> TypeSpecifier data Sign Signed :: Sign Unsigned :: Sign data ParameterDeclaration i ParameterDeclaration :: Maybe i -> (Type i) -> ParameterDeclaration i [parameterDeclarationId] :: ParameterDeclaration i -> Maybe i [parameterDeclarationType] :: ParameterDeclaration i -> (Type i) -- | A collection of named types (typedefs) type TypeNames = HashSet CIdentifier -- | All the parsing is done using the type classes provided by the -- parsers package. You can use the parsing routines with any of -- the parsers that implement the classes, such as parsec or -- trifecta. -- -- We parametrize the parsing by the type of the variable identifiers, -- i. We do so because we use this parser to implement -- anti-quoters referring to Haskell variables, and thus we need to parse -- Haskell identifiers in certain positions. type CParser i m = (Monad m, Functor m, Applicative m, MonadPlus m, Parsing m, CharParsing m, TokenParsing m, LookAheadParsing m, MonadReader (CParserContext i) m, Hashable i) data CParserContext i cCParserContext :: TypeNames -> CParserContext CIdentifier -- | Runs a CParser using parsec. runCParser :: Stream s Identity Char => CParserContext i -> String -> s -> (ReaderT (CParserContext i) (Parsec s ()) a) -> Either ParseError a -- | Useful for quick testing. Uses "quickCParser" as source name, -- and throws an error if parsing fails. quickCParser :: CParserContext i -> String -> (ReaderT (CParserContext i) (Parsec String ()) a) -> a -- | Like quickCParser, but uses cCParserContext -- (const False) as CParserContext. quickCParser_ :: String -> (ReaderT (CParserContext CIdentifier) (Parsec String ()) a) -> a parseParameterDeclaration :: (CParser i m, Pretty i) => m (ParameterDeclaration i) parseParameterList :: (CParser i m, Pretty i) => m [ParameterDeclaration i] parseIdentifier :: CParser i m => m i parseType :: (CParser i m, Pretty i) => m (Type i) data UntangleErr MultipleDataTypes :: [DeclarationSpecifier] -> UntangleErr NoDataTypes :: [DeclarationSpecifier] -> UntangleErr IllegalSpecifiers :: String -> [TypeSpecifier] -> UntangleErr untangleParameterDeclaration :: ParameterDeclaration i -> Either UntangleErr (ParameterDeclaration i) tangleParameterDeclaration :: forall i. ParameterDeclaration i -> ParameterDeclaration i describeParameterDeclaration :: Pretty i => ParameterDeclaration i -> Doc describeType :: Pretty i => Type i -> Doc instance GHC.Classes.Eq Language.C.Types.UntangleErr instance GHC.Show.Show Language.C.Types.UntangleErr instance Data.Traversable.Traversable Language.C.Types.Type instance Data.Foldable.Foldable Language.C.Types.Type instance GHC.Base.Functor Language.C.Types.Type instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.Type i) instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.Type i) instance Data.Traversable.Traversable Language.C.Types.ParameterDeclaration instance Data.Foldable.Foldable Language.C.Types.ParameterDeclaration instance GHC.Base.Functor Language.C.Types.ParameterDeclaration instance GHC.Classes.Eq i => GHC.Classes.Eq (Language.C.Types.ParameterDeclaration i) instance GHC.Show.Show i => GHC.Show.Show (Language.C.Types.ParameterDeclaration i) instance GHC.Classes.Ord Language.C.Types.TypeSpecifier instance GHC.Classes.Eq Language.C.Types.TypeSpecifier instance GHC.Show.Show Language.C.Types.TypeSpecifier instance GHC.Classes.Ord Language.C.Types.Sign instance GHC.Classes.Eq Language.C.Types.Sign instance GHC.Show.Show Language.C.Types.Sign instance GHC.Classes.Eq Language.C.Types.Specifiers instance GHC.Show.Show Language.C.Types.Specifiers instance GHC.Base.Monoid Language.C.Types.Specifiers instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.TypeSpecifier instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Types.UntangleErr instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.ParameterDeclaration i) instance Text.PrettyPrint.ANSI.Leijen.Pretty i => Text.PrettyPrint.ANSI.Leijen.Pretty (Language.C.Types.Type i) module Language.C.Inline.HaskellIdentifier -- | A possibly qualified Haskell identifier. data HaskellIdentifier unHaskellIdentifier :: HaskellIdentifier -> String haskellIdentifierFromString :: String -> Either String HaskellIdentifier haskellCParserContext :: TypeNames -> CParserContext HaskellIdentifier -- | See -- https://www.haskell.org/onlinereport/haskell2010/haskellch2.html#x7-160002.2. parseHaskellIdentifier :: forall i m. CParser i m => m HaskellIdentifier -- | Mangles an HaskellIdentifier to produce a valid -- CIdentifier which still sort of resembles the -- HaskellIdentifier. mangleHaskellIdentifier :: HaskellIdentifier -> CIdentifier instance Data.Hashable.Class.Hashable Language.C.Inline.HaskellIdentifier.HaskellIdentifier instance GHC.Show.Show Language.C.Inline.HaskellIdentifier.HaskellIdentifier instance GHC.Classes.Ord Language.C.Inline.HaskellIdentifier.HaskellIdentifier instance GHC.Classes.Eq Language.C.Inline.HaskellIdentifier.HaskellIdentifier instance Data.String.IsString Language.C.Inline.HaskellIdentifier.HaskellIdentifier instance Text.PrettyPrint.ANSI.Leijen.Pretty Language.C.Inline.HaskellIdentifier.HaskellIdentifier instance Test.QuickCheck.Arbitrary.Arbitrary Language.C.Inline.HaskellIdentifier.HaskellIdentifier -- | A Context is used to define the capabilities of the Template -- Haskell code that handles the inline C code. See the documentation of -- the data type for more details. -- -- In practice, a Context will have to be defined for each library -- that defines new C types, to allow the TemplateHaskell code to -- interpret said types correctly. module Language.C.Inline.Context -- | A mapping from TypeSpecifiers to Haskell types. Needed both to -- parse C types, and to convert them to Haskell types. type TypesTable = Map TypeSpecifier TypeQ -- | A data type to indicate whether the user requested pure or IO function -- from Haskell data Purity Pure :: Purity IO :: Purity -- | Given a Context, it uses its ctxTypesTable to convert -- arbitrary C types. convertType :: Purity -> TypesTable -> Type CIdentifier -> Q (Maybe Type) -- | An alias for Ptr. type CArray = Ptr typeNamesFromTypesTable :: TypesTable -> TypeNames data AntiQuoter a AntiQuoter :: (forall m. CParser HaskellIdentifier m => m (CIdentifier, Type CIdentifier, a)) -> (Purity -> TypesTable -> Type CIdentifier -> a -> Q (Type, Exp)) -> AntiQuoter a -- | Parses the body of the antiquotation, returning a hint for the name to -- assign to the variable that will replace the anti-quotation, the type -- of said variable, and some arbitrary data which will then be fed to -- aqMarshaller. -- -- The Type has Void as an identifier type to make sure -- that no names appear in it. [aqParser] :: AntiQuoter a -> forall m. CParser HaskellIdentifier m => m (CIdentifier, Type CIdentifier, a) -- | Takes the requested purity, the current TypesTable, and the -- type and the body returned by aqParser. -- -- Returns the Haskell type for the parameter, and the Haskell expression -- that will be passed in as the parameter. -- -- If the the type returned is ty, the Exp must -- have type forall a. (ty -> IO a) -> IO a. This allows -- to do resource handling when preparing C values. -- -- Care must be taken regarding Purity. Specifically, the -- generated IO computation must be idempotent to guarantee its safety -- when used in pure code. We cannot prevent the IO computation from -- being inlined, hence potentially duplicated. If non-idempotent -- marshallers are required (e.g. if an update to some global state is -- needed), it is best to throw an error when Purity is -- Pure (for example "you cannot use context X with -- pure"), which will show up at compile time. [aqMarshaller] :: AntiQuoter a -> Purity -> TypesTable -> Type CIdentifier -> a -> Q (Type, Exp) -- | An identifier for a AntiQuoter. type AntiQuoterId = String -- | Existential wrapper around AntiQuoter. data SomeAntiQuoter SomeAntiQuoter :: (AntiQuoter a) -> SomeAntiQuoter type AntiQuoters = Map AntiQuoterId SomeAntiQuoter -- | A Context stores various information needed to produce the -- files with the C code derived from the inline C snippets. -- -- Contexts can be composed with their Monoid instance, -- where mappend is right-biased -- in mappend x y -- y will take precedence over x. data Context Context :: TypesTable -> AntiQuoters -> Maybe String -> Maybe (String -> String) -> Context -- | Needed to convert C types to Haskell types. [ctxTypesTable] :: Context -> TypesTable -- | Needed to parse and process antiquotations. [ctxAntiQuoters] :: Context -> AntiQuoters -- | Will determine the extension of the file containing the inline C -- snippets. [ctxFileExtension] :: Context -> Maybe String -- | This function is used to post-process the functions generated from the -- C snippets. Currently just used to specify C linkage when generating -- C++ code. [ctxOutput] :: Context -> Maybe (String -> String) -- | Context useful to work with vanilla C. Used by default. -- -- ctxTypesTable: converts C basic types to their counterparts in -- Foreign.C.Types. -- -- No ctxAntiQuoters. baseCtx :: Context -- | This Context adds support for ForeignPtr arguments. It -- adds a unique marshaller called fptr-ptr. For example, -- $fptr-ptr:$(int *x) extracts the bare C pointer out of -- foreign pointer x. fptrCtx :: Context -- | This Context includes a AntiQuoter that removes the need -- for explicitely creating FunPtrs, named "fun". -- -- For example, we can capture function f of type CInt -> -- CInt -> IO CInt in C code using $fun:(int (*f)(int, -- int)). -- -- When used in a pure embedding, the Haskell function will have -- to be pure too. Continuing the example above we'll have CInt -> -- CInt -> IO CInt. -- -- Does not include the baseCtx, since most of the time it's going -- to be included as part of larger contexts. -- -- IMPORTANT: When using the fun anti quoter, one must be aware -- that the function pointer which is automatically generated is freed -- when the code contained in the block containing the anti quoter exits. -- Thus, if you need the function pointer to be longer-lived, you must -- allocate it and free it manually using freeHaskellFunPtr. We -- provide utilities to easily allocate them (see mkFunPtr). funCtx :: Context -- | This Context includes two AntiQuoters that allow to -- easily use Haskell vectors in C. -- -- Specifically, the vec-len and vec-ptr will get the -- length and the pointer underlying mutable (IOVector) and -- immutable (Vector) storable vectors. -- -- Note that if you use vecCtx to manipulate immutable vectors you -- must make sure that the vector is not modified in the C code. -- -- To use vec-len, simply write $vec-len:x, where -- x is something of type IOVector a or -- Vector a, for some a. To use vec-ptr -- you need to specify the type of the pointer, e.g. $vec-len:(int -- *x) will work if x has type IOVector -- CInt. vecCtx :: Context -- | Type class used to implement the anti-quoters in vecCtx. class VecCtx a where type VecCtxScalar a :: * where { type family VecCtxScalar a :: *; } vecCtxLength :: VecCtx a => a -> Int vecCtxUnsafeWith :: VecCtx a => a -> (Ptr (VecCtxScalar a) -> IO b) -> IO b -- | bsCtx serves exactly the same purpose as vecCtx, but -- only for ByteString. vec-ptr becomes bs-ptr, -- and vec-len becomes bs-len. You don't need to -- specify the type of the pointer in bs-ptr, it will always be -- char*. bsCtx :: Context instance GHC.Show.Show Language.C.Inline.Context.Purity instance GHC.Classes.Eq Language.C.Inline.Context.Purity instance GHC.Base.Monoid Language.C.Inline.Context.Context instance Foreign.Storable.Storable a => Language.C.Inline.Context.VecCtx (Data.Vector.Storable.Vector a) instance Foreign.Storable.Storable a => Language.C.Inline.Context.VecCtx (Data.Vector.Storable.Mutable.IOVector a) module Language.C.Inline.Internal -- | Sets the Context for the current module. This function, if -- called, must be called before any of the other TH functions in this -- module. Fails if that's not the case. setContext :: Context -> Q () -- | Gets the current Context. Also makes sure that the current -- module is initialised. getContext :: Q Context -- | Simply appends some string to the module's C file. Use with care. emitVerbatim :: String -> DecsQ -- | Data type representing a list of C definitions with a typed and named -- entry function. -- -- We use it as a basis to inline and call C code. data Code Code :: Safety -> TypeQ -> String -> String -> Code -- | Safety of the foreign call. [codeCallSafety] :: Code -> Safety -- | Type of the foreign call. [codeType] :: Code -> TypeQ -- | Name of the function to call in the code below. [codeFunName] :: Code -> String -- | The C code. [codeDefs] :: Code -> String -- | Inlines a piece of code inline. The resulting Exp will have the -- type specified in the codeType. -- -- In practice, this function outputs the C code to the module's C file, -- and then inserts a foreign call of type codeType calling the -- provided codeFunName. -- -- Example: -- --
--   c_add :: Int -> Int -> Int
--   c_add = $(inlineCode $ Code
--     TH.Unsafe                   -- Call safety
--     [t| Int -> Int -> Int |]    -- Call type
--     "francescos_add"            -- Call name
--     -- C Code
--     "int francescos_add(int x, int y) { int z = x + y; return z; }")
--   
inlineCode :: Code -> ExpQ -- | Same as inlineCItems, but with a single expression. -- --
--   c_cos :: Double -> Double
--   c_cos = $(inlineExp
--     TH.Unsafe
--     [t| Double -> Double |]
--     (quickCParser_ "double" parseType)
--     [("x", quickCParser_ "double" parseType)]
--     "cos(x)")
--   
inlineExp :: Safety -> TypeQ -> Type CIdentifier -> [(CIdentifier, Type CIdentifier)] -> String -> ExpQ -- | Same as inlineCode, but accepts a string containing a list of C -- statements instead instead than a full-blown Code. A function -- containing the provided statement will be automatically generated. -- --
--   c_cos :: Double -> Double
--   c_cos = $(inlineItems
--     TH.Unsafe
--     [t| Double -> Double |]
--     (quickCParser_ "double" parseType)
--     [("x", quickCParser_ "double" parseType)]
--     "return cos(x);")
--   
inlineItems :: Safety -> TypeQ -> Type CIdentifier -> [(CIdentifier, Type CIdentifier)] -> String -> ExpQ data SomeEq toSomeEq :: (Eq a, Typeable a) => a -> SomeEq fromSomeEq :: (Eq a, Typeable a) => SomeEq -> Maybe a data ParameterType Plain :: HaskellIdentifier -> ParameterType AntiQuote :: AntiQuoterId -> SomeEq -> ParameterType data ParseTypedC ParseTypedC :: Type CIdentifier -> [(CIdentifier, Type CIdentifier, ParameterType)] -> String -> ParseTypedC [ptcReturnType] :: ParseTypedC -> Type CIdentifier [ptcParameters] :: ParseTypedC -> [(CIdentifier, Type CIdentifier, ParameterType)] [ptcBody] :: ParseTypedC -> String parseTypedC :: forall m. CParser HaskellIdentifier m => AntiQuoters -> m ParseTypedC runParserInQ :: String -> TypeNames -> (forall m. CParser HaskellIdentifier m => m a) -> Q a genericQuote :: Purity -> (TypeQ -> Type CIdentifier -> [(CIdentifier, Type CIdentifier)] -> String -> ExpQ) -> QuasiQuoter instance GHC.Classes.Eq Language.C.Inline.Internal.ParameterType instance GHC.Show.Show Language.C.Inline.Internal.ParameterType instance GHC.Classes.Eq Language.C.Inline.Internal.SomeEq instance GHC.Show.Show Language.C.Inline.Internal.SomeEq -- | interruptible variants of the Language.C.Inline -- quasi-quoters, to call interruptible C code. See -- https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ffi.html#ffi-interruptible -- for more information. -- -- This module is intended to be imported qualified: -- --
--   import qualified Language.C.Inline.Interruptible as CI
--   
module Language.C.Inline.Interruptible -- | C expressions. exp :: QuasiQuoter -- | Variant of exp, for use with expressions known to have no side -- effects. -- -- BEWARE: use this function with caution, only when you know what you -- are doing. If an expression does in fact have side-effects, then -- indiscriminate use of pure may endanger referential -- transparency, and in principle even type safety. pure :: QuasiQuoter -- | C code blocks (i.e. statements). block :: QuasiQuoter -- | unsafe variants of the Language.C.Inline -- quasi-quoters, to call the C code unsafely in the sense of -- https://www.haskell.org/onlinereport/haskell2010/haskellch8.html#x15-1590008.4.3. -- In GHC, unsafe foreign calls are faster than safe foreign calls, but -- the user must guarantee the control flow will never enter Haskell code -- (via a callback or otherwise) before the call is done. -- -- This module is intended to be imported qualified: -- --
--   import qualified Language.C.Inline.Unsafe as CU
--   
module Language.C.Inline.Unsafe -- | C expressions. exp :: QuasiQuoter -- | Variant of exp, for use with expressions known to have no side -- effects. -- -- BEWARE: use this function with caution, only when you know what you -- are doing. If an expression does in fact have side-effects, then -- indiscriminate use of pure may endanger referential -- transparency, and in principle even type safety. pure :: QuasiQuoter -- | C code blocks (i.e. statements). block :: QuasiQuoter -- | Enable painless embedding of C code in Haskell code. If you're -- interested in how to use the library, skip to the "Inline C" section. -- To build, read the first two sections. -- -- This module is intended to be imported qualified: -- --
--   import qualified Language.C.Inline as C
--   
module Language.C.Inline -- | A Context stores various information needed to produce the -- files with the C code derived from the inline C snippets. -- -- Contexts can be composed with their Monoid instance, -- where mappend is right-biased -- in mappend x y -- y will take precedence over x. data Context -- | Context useful to work with vanilla C. Used by default. -- -- ctxTypesTable: converts C basic types to their counterparts in -- Foreign.C.Types. -- -- No ctxAntiQuoters. baseCtx :: Context -- | This Context adds support for ForeignPtr arguments. It -- adds a unique marshaller called fptr-ptr. For example, -- $fptr-ptr:$(int *x) extracts the bare C pointer out of -- foreign pointer x. fptrCtx :: Context -- | This Context includes a AntiQuoter that removes the need -- for explicitely creating FunPtrs, named "fun". -- -- For example, we can capture function f of type CInt -> -- CInt -> IO CInt in C code using $fun:(int (*f)(int, -- int)). -- -- When used in a pure embedding, the Haskell function will have -- to be pure too. Continuing the example above we'll have CInt -> -- CInt -> IO CInt. -- -- Does not include the baseCtx, since most of the time it's going -- to be included as part of larger contexts. -- -- IMPORTANT: When using the fun anti quoter, one must be aware -- that the function pointer which is automatically generated is freed -- when the code contained in the block containing the anti quoter exits. -- Thus, if you need the function pointer to be longer-lived, you must -- allocate it and free it manually using freeHaskellFunPtr. We -- provide utilities to easily allocate them (see mkFunPtr). funCtx :: Context -- | This Context includes two AntiQuoters that allow to -- easily use Haskell vectors in C. -- -- Specifically, the vec-len and vec-ptr will get the -- length and the pointer underlying mutable (IOVector) and -- immutable (Vector) storable vectors. -- -- Note that if you use vecCtx to manipulate immutable vectors you -- must make sure that the vector is not modified in the C code. -- -- To use vec-len, simply write $vec-len:x, where -- x is something of type IOVector a or -- Vector a, for some a. To use vec-ptr -- you need to specify the type of the pointer, e.g. $vec-len:(int -- *x) will work if x has type IOVector -- CInt. vecCtx :: Context -- | bsCtx serves exactly the same purpose as vecCtx, but -- only for ByteString. vec-ptr becomes bs-ptr, -- and vec-len becomes bs-len. You don't need to -- specify the type of the pointer in bs-ptr, it will always be -- char*. bsCtx :: Context -- | Sets the Context for the current module. This function, if -- called, must be called before any of the other TH functions in this -- module. Fails if that's not the case. context :: Context -> DecsQ -- | C expressions. exp :: QuasiQuoter -- | Variant of exp, for use with expressions known to have no side -- effects. -- -- BEWARE: use this function with caution, only when you know what you -- are doing. If an expression does in fact have side-effects, then -- indiscriminate use of pure may endanger referential -- transparency, and in principle even type safety. pure :: QuasiQuoter -- | C code blocks (i.e. statements). block :: QuasiQuoter -- | Emits a CPP include directive for C code associated with the current -- module. To avoid having to escape quotes, the function itself adds -- them when appropriate, so that -- --
--   include "foo.h" ==> #include "foo.h"
--   
-- -- but -- --
--   include "<foo>" ==> #include <foo>
--   
include :: String -> DecsQ -- | Emits an arbitrary C string to the C code associated with the current -- module. Use with care. verbatim :: String -> DecsQ -- | Like alloca, but also peeks the contents of the Ptr and -- returns them once the provided action has finished. withPtr :: (Storable a) => (Ptr a -> IO b) -> IO (a, b) withPtr_ :: (Storable a) => (Ptr a -> IO ()) -> IO a -- | Type class with methods useful to allocate and peek multiple pointers -- at once: -- --
--   withPtrs_ :: (Storable a, Storable b) => ((Ptr a, Ptr b) -> IO ()) -> IO (a, b)
--   withPtrs_ :: (Storable a, Storable b, Storable c) => ((Ptr a, Ptr b, Ptr c) -> IO ()) -> IO (a, b, c)
--   ...
--   
class WithPtrs a where type WithPtrsPtrs a :: * withPtrs_ f = do { (x, _) <- withPtrs f; return x } where { type family WithPtrsPtrs a :: *; } withPtrs :: WithPtrs a => (WithPtrsPtrs a -> IO b) -> IO (a, b) withPtrs_ :: WithPtrs a => (WithPtrsPtrs a -> IO ()) -> IO a -- | $(mkFunPtr [t| CDouble -> IO -- CDouble |] generates a foreign import wrapper of type -- --
--   (CDouble -> IO CDouble) -> IO (FunPtr (CDouble -> IO CDouble))
--   
-- -- And invokes it. mkFunPtr :: TypeQ -> ExpQ -- | $(mkFunPtrFromName 'foo), if foo :: -- CDouble -> IO CDouble, splices in an -- expression of type IO (FunPtr (CDouble -- -> IO CDouble)). mkFunPtrFromName :: Name -> ExpQ -- | $(peekFunPtr [t| CDouble -> IO -- CDouble |]) generates a foreign import dynamic of type -- --
--   FunPtr (CDouble -> IO CDouble) -> (CDouble -> IO CDouble)
--   
-- -- And invokes it. peekFunPtr :: TypeQ -> ExpQ instance (Foreign.Storable.Storable a, Foreign.Storable.Storable b) => Language.C.Inline.WithPtrs (a, b) instance (Foreign.Storable.Storable a, Foreign.Storable.Storable b, Foreign.Storable.Storable c) => Language.C.Inline.WithPtrs (a, b, c) instance (Foreign.Storable.Storable a, Foreign.Storable.Storable b, Foreign.Storable.Storable c, Foreign.Storable.Storable d) => Language.C.Inline.WithPtrs (a, b, c, d) instance (Foreign.Storable.Storable a, Foreign.Storable.Storable b, Foreign.Storable.Storable c, Foreign.Storable.Storable d, Foreign.Storable.Storable e) => Language.C.Inline.WithPtrs (a, b, c, d, e) instance (Foreign.Storable.Storable a, Foreign.Storable.Storable b, Foreign.Storable.Storable c, Foreign.Storable.Storable d, Foreign.Storable.Storable e, Foreign.Storable.Storable f) => Language.C.Inline.WithPtrs (a, b, c, d, e, f) instance (Foreign.Storable.Storable a, Foreign.Storable.Storable b, Foreign.Storable.Storable c, Foreign.Storable.Storable d, Foreign.Storable.Storable e, Foreign.Storable.Storable f, Foreign.Storable.Storable g) => Language.C.Inline.WithPtrs (a, b, c, d, e, f, g)