| Safe Haskell | Safe-Inferred |
|---|---|
| Language | GHC2021 |
HsBindgen.TH
Description
Main entry point for using hs-bindgen in Template-Haskell mode.
Intended for unqualified import.
Synopsis
- withHsBindgen :: Config -> ConfigTH -> BindgenM -> Q [Dec]
- hashInclude :: FilePath -> BindgenM
- type Config = Config_ IncludeDir
- data Config_ path = Config {}
- data ConfigTH = ConfigTH {}
- data ClangArgsConfig path = ClangArgsConfig {
- builtinIncDir :: BuiltinIncDirConfig
- extraIncludeDirs :: [path]
- defineMacros :: [String]
- enableBlocks :: Bool
- argsBefore :: [String]
- argsInner :: [String]
- argsAfter :: [String]
- data BuiltinIncDirConfig
- data IncludeDir
- data BindingSpecConfig = BindingSpecConfig {}
- data EnableStdlibBindingSpec
- data BindingSpecCompatibility
- data Boolean a
- data HeaderPathPredicate
- data Regex
- data ParsePredicate = ParseHeader HeaderPathPredicate
- data DeclPredicate
- data SelectPredicate
- data ProgramSlicing
- data ByCategory (f :: CategoryLvl -> Star) = ByCategory {}
- data Choice (lvl :: CategoryLvl) where
- ExcludeCategory :: forall (lvl :: CategoryLvl). Choice lvl
- IncludeTypeCategory :: Choice 'LvlType
- IncludeTermCategory :: RenameTerm -> Choice 'LvlTerm
- newtype RenameTerm = RenameTerm (Text -> Text)
- useSafeCategory :: ByCategory Choice
- useUnsafeCategory :: ByCategory Choice
- useFunPtrCategory :: ByCategory Choice
- data PathStyle
- newtype Verbosity = Verbosity {}
- data Level
- data CustomLogLevelSetting
- class Default a where
- def :: a
- module HsBindgen.Runtime.Internal.Deriving
Documentation
withHsBindgen :: Config -> ConfigTH -> BindgenM -> Q [Dec] #
Generate bindings for given C headers at compile-time
Use together with hashInclude, which acts in the BindgenM monad.
For example,
withHsBindgen def def $ do hashInclude "foo.h" hashInclude "bar.h"
hashInclude :: FilePath -> BindgenM #
#include (i.e., generate bindings for) a C header
For example, the Haskell code,
hashInclude "a.h"
corresponds to the following C code using angular brackets,
#include <a.h>
See withHsBindgen.
Configuration
type Config = Config_ IncludeDir #
Configuration with C include directories
C include directories can be provided relative to the package root (see the
IncludeDir data constructor Pkg).
User-provided configuration shared between client commands and Template-Haskell mode
Constructors
| Config | |
Instances
Configuration specific to Template-Haskell mode
Constructors
| ConfigTH | |
Fields
| |
Instances
| Generic ConfigTH | |
| Default ConfigTH | |
Defined in HsBindgen.Config | |
| type Rep ConfigTH | |
Defined in HsBindgen.Config type Rep ConfigTH = D1 ('MetaData "ConfigTH" "HsBindgen.Config" "hs-bindgen-0.1.0-inplace-internal" 'False) (C1 ('MetaCons "ConfigTH" 'PrefixI 'True) (S1 ('MetaSel ('Just "categoryChoice") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (ByCategory Choice)) :*: (S1 ('MetaSel ('Just "verbosity") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Verbosity) :*: S1 ('MetaSel ('Just "customLogLevels") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [CustomLogLevelSetting])))) | |
Clang arguments
data ClangArgsConfig path #
Configuration of libclang command-line arguments
ClangArgsConfig is not intended to be complete; instead, we have added
configuration options most relevant to hs-bindgen. Pass other
configurations options directly using command line arguments (argsBefore,
argsInner, and argsAfter).
Configuration of the C standard must be done via one of these options.
hs-bindgen queries libclang to get the C standard.
Constructors
| ClangArgsConfig | |
Fields
| |
Instances
data BuiltinIncDirConfig #
Configure builtin include directory automatic configuration
Constructors
| BuiltinIncDirDisable | Do not configure the builtin include directory |
| BuiltinIncDirClang | Configure the builtin include directory using the resource directory
from |
Instances
| Show BuiltinIncDirConfig | |
Defined in HsBindgen.Config.ClangArgs Methods showsPrec :: Int -> BuiltinIncDirConfig -> ShowS # show :: BuiltinIncDirConfig -> String # showList :: [BuiltinIncDirConfig] -> ShowS # | |
| Default BuiltinIncDirConfig | |
Defined in HsBindgen.Config.ClangArgs Methods | |
| Eq BuiltinIncDirConfig | |
Defined in HsBindgen.Config.ClangArgs Methods (==) :: BuiltinIncDirConfig -> BuiltinIncDirConfig -> Bool # (/=) :: BuiltinIncDirConfig -> BuiltinIncDirConfig -> Bool # | |
data IncludeDir #
C include directory added to the C include search path
Instances
| Generic IncludeDir | |
Defined in HsBindgen.TH.Internal Associated Types type Rep IncludeDir :: Type -> Type # | |
| Show IncludeDir | |
Defined in HsBindgen.TH.Internal Methods showsPrec :: Int -> IncludeDir -> ShowS # show :: IncludeDir -> String # showList :: [IncludeDir] -> ShowS # | |
| Eq IncludeDir | |
Defined in HsBindgen.TH.Internal | |
| type Rep IncludeDir | |
Defined in HsBindgen.TH.Internal type Rep IncludeDir = D1 ('MetaData "IncludeDir" "HsBindgen.TH.Internal" "hs-bindgen-0.1.0-inplace-internal" 'False) (C1 ('MetaCons "Dir" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FilePath)) :+: C1 ('MetaCons "Pkg" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FilePath))) | |
Binding specifications
data BindingSpecConfig #
Constructors
| BindingSpecConfig | |
Instances
data EnableStdlibBindingSpec #
Configure if the stdlib binding specification should be used
Constructors
| EnableStdlibBindingSpec | Automatically include |
| DisableStdlibBindingSpec | Do not include |
Instances
| Show EnableStdlibBindingSpec | |
Defined in HsBindgen.BindingSpec Methods showsPrec :: Int -> EnableStdlibBindingSpec -> ShowS # show :: EnableStdlibBindingSpec -> String # showList :: [EnableStdlibBindingSpec] -> ShowS # | |
| Default EnableStdlibBindingSpec | |
Defined in HsBindgen.BindingSpec Methods | |
| Eq EnableStdlibBindingSpec | |
Defined in HsBindgen.BindingSpec Methods (==) :: EnableStdlibBindingSpec -> EnableStdlibBindingSpec -> Bool # (/=) :: EnableStdlibBindingSpec -> EnableStdlibBindingSpec -> Bool # | |
data BindingSpecCompatibility #
Binding specification compatibility strictness
Constructors
| BindingSpecStrict | Do not allow newer minor versions |
| BindingSpecAllowNewer | Allow newer minor versions |
Instances
| Show BindingSpecCompatibility | |
Defined in HsBindgen.BindingSpec.Private.Version Methods showsPrec :: Int -> BindingSpecCompatibility -> ShowS # show :: BindingSpecCompatibility -> String # showList :: [BindingSpecCompatibility] -> ShowS # | |
| Default BindingSpecCompatibility | |
Defined in HsBindgen.BindingSpec.Private.Version Methods | |
| Eq BindingSpecCompatibility | |
Defined in HsBindgen.BindingSpec.Private.Version Methods (==) :: BindingSpecCompatibility -> BindingSpecCompatibility -> Bool # (/=) :: BindingSpecCompatibility -> BindingSpecCompatibility -> Bool # | |
Predicates and program slicing
Boolean logic combining predicates that determine which declarations should be kept
Constructors
| BTrue | Match any declaration |
| BFalse | Match no declaration |
| BAnd (Boolean a) (Boolean a) | Logical conjunction |
| BOr (Boolean a) (Boolean a) | Logical disjunction |
| BNot (Boolean a) | Logical negation |
| BIf a | Concrete predicates |
Instances
data HeaderPathPredicate #
Predicates matched against header paths
Constructors
| FromMainHeaders | Only include declarations in main headers (not included headers) |
| FromMainHeaderDirs | Only include declarations in headers in main header directories, including subdirectories |
| HeaderPathMatches Regex | Match header path against regex |
Instances
Perl-compatible regular expression
Parse predicates
data ParsePredicate #
Predicates for the Parse pass
Parse predicates match against header file paths only.
The parse predicate and the select predicate both allow matching against
header paths but serve different purposes. The parse predicate dictates which
declarations `hs-bindgen` reifies into `hs-bindgen`-specific data structures,
the select predicate dictates which declarations `hs-bindgen` generates
bindings for. For details, please see the hs-bindgen manual section on
predicates and program slicing.
Constructors
| ParseHeader HeaderPathPredicate |
Instances
Select predicates and program slicing
data DeclPredicate #
Predicates matched against declarations themselves
Constructors
| DeclNameMatches Regex | Match declaration name against regex |
| DeclDeprecated | Match deprecated declarations taking current target platform into
account; see |
Instances
| Generic DeclPredicate | |
Defined in HsBindgen.Frontend.Predicate Associated Types type Rep DeclPredicate :: Type -> Type # | |
| Show DeclPredicate | |
Defined in HsBindgen.Frontend.Predicate Methods showsPrec :: Int -> DeclPredicate -> ShowS # show :: DeclPredicate -> String # showList :: [DeclPredicate] -> ShowS # | |
| Eq DeclPredicate | |
Defined in HsBindgen.Frontend.Predicate Methods (==) :: DeclPredicate -> DeclPredicate -> Bool # (/=) :: DeclPredicate -> DeclPredicate -> Bool # | |
| type Rep DeclPredicate | |
Defined in HsBindgen.Frontend.Predicate type Rep DeclPredicate = D1 ('MetaData "DeclPredicate" "HsBindgen.Frontend.Predicate" "hs-bindgen-0.1.0-inplace-internal" 'False) (C1 ('MetaCons "DeclNameMatches" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Regex)) :+: C1 ('MetaCons "DeclDeprecated" 'PrefixI 'False) (U1 :: Type -> Type)) | |
data SelectPredicate #
Predicates for the Select pass
Select predicates match against header file paths or the declarations themselves.
The parse predicate and the select predicate both allow matching against
header paths but serve different purposes. The parse predicate dictates which
declarations `hs-bindgen` reifies into `hs-bindgen`-specific data structures,
the select predicate dictates which declarations `hs-bindgen` generates
bindings for. For details, please see the hs-bindgen manual section on
predicates and program slicing.
Constructors
| SelectHeader HeaderPathPredicate | |
| SelectDecl DeclPredicate |
Instances
data ProgramSlicing #
Select transitive dependencies?
Constructors
| EnableProgramSlicing | Select declarations using the select predicate and their transitive dependencies. |
| DisableProgramSlicing |
Instances
| Show ProgramSlicing | |
Defined in HsBindgen.Frontend.Pass.Select.IsPass Methods showsPrec :: Int -> ProgramSlicing -> ShowS # show :: ProgramSlicing -> String # showList :: [ProgramSlicing] -> ShowS # | |
| Default ProgramSlicing | |
Defined in HsBindgen.Frontend.Pass.Select.IsPass Methods def :: ProgramSlicing # | |
| Eq ProgramSlicing | |
Defined in HsBindgen.Frontend.Pass.Select.IsPass Methods (==) :: ProgramSlicing -> ProgramSlicing -> Bool # (/=) :: ProgramSlicing -> ProgramSlicing -> Bool # | |
Binding categories
data ByCategory (f :: CategoryLvl -> Star) #
A strict, total map from Category to a.
Constructors
| ByCategory | |
Instances
data Choice (lvl :: CategoryLvl) where #
Include or exclude categories.
Possibly rename declarations in categories of Level LvlTerm. We only
allow renaming of LvlTerm because for LvlType we would also need to
rename the use sites, instances etc.
Constructors
| ExcludeCategory :: forall (lvl :: CategoryLvl). Choice lvl | |
| IncludeTypeCategory :: Choice 'LvlType | |
| IncludeTermCategory :: RenameTerm -> Choice 'LvlTerm |
newtype RenameTerm #
Constructors
| RenameTerm (Text -> Text) |
Instances
| Show RenameTerm | |
Defined in HsBindgen.Backend.Category Methods showsPrec :: Int -> RenameTerm -> ShowS # show :: RenameTerm -> String # showList :: [RenameTerm] -> ShowS # | |
| Default RenameTerm | |
Defined in HsBindgen.Backend.Category Methods def :: RenameTerm # | |
Haddocks
Path style used in generated Haddock comments
Tracer
Log or verbosity level.
Careful, the derived Ord instance is used when determining if a trace
should be emitted, or not.
Constructors
| Debug | Useful only for debugging hs-bindgen itself |
| Info | Regular progress, perhaps useful for debugging hs-bindgen config E.g.: "Why why |
| Notice | Normal but significant condition the user should be aware of E.g.: "binding global variable may result in duplicate symbols" |
| Warning | We may produce incomplete bindings |
| Error | We are unable to produce any bindings at all |
Instances
data CustomLogLevelSetting #
List of predefined log level customization settings.
Constructors
| MakeTrace Level TraceId | |
| MakeWarningsErrors | |
| EnableMacroWarnings | Set the log level of macro-related parsing traces to Reparse and typechecking errors may indicate that something went wrong, or they may be caused by macro syntax that we do not yet support. By default, traces emitted while parsing macros have log level |
Instances
| Show CustomLogLevelSetting | |
Defined in HsBindgen.TraceMsg Methods showsPrec :: Int -> CustomLogLevelSetting -> ShowS # show :: CustomLogLevelSetting -> String # showList :: [CustomLogLevelSetting] -> ShowS # | |
| Eq CustomLogLevelSetting | |
Defined in HsBindgen.TraceMsg Methods (==) :: CustomLogLevelSetting -> CustomLogLevelSetting -> Bool # (/=) :: CustomLogLevelSetting -> CustomLogLevelSetting -> Bool # | |
| Ord CustomLogLevelSetting | |
Defined in HsBindgen.TraceMsg Methods compare :: CustomLogLevelSetting -> CustomLogLevelSetting -> Ordering # (<) :: CustomLogLevelSetting -> CustomLogLevelSetting -> Bool # (<=) :: CustomLogLevelSetting -> CustomLogLevelSetting -> Bool # (>) :: CustomLogLevelSetting -> CustomLogLevelSetting -> Bool # (>=) :: CustomLogLevelSetting -> CustomLogLevelSetting -> Bool # max :: CustomLogLevelSetting -> CustomLogLevelSetting -> CustomLogLevelSetting # min :: CustomLogLevelSetting -> CustomLogLevelSetting -> CustomLogLevelSetting # | |
Re-exports
A class for types with a default value.
Minimal complete definition
Nothing