bindings-0.0.1: Low level bindings for foreign libraries following community driven guidelinesSource codeContentsIndex
Bindings
Description

Modules under Bindings are supposed to be low level links to non-Haskell packages, sharing a set of community driven guidelines on procedures, goals and style. (Note that, until others get interested in this work, "community" means just the author.) This is the current set of guidelines:

  • Code should be portable and easy to build.
  • There should be a one-to-one relashionship between names in the original library and its bindings. Also, the behavior of elements should be what would be expected from the element of the original library it represents.
  • As a planed consequence of the former item, the reference documentation for all modules should be the documentation available for the original libraries. Documentation and comments to Haskell binding code should be restricted to explain decisions that had to be made to solve ambiguities or provide functionality that could not be mapped to an exact Haskell equivalent.
  • All foreign functions are declared safe. Also, they should all result in a System.IO.IO, even when they are supposed to be effect-free. This is both for consistency and security, since otherwise it would be difficult to inspect all the code to check which functions are actually guaranteed to be effect-free. Constant values, however, may be represented by pure functions.
  • Global variables whose values can be changed by a library user are wrapped throw type Bindings.Utilities.GlobalVar. When their values can't be changed by the user, but still they can change as the execution goes, they are wrapped throw functions returning an System.IO.IO. (This last case, of course, may need helper functions written in the foreign language.)
  • Names in Haskell should match the corresponding names in original libraries, prefixed with '_' when starting with an uppercase letter, or with first letter uppercased when naming types. Exception is made to prefixes used to emulate namespaces. In this case, prefixes are stripped, and they are expected to be replaced by qualified imports, e.g., a function named somepkg_anyfun should be named just anyfun and may be used as SomePkg.anyfun. Also names for basic types, like fixed size integers or pointers, should be consistent with style used in Foreign.C.Types.
  • Module Bindings.Utilities has an enumeration of function types (Bindings.Utilities.CB0001, Bindings.Utilities.CB0002 etc.) which are supposed to be used (and incremented when necessary) to type callback functions. Foreign functions parameters expecting callback pointers should be typed as pointers to function types in that enumeration; except when those callbacks are just data destructors, when they should be typed as Foreign.ForeignPtr.FinalizerPtr.
  • Users can suggest tests using Test.HUnit or Test.QuickCheck using the bug tracking system. Test shown to be valid will be included with a test program included in this package.

The names for files and directories in the source pack follow the usual convention of mapping module names to file names. A similar convention is followed by C files that support those modules. There are also a few special directories:

packageCode
This directory contains the source code for the foreign libraries. Whe appropriate, steps necessary to build a library will be listed in a file here.
packageCode/include
Support files needed by this package to properly wrapp libraries (like C include files) are placed here. They should be simplified as much as possible to contain only the required information.
traduttoreTraditore
Here example code for wrapped libraries can be found. However, only Haskell translations for code already available for those libraries in "official" places (like the homepage for the library, or inside its source code distribution) are allowed. Best effort should be made to keep those translations faithfull to the original code, so that readers could follow then side by side.
Synopsis
data License
= ApacheLicenseV2
| BSD3
| GPL
| GPLv3
| LGPL
| LGPLv3
| MIT
| MPL
| CDDL
| CPL
| EPL
| ArtisticLicenseV2
| OSLv3
| Zlib
| AfferoGNUv3
| SimPLv2
| Proprietary
| Private
data Package = Sqlite3
whatCanBeUsedWithThisLicense :: License -> [Package]
initialize :: [Package] -> IO ()
bindings_init_sqlite3 :: IO CInt
bindings_shutdown :: IO ()
Documentation
data License Source
Constructors
ApacheLicenseV2
BSD3
GPL
GPLv3
LGPL
LGPLv3
MIT
MPL
CDDL
CPL
EPL
ArtisticLicenseV2
OSLv3
Zlib
AfferoGNUv3
SimPLv2
Proprietary
Private
data Package Source
Constructors
Sqlite3
show/hide Instances
whatCanBeUsedWithThisLicense :: License -> [Package]Source
Given the license you have choosen for your work, this function tells you which libraries in this package you're allowed to use.
initialize :: [Package] -> IO ()Source
When libraries require an initialization call to be made at startup, the related functions are not wrapped. Instead, we use initialize as a common initialization point for all libraries. You can use initialize at the beginning of main and shutdown at the end. Repeated calls to initialize cause no harm.
bindings_init_sqlite3 :: IO CIntSource
bindings_shutdown :: IO ()Source
Produced by Haddock version 2.4.2