hoppy-docs 0.5.0 → 0.6.0

raw patch · 3 files changed

+76/−80 lines, 3 filesdep ~hoppy-generatordep ~hoppy-runtimesetup-changedPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: hoppy-generator, hoppy-runtime

API changes (from Hackage documentation)

Files

• Setup.hs +1/−1
• hoppy-docs.cabal +4/−4
• src/Foreign/Hoppy/Documentation/UsersGuide.hs +71/−75

@@ -1,6 +1,6 @@ -- This file is part of Hoppy. ----- Copyright 2015-2018 Bryan Gardiner <bog@khumba.net>+-- Copyright 2015-2019 Bryan Gardiner <bog@khumba.net> -- -- This program is free software: you can redistribute it and/or modify -- it under the terms of the GNU Affero General Public License as published by

@@ -1,12 +1,12 @@ name: hoppy-docs-version: 0.5.0+version: 0.6.0 synopsis: C++ FFI generator - Documentation homepage: http://khumba.net/projects/hoppy license: AGPL-3 license-file: LICENSE author: Bryan Gardiner <bog@khumba.net> maintainer: Bryan Gardiner <bog@khumba.net>-copyright: Copyright 2015-2018 Bryan Gardiner+copyright: Copyright 2015-2019 Bryan Gardiner category: Foreign build-type: Simple cabal-version: >=1.10@@ -21,8 +21,8 @@   build-depends:       base >=4.7 && <5     , haskell-src >=1.0 && <1.1-    , hoppy-generator >=0.5 && <0.6-    , hoppy-runtime >=0.5 && <0.6+    , hoppy-generator >=0.6 && <0.7+    , hoppy-runtime >=0.6 && <0.7   hs-source-dirs: src   ghc-options: -W -fwarn-incomplete-patterns -fwarn-unused-do-bind   default-language: Haskell2010

