-- | A Haskell interface to /Mathematica/'s /MathLink/.
module Foreign.MathLink ( 
-- * Basic usage

{- | The following is a small Haskell module that exposes a function 
callable from /Mathematica/ that gets a pair of 'Int's (as a tuple) and 
returns their sum to /Mathematica/:

@
module Main where
 
import 'Foreign.MathLink'
 
addTwo :: 'ML' ()
addTwo = do
  (i1,i2) <- 'get'
  'put' ((i1 + i2) :: 'Int')

main = 'runMathLink' [ 'Function' \{ 'callPattern' = \"AddTwo[i_Integer,j_Integer]\"
                              , 'argumentPattern' = \"{i,j}\"
                              , 'function' = addTwo
                              \}
                   ]
@

A function to be exposed to /Mathematica/ has type @'ML' ()@. In its body it uses
the 'get' method to receive a value from /Mathematica/, performs the desired
computation, and sends the result back to /Mathematica/ via the 'put' function.

The types that can be marshaled to\/from /Mathematica/ are instances of the
'Expressible' class.

See the @examples@ directory of the source distribution for more.
-}

 -- * Known limitations

 -- ** No out-of-band messaging

 {- | So, /e.g./, you cannot abort a calculation. An initial 
implementation of this was working, but not always reliably, so it was 
removed, to be added back in a coming revision, hopefully.
-}

-- ** @'Expressible' 'String'@ needs rewrite rules

{- | On Haskell systems without rewrite rules (or when they are not
used, as, /e.g./, is the case by default in GHC), the 'Expressible' 
instance for 'String' is broken. To make sure that the rules always fire
with GHC, you can, for instance, include the @OPTIONS_GHC -O@ pragma at
the top of your source file. Without using the rewrite rules, two simple 
workarounds exist. Firstly, if you only need to marshal a single string, 
you can use the 'getString' and 'putString' functions. More generally, 
you can marshal the string as a value of type 'Expression' by wrapping 
it in the 'ExString' constructor.
-}

-- ** Untested across platforms

{- | The author developed the library on a 64-bit Linux platform with 
GHC 6.10.1 and /Mathematica/ 7. However, among the author's design goals 
is that the library be useful for:

 (1) any Haskell system with modest language extensions beyond the 
     98 standard and implementing the FFI addendum;

 (2) any version of /Mathematica/ supporting version 3 of the
     /MathLink/ interface;

 (3) any 32-bit or 64-bit OS.

Please report any failures in this regard, (or, better yet, send a patch!) 
and the author will make an effort (time, patience, and resources 
permitting) to bring the library closer to its stated goal, or at least 
to explicitly document the limitation in a future release.
-}

   module Foreign.MathLink.Types
 , module Foreign.MathLink.ML
 , module Foreign.MathLink.Expressible

 ) where

import Foreign.MathLink.Types
import Foreign.MathLink.ML
import Foreign.MathLink.Expressible