Support.hs

{-# LANGUAGE MagicHash #-}
{-# OPTIONS_HADDOCK hide #-}

-- | Support prelude of generated bindings
--
-- Re-exports the definitions that generated code needs from modules meant for
-- unqualified import, be they in @base@, in other libraries, or in
-- @hs-bindgen-runtime@. Generated code imports modules meant for qualified
-- import, such as "HsBindgen.Runtime.Marshal", directly instead, and imports a
-- curated set of "Prelude" names unqualified; see @dev\/generated-code.md@.
--
-- This module also bridges differences between GHC and @base@ versions.
--
-- We maintain minimal lists of explicit imports and exports. Exports are
-- grouped like the constructors of @BindgenGlobalType@ and
-- @BindgenGlobalTerm@ in @HsBindgen.Backend.Global@ (package @hs-bindgen@).
--
-- Intended for qualified import.
--
-- @
-- import HsBindgen.Runtime.Support qualified as BG
-- @
module HsBindgen.Runtime.Support (
  -- * Function pointers
  ToFunPtr (toFunPtr),
  FromFunPtr (fromFunPtr),

  -- * Foreign function interface
  Ptr (Ptr),
  FunPtr,
  StablePtr,
  plusPtr,
  castFunPtr,
  getUnionPayload,
  setUnionPayload,
  getUnionPayloadBits,
  setUnionPayloadBits,
  with,
  allocaAndPeek,
  Generic,

  -- * 'Storable'
  Storable (sizeOf, alignment, peekByteOff, pokeByteOff, peek, poke),

  -- * 'HasField'
  HasField (getField),

  -- * Proxy
  Proxy (Proxy),

  -- * 'HasFFIType'
  HasFFIType (fromFFIType, toFFIType),
  PtrVoid,
  FunPtrVoid,

  -- * Unsafe
  unsafePerformIO,

  -- * Primitive
  Prim (
    sizeOf#,
    alignment#,
    indexByteArray#,
    readByteArray#,
    writeByteArray#,
    indexOffAddr#,
    readOffAddr#,
    writeOffAddr#
  ),
  (+#),
  (*#),

  -- * Other type classes
  Bitfield,
  Bits,
  FiniteBits,
  Ix,
  readPrec,
  readList,
  readListPrec,
  readListDefault,
  readListPrecDefault,
  showsPrec,
  -- Floating point numbers
  castWord32ToFloat,
  castWord64ToDouble,
  -- The CFloat and CDouble constructors are exported below, together with
  -- their types.

  -- Non-empty lists
  NonEmpty ((:|)),
  singleton,
  -- Arrays
  ByteArray,
  SizedByteArray (SizedByteArray),
  -- ByteString
  BS.ByteString,
  BS.pack,
  -- Complex numbers
  Complex,
  -- C types
  Void,
  Int8,
  Int16,
  Int32,
  Int64,
  Word8,
  Word16,
  Word32,
  Word64,
  CChar (CChar),
  CSChar (CSChar),
  CUChar (CUChar),
  CShort (CShort),
  CUShort (CUShort),
  CInt (CInt),
  CUInt (CUInt),
  CLong (CLong),
  CULong (CULong),
  CLLong (CLLong),
  CULLong (CULLong),
  CBool (CBool),
  CFloat (CFloat),
  CDouble (CDouble),
  CStringLen,
  CPtrdiff,
) where

import Data.Array.Byte (ByteArray)
import Data.Bits (Bits, FiniteBits)
import Data.ByteString qualified as BS (ByteString, pack)
import Data.Complex (Complex)
import Data.Int (Int16, Int32, Int64, Int8)
import Data.Ix (Ix)
import Data.List.NonEmpty (NonEmpty ((:|)), singleton)
import Data.Primitive.Types (
  Prim (
    alignment#,
    indexByteArray#,
    indexOffAddr#,
    readByteArray#,
    readOffAddr#,
    sizeOf#,
    writeByteArray#,
    writeOffAddr#
  ),
 )
import Data.Proxy (Proxy (Proxy))
import Data.Void (Void)
import Data.Word (Word16, Word32, Word64, Word8)
import Foreign (
  Storable (alignment, peek, peekByteOff, poke, pokeByteOff, sizeOf),
  castFunPtr,
  with,
 )
import Foreign.C (
  CBool (CBool),
  CChar (CChar),
  CDouble (CDouble),
  CFloat (CFloat),
  CInt (CInt),
  CLLong (CLLong),
  CLong (CLong),
  CPtrdiff,
  CSChar (CSChar),
  CShort (CShort),
  CUChar (CUChar),
  CUInt (CUInt),
  CULLong (CULLong),
  CULong (CULong),
  CUShort (CUShort),
 )
import Foreign.C.String (CStringLen)
import Foreign.StablePtr (StablePtr)
import GHC.Base ((*#), (+#))
import GHC.Float (castWord32ToFloat, castWord64ToDouble)
import GHC.Generics (Generic)
import GHC.Ptr (FunPtr, Ptr (Ptr), plusPtr)
import GHC.Records (HasField (getField))
import System.IO.Unsafe (unsafePerformIO)
import Text.Read (readListDefault, readListPrec, readListPrecDefault, readPrec)

import HsBindgen.Runtime.HasFFIType (
  FunPtrVoid,
  HasFFIType (fromFFIType, toFFIType),
  PtrVoid,
 )
import HsBindgen.Runtime.Support.Bitfield (Bitfield)
import HsBindgen.Runtime.Support.ByteArray (
  getUnionPayload,
  getUnionPayloadBits,
  setUnionPayload,
  setUnionPayloadBits,
 )
import HsBindgen.Runtime.Support.CAPI (allocaAndPeek)
import HsBindgen.Runtime.Support.FunPtr (
  FromFunPtr (fromFunPtr),
  ToFunPtr (toFunPtr),
 )
import HsBindgen.Runtime.Support.SizedByteArray (SizedByteArray (SizedByteArray))