hslua-packaging 2.2.1 → 2.3.0

raw patch · 18 files changed

+161/−69 lines, 18 filesdep +hslua-typingdep ~basedep ~hslua-coredep ~hslua-marshallingPVP ok

version bump matches the API change (PVP)

Dependencies added: hslua-typing

Dependency ranges changed: base, hslua-core, hslua-marshalling, hslua-objectorientation

API changes (from Hackage documentation)

Files

• CHANGELOG.md +28/−1
• LICENSE +1/−1
• hslua-packaging.cabal +11/−11
• src/HsLua/Packaging.hs +2/−2
• src/HsLua/Packaging/Convenience.hs +2/−2
• src/HsLua/Packaging/Documentation.hs +7/−5
• src/HsLua/Packaging/Function.hs +6/−10
• src/HsLua/Packaging/Module.hs +9/−3
• src/HsLua/Packaging/Rendering.hs +5/−9
• src/HsLua/Packaging/Types.hs +7/−4
• src/HsLua/Packaging/UDType.hs +54/−5
• test/HsLua/Packaging/DocumentationTests.hs +2/−2
• test/HsLua/Packaging/FunctionTests.hs +2/−2
• test/HsLua/Packaging/ModuleTests.hs +15/−4
• test/HsLua/Packaging/RenderingTests.hs +4/−2
• test/HsLua/Packaging/UDTypeTests.hs +2/−2
• test/HsLua/PackagingTests.hs +2/−2
• test/test-hslua-packaging.hs +2/−2

@@ -2,9 +2,36 @@  `hslua-packaging` uses [PVP Versioning][]. +## hslua-packaging-2.3.0++Released 2023-03-13.++-   Type initializers as part of Module records. This allows to+    associate types with a module. For performance reasons, the+    types are not initialized when the module is pushed, but only+    on first use. However, the documentation Lua object for each+    module now has an additional field `types`. The new field+    contains a function that returns the names of all associated+    types. Calling the function will also initialize these types,+    thereby making the respective metatables available in the+    registry.++-   *Field* records now have an additional `fieldType` entry.+    \[API change\]++-   The `pushUD` function is now specialized to documented types.++-   Export `initType`. The function ensures that the metatable of+    a type has been fully initialized. This can be helpful when+    the default method of lazy initialization is not desired, e.g.+    when the type object is to be inspected or extended.++-   Re-export `udDocs`, `udTypeSpec`, allowing to generate typing+    info for userdata classes.+ ## hslua-packaging-2.2.1 -Release pending.+Release 2022-06-19.  -   Require hslua-core-2.2.1. 

@@ -1,4 +1,4 @@-Copyright © 2019-2022 Albert Krewinkel+Copyright © 2019-2023 Albert Krewinkel  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the

@@ -1,6 +1,6 @@ cabal-version:       2.2 name:                hslua-packaging-version:             2.2.1+version:             2.3.0 synopsis:            Utilities to build Lua modules. description:         Utilities to package up Haskell functions and                      values into a Lua module.@@ -13,19 +13,18 @@ license:             MIT license-file:        LICENSE author:              Albert Krewinkel-maintainer:          albert+hslua@zeitkraut.de-copyright:           © 2019-2022 Albert Krewinkel+maintainer:          tarleb@hslua.org+copyright:           © 2019-2023 Albert Krewinkel category:            Foreign extra-source-files:  README.md                    , CHANGELOG.md-tested-with:         GHC == 8.0.2-                   , GHC == 8.2.2-                   , GHC == 8.4.4+tested-with:         GHC == 8.4.4                    , GHC == 8.6.5                    , GHC == 8.8.4                    , GHC == 8.10.3                    , GHC == 9.0.2-                   , GHC == 9.2.3+                   , GHC == 9.2.5+                   , GHC == 9.4.4  source-repository head   type:                git@@ -34,10 +33,11 @@  common common-options   default-language:    Haskell2010-  build-depends:       base                    >= 4.8    && < 5-                     , hslua-core              >= 2.2.1  && < 2.3-                     , hslua-marshalling       >= 2.2.1  && < 2.3-                     , hslua-objectorientation >= 2.2.1  && < 2.3+  build-depends:       base                    >= 4.11   && < 5+                     , hslua-core              >= 2.2.1  && < 2.4+                     , hslua-marshalling       >= 2.2.1  && < 2.4+                     , hslua-objectorientation >= 2.3    && < 2.4+                     , hslua-typing            >= 0.1    && < 0.2                      , mtl                     >= 2.2    && < 2.4                      , text                    >= 1.2    && < 2.1   ghc-options:         -Wall

