diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -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 diff --git a/hslua-packaging.cabal b/hslua-packaging.cabal --- a/hslua-packaging.cabal +++ b/hslua-packaging.cabal @@ -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 diff --git a/src/HsLua/Packaging.hs b/src/HsLua/Packaging.hs --- a/src/HsLua/Packaging.hs +++ b/src/HsLua/Packaging.hs @@ -1,8 +1,8 @@ {-| Module : HsLua.Packaging -Copyright : © 2019-2022 Albert Krewinkel +Copyright : © 2019-2023 Albert Krewinkel License : MIT -Maintainer : Albert Krewinkel +Maintainer : Albert Krewinkel Tools to create documented Lua functions and modules. -} diff --git a/src/HsLua/Packaging/Convenience.hs b/src/HsLua/Packaging/Convenience.hs --- a/src/HsLua/Packaging/Convenience.hs +++ b/src/HsLua/Packaging/Convenience.hs @@ -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 +Maintainer : Albert Krewinkel Convenience functions for common parameter and result types. -} diff --git a/src/HsLua/Packaging/Documentation.hs b/src/HsLua/Packaging/Documentation.hs --- a/src/HsLua/Packaging/Documentation.hs +++ b/src/HsLua/Packaging/Documentation.hs @@ -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 +Maintainer : Albert Krewinkel 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) ] diff --git a/src/HsLua/Packaging/Function.hs b/src/HsLua/Packaging/Function.hs --- a/src/HsLua/Packaging/Function.hs +++ b/src/HsLua/Packaging/Function.hs @@ -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 +Maintainer : Albert Krewinkel 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 diff --git a/src/HsLua/Packaging/Module.hs b/src/HsLua/Packaging/Module.hs --- a/src/HsLua/Packaging/Module.hs +++ b/src/HsLua/Packaging/Module.hs @@ -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 +Maintainer : Albert Krewinkel 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 diff --git a/src/HsLua/Packaging/Rendering.hs b/src/HsLua/Packaging/Rendering.hs --- a/src/HsLua/Packaging/Rendering.hs +++ b/src/HsLua/Packaging/Rendering.hs @@ -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 +Maintainer : Albert Krewinkel 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 diff --git a/src/HsLua/Packaging/Types.hs b/src/HsLua/Packaging/Types.hs --- a/src/HsLua/Packaging/Types.hs +++ b/src/HsLua/Packaging/Types.hs @@ -1,8 +1,8 @@ {-| Module : HsLua.Packaging.Types -Copyright : © 2020-2022 Albert Krewinkel +Copyright : © 2020-2023 Albert Krewinkel License : MIT -Maintainer : Albert Krewinkel +Maintainer : Albert Krewinkel 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) diff --git a/src/HsLua/Packaging/UDType.hs b/src/HsLua/Packaging/UDType.hs --- a/src/HsLua/Packaging/UDType.hs +++ b/src/HsLua/Packaging/UDType.hs @@ -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 +Maintainer : Albert Krewinkel 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) + ] diff --git a/test/HsLua/Packaging/DocumentationTests.hs b/test/HsLua/Packaging/DocumentationTests.hs --- a/test/HsLua/Packaging/DocumentationTests.hs +++ b/test/HsLua/Packaging/DocumentationTests.hs @@ -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 +Maintainer : Albert Krewinkel Tests for calling exposed Haskell functions. -} diff --git a/test/HsLua/Packaging/FunctionTests.hs b/test/HsLua/Packaging/FunctionTests.hs --- a/test/HsLua/Packaging/FunctionTests.hs +++ b/test/HsLua/Packaging/FunctionTests.hs @@ -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 +Maintainer : Albert Krewinkel Tests for calling exposed Haskell functions. -} diff --git a/test/HsLua/Packaging/ModuleTests.hs b/test/HsLua/Packaging/ModuleTests.hs --- a/test/HsLua/Packaging/ModuleTests.hs +++ b/test/HsLua/Packaging/ModuleTests.hs @@ -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 +Maintainer : Albert Krewinkel 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 diff --git a/test/HsLua/Packaging/RenderingTests.hs b/test/HsLua/Packaging/RenderingTests.hs --- a/test/HsLua/Packaging/RenderingTests.hs +++ b/test/HsLua/Packaging/RenderingTests.hs @@ -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 +Maintainer : Albert Krewinkel 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 diff --git a/test/HsLua/Packaging/UDTypeTests.hs b/test/HsLua/Packaging/UDTypeTests.hs --- a/test/HsLua/Packaging/UDTypeTests.hs +++ b/test/HsLua/Packaging/UDTypeTests.hs @@ -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 +Maintainer : Albert Krewinkel Tests for calling exposed Haskell functions. -} diff --git a/test/HsLua/PackagingTests.hs b/test/HsLua/PackagingTests.hs --- a/test/HsLua/PackagingTests.hs +++ b/test/HsLua/PackagingTests.hs @@ -1,8 +1,8 @@ {-| Module : HsLua.PackagingTests -Copyright : © 2020-2022 Albert Krewinkel +Copyright : © 2020-2023 Albert Krewinkel License : MIT -Maintainer : Albert Krewinkel +Maintainer : Albert Krewinkel Test packaging -} diff --git a/test/test-hslua-packaging.hs b/test/test-hslua-packaging.hs --- a/test/test-hslua-packaging.hs +++ b/test/test-hslua-packaging.hs @@ -1,8 +1,8 @@ {-| Module : Main -Copyright : © 2020-2022 Albert Krewinkel +Copyright : © 2020-2023 Albert Krewinkel License : MIT -Maintainer : Albert Krewinkel +Maintainer : Albert Krewinkel Tests for hslua-packaging. -}