@@ -1,6 +1,6 @@ -- This file is part of Hoppy. ----- Copyright 2015-2018 Bryan Gardiner <bog@khumba.net>+-- Copyright 2015-2019 Bryan Gardiner <bog@khumba.net> -- -- This program is free software: you can redistribute it and/or modify -- it under the terms of the GNU Affero General Public License as published by@@ -85,9 +85,6 @@   -- **** Enum exports   -- $generators-hs-module-structure-enums -  -- **** Bitspace exports-  -- $generators-hs-module-structure-bitspaces-   -- **** Function exports   -- $generators-hs-module-structure-functions @@ -108,7 +105,7 @@   ) where  import Data.Bits (Bits)-import Foreign.C (CInt, peekCString, withCString)+import Foreign.C (CBool, CDouble, CFloat, CInt, peekCString, withCString) import Foreign.Hoppy.Generator.Language.Haskell import Foreign.Hoppy.Generator.Main import Foreign.Hoppy.Generator.Spec@@ -126,8 +123,8 @@ {- $overview  Hoppy is a foreign function interface (FFI) generator for interfacing Haskell-with C++.  It lets developers specify C++ interfaces in pure Haskell, and-generates code to expose that functionality to Haskell.  Hoppy is made up of a+with C++.  With Hoppy, you can specify C++ interfaces in pure Haskell, and+generate code to expose that functionality to Haskell.  Hoppy is made up of a few different packages that provide interface definition data structures and code generators, some runtime support for Haskell bindings, and interface definitions for the C++ standard library.@@ -137,16 +134,16 @@ - A Haskell generator program (in @\/myproject-generator@) that knows the interface definition and generates code for the next two parts. -- A C++ library (in @\/myproject-cpp@) that gets compiled into a shared object containing-the C++ half of the bindings.+- A C++ library (in @\/myproject-cpp@) that gets compiled into a shared object+containing the C++ half of the bindings.  - A Haskell library (in @\/myproject@) that links against the C++ library and exposes the bindings.  The path names are suggested subdirectories of a project, and are used in this-document, but are not required.  Only the latter two items need to be packaged-and distributed to users of the binding (plus Hoppy itself which is a dependency-of the generated bindings).+document, but are not required.  Despite the second being called a C++ library+and containing C++ code, all three of these are Haskell packages, built using+Cabal.  -} {- $getting-started@@ -156,21 +153,29 @@ -} {- $getting-started-project-setup -To set up a new Hoppy project, it's recommended to start with the project in the-@example\/@ directory as a base.  It is a minimal project that defines a C++-function to reverse a @std::string@, exposes that to Haskell via a library, and-provides a demo program that uses the library.  The @example\/install.sh@ script-simply compiles and installs the generator, C++, and Haskell packages in turn.+To set up a new Hoppy project, it's recommended to start with the template+project in the @example\/@ directory.  You can find this in the Hoppy source+repository: +<https://gitlab.com/khumba/hoppy/tree/master/example>++This is a minimal project that defines a C++ function to reverse a @std::string@,+exposes that to Haskell via a library, and provides a demo program that uses the+library.  The @example\/install.sh@ script simply compiles and installs the+generator, C++, and Haskell packages in turn.+ The generator package specifies the C++ interface to be exposed, using the functions and data types described in the rest of this section. -The C++ package is a mostly empty, primarily containing a @Setup.hs@ file that-invokes Hoppy build hooks, and the C++ code we're binding to.  When building-this package, Hoppy generates some C++ code and then relies on a Makefile we-provide for linking it together with any code we provided (see-@example\/example-cpp\/cpp\/Makefile@).  If you are relying on a system library,-you can link to it in the Makefile.+The C++ package is mostly empty, primarily containing a @Setup.hs@ file that+invokes Hoppy build hooks, and any C++ code of our own that we want to bind to,+beyond what's provided by third-party libraries.  For this example, we add a+@reverse()@ function and make use of the C++ standard library.  If we were+writing a binding for an existing third-party library, we might not need to+provide any C++ code ourselves here.  When building this package, Hoppy+generates some C++ code and then relies on a Makefile we provide for linking it+together with any code we provided (see @example\/example-cpp\/Makefile@).  If+you are relying on a system library, you can link to it in the Makefile.  The Haskell package is even more empty than the C++ one.  It contains a similar @Setup.hs@ to invoke Hoppy.  Nothing else is included in the package's library,@@ -316,7 +321,6 @@ - @f_@ for functions ('Function'). - @c_@ for classes ('Class'). - @e_@ for enums ('CppEnum').-- @bs_@ for bitspaces ('Bitspace'). - @cb_@ for callbacks ('Callback'). - @mod_@ for modules ('Module'). @@ -362,7 +366,7 @@ between C++ and Haskell, because these types are the common denominator between C++ and Haskell.  When passing values back and forth between C++ and Haskell, generally, primitive types are converted to equivalent types on both ends, and-pointer types in C++ are represented by corresponding pointer types in Haskell.+pointer types in C++ are represented by corresponding handle types in Haskell. Other types have special rules.  Conversion code is generated on both sides of the gateway to perform the necessary conversions. @@ -378,17 +382,23 @@ - 'voidT': C++ uses @void@.  The C type is unspecified.  Haskell uses @()@.  - 'boolT', 'intT', 'floatT', 'doubleT': C++ and C use @bool@, @int@, @float@,-@double@.  Haskell uses 'Bool', 'Int', 'Float', 'Double'.+@double@.  Haskell uses 'Bool', 'Int', 'Float', 'Double'.  The common Haskell+types are used here for convenience, but note that their sizes may differ from+the C++ types.  Coersion here performs bounds checking and will throw an+exception if a value cannot be converted properly. +- 'boolT'', 'intT'', 'floatT'', 'doubleT'': C++ and C use @bool@, @int@,+@float@, @double@ as above.  Haskell uses 'CBool', 'CInt', 'CFloat', 'CDouble'.+In comparison to the above, the Haskell types here are identical to the C/C+++types, so no type conversion is performed, but fewer Haskell functions take+these types as arguments, so they may be more awkward to use.+ - 'charT', 'ucharT', and other primitive numeric types: Identical C++ and C types; Haskell uses built-in foreign data types.  See "Foreign.Hoppy.Generator.Types" for more info. -- 'enumT': C++ uses the enum type.  C uses @int@.  Haskell uses a generated data-type for the enum.--- 'bitspaceT': C++ and C use a specified type, usually @int@.  Haskell uses a-generated data type for the bitspace.+- 'enumT': C++ uses the enum type.  C uses the numeric type underlying the enum;+see 'enumNumericType'.  Haskell uses a generated data type for the enum.  - 'ptrT': C++ and C use the raw pointer type.  The Haskell type depends on the pointed-to type.  If it's an object pointer, then Haskell uses the generated@@ -399,7 +409,8 @@ - 'refT': C++ uses the reference type.  Everything else is the same as 'ptrT'.  - 'fnT': Function types aren't useful raw, and need to be wrapped in 'ptrT' to-be useable in parameter and return types.+be useable in parameter and return types.  To specifying additional information+about parameters, use 'fnT''.  - 'callbackT': C++ uses the callback's generated functor class.  C uses an internal implementation pointer.  Haskell uses a function in @IO@ of the Haskell@@ -416,7 +427,10 @@ - 'constT': Wraps types in @const@.  Many of these types (enumerations, object types, functions, callbacks) are-discussed in later sections.+discussed in later sections.  The above list is incomplete and only mentions the+most commonly used types.  See "Foreign.Hoppy.Generator.Types" for more.  You+can also construct your own numeric types with 'makeNumericType', and more+generally with 'ConversionSpec'.  -} {- $getting-started-wrapping-up-the-string-binding@@ -684,9 +698,9 @@ for more info.  If you want to pass an object to the collector immediately upon creation, chain-its constructor call with @('toGc' '=<<')@.  This is not done by default because-we don't support revoking the collector's watch over an object, and there are-times when you want to work with manually managed objects.+its constructor call with @('toGc' '=<<')@.  Hoppy does not do this by default+because we don't support revoking the collector's watch over an object, and+there are times when you want to work with manually managed objects.  'toGcT' may be used when defining a function to make an object being passed into Haskell be managed by the garbage collector explicitly.  But rather than using@@ -1058,6 +1072,18 @@ @ alignment :: 'CppEnum' alignment =+  'makeAutoEnum' ('ident' \"Alignment\") Nothing False+  [ "LeftAlign"+  , "CenterAlign"+  , "RightAlign"+  ]+@++or declared with manual enum values specified:++@+alignment :: 'CppEnum'+alignment =   'makeEnum' ('ident' \"Alignment\") Nothing   [ (0, [\"left\", \"align\"])   , (1, [\"center\", \"align\"])@@ -1072,49 +1098,19 @@     Alignment_LeftAlign   | Alignment_CenterAlign   | Alignment_RightAlign-@--with instances for 'Bounded', 'Enum', 'Eq', 'Ord', and 'Show'.---}-{- $generators-hs-module-structure-bitspaces--'Bitspace's, unlike enums, materialize in Haskell using a single data-constructor and bindings for values, rather than multiple data constructors.  A-bitspace declaration such as--@-formatFlags :: 'Bitspace'-formatFlags =-  'makeBitspace' ('toExtName' \"Format\") 'intT'-  [ (1, [\"format\", \"letter\"])-  , (2, [\"format\", \"jpeg\"])-  , (4, [\"format\", \"c\"])-  ]+  | Alignment_Unknown Int @ -will generate the following:--@-newtype Format--instance 'Bits' Format-instance 'Bounded' Format-instance 'Eq' Format-instance 'Ord' Format-instance 'Show' Format--fromFormat :: Format -> 'CInt'--class IsFormat a where-  toFormat :: a -> Format+with instances for a Hoppy 'Foreign.Hoppy.Runtime.CppEnum' typeclass, in+addition to the standard 'Eq', 'Ord', and 'Show' typeclasses. -instance IsFormat 'CInt'+A 'Bits' instance is also generated by default.  This can be disabled with+'enumSetHasBitOperations'. -format_FormatLetter :: Format-format_FormatJpeg :: Format-format_FormatC :: Format-@+The \"Unknown\" entry is used to represent enum values that weren't declared in+the Hoppy interface, e.g. when a value is passed from C++ to Haskell.  This+entry's name can be changed with 'enumSetUnknownValueEntry', or disabled with+'enumSetNoUnknownValueEntry'.  -} {- $generators-hs-module-structure-functions