@@ -1,8 +1,8 @@ {-| Module      : HsLua.Packaging-Copyright   : © 2019-2022 Albert Krewinkel+Copyright   : © 2019-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Tools to create documented Lua functions and modules. -}

@@ -1,9 +1,9 @@ {-# LANGUAGE OverloadedStrings #-} {-| Module      : HsLua.Packaging.Convenience-Copyright   : © 2021-2022 Albert Krewinkel+Copyright   : © 2021-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Convenience functions for common parameter and result types. -}

@@ -1,9 +1,9 @@ {-# LANGUAGE OverloadedStrings #-} {-| Module      : HsLua.Packaging.Documentation-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Provides a function to print documentation if available. -}@@ -21,6 +21,7 @@ import HsLua.Core as Lua import HsLua.Marshalling import HsLua.Packaging.Types+import HsLua.Typing (pushTypeSpec)  -- | Function that retrieves documentation. documentation :: LuaError e => DocumentedFunction e@@ -117,6 +118,7 @@ pushFieldDoc :: LuaError e => Pusher e (Field e) pushFieldDoc = pushAsTable   [ ("name", pushText . fieldName)+  , ("type", pushTypeSpec . fieldType)   , ("description", pushText . fieldDescription)   ] @@ -133,11 +135,11 @@   ] (functionDoc fun)  -- | Pushes the documentation of a parameter as a table with boolean--- field @optional@ and string fields @name@, @type@, and @description.+-- field @optional@ and string fields @name@, @type@, and @description@. pushParameterDoc :: LuaError e => Pusher e ParameterDoc pushParameterDoc = pushAsTable   [ ("name", pushText . parameterName)-  , ("type", pushText . parameterType)+  , ("type", pushTypeSpec . parameterType)   , ("description", pushText . parameterDescription)   , ("optional", pushBool . parameterIsOptional)   ]@@ -154,6 +156,6 @@ -- fields @type@ and @description@. pushResultValueDoc :: LuaError e => Pusher e ResultValueDoc pushResultValueDoc = pushAsTable-  [ ("type", pushText . resultValueType)+  [ ("type", pushTypeSpec . resultValueType)   , ("description", pushText . resultValueDescription)   ]

@@ -1,12 +1,11 @@ {-# LANGUAGE BangPatterns #-}-{-# LANGUAGE CPP #-} {-# LANGUAGE DeriveFunctor #-} {-# LANGUAGE OverloadedStrings #-} {-| Module      : HsLua.Packaging.Function-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org> Stability   : alpha Portability : Portable @@ -60,13 +59,10 @@ import HsLua.Marshalling import HsLua.Packaging.Documentation import HsLua.Packaging.Types+import HsLua.Typing (TypeSpec) import qualified HsLua.Core as Lua import qualified HsLua.Core.Utf8 as Utf8 -#if !MIN_VERSION_base(4,12,0)-import Data.Semigroup (Semigroup ((<>)))-#endif- -- -- Haskell function building --@@ -304,7 +300,7 @@  -- | Creates a parameter. parameter :: Peeker e a   -- ^ method to retrieve value from Lua-          -> Text         -- ^ expected Lua type+          -> TypeSpec     -- ^ expected Lua type           -> Text         -- ^ parameter name           -> Text         -- ^ parameter description           -> Parameter e a@@ -331,7 +327,7 @@ -- -- DEPRECATED: Use @opt (parameter ...)@ instead. optionalParameter :: Peeker e a   -- ^ method to retrieve the value from Lua-                  -> Text         -- ^ expected Lua type+                  -> TypeSpec     -- ^ expected Lua type                   -> Text         -- ^ parameter name                   -> Text         -- ^ parameter description                   -> Parameter e (Maybe a)@@ -341,7 +337,7 @@  -- | Creates a function result. functionResult :: Pusher e a      -- ^ method to push the Haskell result to Lua-               -> Text            -- ^ Lua type of result+               -> TypeSpec        -- ^ Lua type of result                -> Text            -- ^ result description                -> FunctionResults e a functionResult pusher type_ desc = (:[]) $ FunctionResult

@@ -1,9 +1,9 @@ {-# LANGUAGE OverloadedStrings #-} {-| Module      : HsLua.Packaging.Module-Copyright   : © 2019-2022 Albert Krewinkel+Copyright   : © 2019-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <albert+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org> Stability   : alpha Portability : Requires GHC 8 or later. @@ -23,7 +23,7 @@  import Control.Monad (forM_) import HsLua.Core-import HsLua.Marshalling (pushAsTable, pushList, pushName, pushText)+import HsLua.Marshalling (Pusher, pushAsTable, pushList, pushName, pushText) import HsLua.ObjectOrientation.Operation (Operation (..), metamethodName) import HsLua.Packaging.Documentation import HsLua.Packaging.Types@@ -60,6 +60,7 @@     [ ("name", pushName . moduleName)     , ("description", pushText . moduleDescription)     , ("fields", pushList pushFieldDoc . moduleFields)+    , ("types", pushTypesFunction . moduleTypeInitializers)     ] mdl   create        -- module table   pushvalue (nth 2)              -- push documentation object@@ -106,3 +107,8 @@         Fun.pushDocumentedFunction $ Fun.setName "" fn         rawset (nth 3)       setmetatable (nth 2)++pushTypesFunction :: LuaError e => Pusher e [LuaE e Name]+pushTypesFunction initializers = pushHaskellFunction $ do+  sequence initializers >>= pushList pushName+  pure 1

@@ -1,11 +1,10 @@-{-# LANGUAGE CPP #-} {-# LANGUAGE LambdaCase #-} {-# LANGUAGE OverloadedStrings #-} {-| Module      : HsLua.Packaging.Rendering-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org> Stability   : alpha Portability : Portable @@ -23,14 +22,11 @@ import Data.Version (showVersion) import HsLua.Core import HsLua.Packaging.Types+import HsLua.Typing (typeSpecToString) import qualified Data.Text as T import qualified Data.Text.Encoding as T import qualified HsLua.Core.Utf8 as Utf8 -#if !MIN_VERSION_base(4,12,0)-import Data.Semigroup (Semigroup ((<>)))-#endif- -- -- Module documentation --@@ -122,7 +118,7 @@   [ parameterName pd   ,  "\n:   "   , parameterDescription pd-  , " (", parameterType pd, ")\n"+  , " (", T.pack (typeSpecToString (parameterType pd)), ")\n"   ]  -- | Renders the documentation of a function result as a Markdown list@@ -140,7 +136,7 @@ renderResultValueDoc rd = mconcat   [ " -  "   , resultValueDescription rd-  , " (", resultValueType rd, ")"+  , " (", T.pack (typeSpecToString $ resultValueType rd), ")"   ]  indent :: Int -> Text -> Text

@@ -1,8 +1,8 @@ {-| Module      : HsLua.Packaging.Types-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org> Stability   : alpha Portability : Portable @@ -25,6 +25,7 @@ import Data.Version (Version) import HsLua.Core (LuaE, Name, NumResults) import HsLua.ObjectOrientation (Operation)+import HsLua.Typing (TypeSpec)  -- | Named and documented Lua module. data Module e = Module@@ -33,11 +34,13 @@   , moduleFields :: [Field e]   , moduleFunctions :: [DocumentedFunction e]   , moduleOperations :: [(Operation, DocumentedFunction e)]+  , moduleTypeInitializers :: [LuaE e Name]   }  -- | Self-documenting module field data Field e = Field   { fieldName :: Text+  , fieldType :: TypeSpec   , fieldDescription :: Text   , fieldPushValue :: LuaE e ()   }@@ -71,7 +74,7 @@ -- | Documentation for function parameters. data ParameterDoc = ParameterDoc   { parameterName :: Text-  , parameterType :: Text+  , parameterType :: TypeSpec   , parameterDescription :: Text   , parameterIsOptional :: Bool   }@@ -85,7 +88,7 @@  -- | Documentation for a single return value of a function. data ResultValueDoc = ResultValueDoc-  { resultValueType :: Text+  { resultValueType :: TypeSpec   , resultValueDescription :: Text   }   deriving (Eq, Ord, Show)

@@ -1,8 +1,9 @@+{-# LANGUAGE OverloadedStrings #-} {-| Module      : HsLua.Packaging.UDType-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  This module provides types and functions to use Haskell values as userdata objects in Lua. These objects wrap a Haskell value and provide@@ -18,14 +19,20 @@   , deftype'   , method   , property+  , property'   , possibleProperty+  , possibleProperty'   , readonly+  , readonly'   , alias   , operation   , peekUD   , pushUD+  , initType   , udparam   , udresult+  , udDocs+  , udTypeSpec     -- * Helper types for building   , Member   , Operation (..)@@ -33,12 +40,15 @@   , Possible (..)   ) where +import Data.Map (Map) import Data.Text (Text) import HsLua.Core+import HsLua.Marshalling import HsLua.ObjectOrientation import HsLua.ObjectOrientation.Operation (metamethodName) import HsLua.Packaging.Function-import qualified HsLua.Core.Utf8 as Utf8+import HsLua.Typing (pushTypeSpec)+import qualified Data.Map as Map  -- | Type definitions containing documented functions. type DocumentedType e a = UDType e (DocumentedFunction e) a@@ -87,11 +97,50 @@         -> Text            -- ^ parameter name         -> Text            -- ^ parameter description         -> Parameter e a-udparam ty = parameter (peekUD ty) (Utf8.toText . fromName $ udName ty)+udparam ty = parameter (peekUDGeneric ty) (udTypeSpec ty)  -- | Defines a function result of the given type. udresult :: LuaError e          => DocumentedTypeWithList e a itemtype -- ^ result type          -> Text           -- ^ result description          -> FunctionResults e a-udresult ty = functionResult (pushUD ty) (Utf8.toText . fromName $ udName ty)+udresult ty = functionResult (pushUD ty) (udTypeSpec ty)++-- | Pushes a userdata value of the given type.+pushUD :: LuaError e => DocumentedTypeWithList e a itemtype -> a -> LuaE e ()+pushUD = pushUDGeneric pushUDTypeDocs++-- | Retrieves a userdata value of the given type.+peekUD :: LuaError e => DocumentedTypeWithList e a itemtype -> Peeker e a+peekUD = peekUDGeneric++-- | Ensures that the type has been fully initialized, i.e., that all+-- metatables have been created and stored in the registry. Returns the+-- name of the initialized type.+initType :: LuaError e+         => DocumentedTypeWithList e a itemtype+         -> LuaE e Name+initType = initTypeGeneric pushUDTypeDocs++-- | Pushes a documentation table for the given UD type.+pushUDTypeDocs :: LuaError e+               => DocumentedTypeWithList e a itemtype+               -> LuaE e ()+pushUDTypeDocs ty = do+  -- metadata table is at the top of the stack+  pushName "docs"+  pushAsTable+    [ ("name", pushName . udName)+    , ("properties", pushPropertyDocs . udProperties)+    ] ty+  rawset (nth 3)++pushPropertyDocs :: LuaError e+                 => Map Name (Property e a)+                 -> LuaE e ()+pushPropertyDocs = pushKeyValuePairs pushName pushPropDocs . Map.toList+  where+    pushPropDocs = pushAsTable+      [ ("description", pushText . propertyDescription)+      , ("type", pushTypeSpec . propertyType)+      ]

@@ -2,9 +2,9 @@ {-# LANGUAGE TypeApplications #-} {-| Module      : HsLua.Packaging.DocumentationTests-Copyright   : © 2021-2022 Albert Krewinkel+Copyright   : © 2021-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Tests for calling exposed Haskell functions. -}

@@ -2,9 +2,9 @@ {-# LANGUAGE TypeApplications #-} {-| Module      : HsLua.Packaging.FunctionTests-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Tests for calling exposed Haskell functions. -}

@@ -2,9 +2,9 @@ {-# LANGUAGE TypeApplications #-} {-| Module      : HsLua.Packaging.ModuleTests-Copyright   : © 2019-2022 Albert Krewinkel+Copyright   : © 2019-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <albert+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org> Stability   : alpha Portability : Requires GHC 8 or later. @@ -14,11 +14,12 @@  import HsLua.Core import HsLua.Marshalling-  ( forcePeek, peekFieldRaw, peekIntegral, peekString+  ( forcePeek, peekFieldRaw, peekIntegral, peekList, peekName, peekString   , pushIntegral, pushText) import HsLua.Packaging.Documentation import HsLua.Packaging.Function import HsLua.Packaging.Module+import HsLua.Packaging.UDType (deftype, initType) import Test.Tasty.HsLua ((=:), shouldBeResultOf) import Test.Tasty (TestTree, testGroup) @@ -99,6 +100,15 @@         TypeTable <- getfield top "fields"         TypeTable <- rawgeti top 1         forcePeek $ peekFieldRaw peekString "name" Lua.top++    , "document object has associated types" =:+      ["Void"] `shouldBeResultOf` do+        Lua.openlibs+        registerModule mymath+        TypeTable <- getdocumentation top+        TypeFunction <- getfield top "types"+        call 0 1+        forcePeek $ peekList peekName top     ]   ] @@ -107,7 +117,7 @@   { moduleName = "mymath"   , moduleDescription = "A math module."   , moduleFields = [-      Field "unit" "additive unit" (pushinteger 1)+      Field "unit" "integer" "additive unit" (pushinteger 1)     ]   , moduleFunctions = [factorial]   , moduleOperations =@@ -115,6 +125,7 @@       ### (1 <$ pushText "call me maybe")       =?> "call result"     ]+  , moduleTypeInitializers = [initType (deftype "Void" [] [])]   }  factorial :: DocumentedFunction Lua.Exception

@@ -3,9 +3,9 @@ {-# OPTIONS_GHC -Wno-warnings-deprecations #-} {-| Module      : HsLua.Packaging.RenderingTests-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Tests for calling exposed Haskell functions. -}@@ -108,12 +108,14 @@   , moduleFields = [euler_mascheroni]   , moduleFunctions = [ factorial, nroot ]   , moduleOperations = []+  , moduleTypeInitializers = []   }  -- | Euler-Mascheroni constant euler_mascheroni :: Field Lua.Exception euler_mascheroni = Field   { fieldName = "euler_mascheroni"+  , fieldType = "number"   , fieldDescription = "Euler-Mascheroni constant"   , fieldPushValue = pushRealFloat @Double                      0.57721566490153286060651209008240243

@@ -3,9 +3,9 @@ {-# LANGUAGE TypeApplications #-} {-| Module      : HsLua.Packaging.UDTypeTests-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Tests for calling exposed Haskell functions. -}

@@ -1,8 +1,8 @@ {-| Module      : HsLua.PackagingTests-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Test packaging -}

@@ -1,8 +1,8 @@ {-| Module      : Main-Copyright   : © 2020-2022 Albert Krewinkel+Copyright   : © 2020-2023 Albert Krewinkel License     : MIT-Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>+Maintainer  : Albert Krewinkel <tarleb@hslua.org>  Tests for hslua-packaging. -}