C bindings to PGF interpreter

contrib/c-bindings/readme-ffi.txt

@@ -0,0 +1,121 @@
+GF C Bindings
+Copyright (C) 2008-2009 Kevin Kofler
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, see <http://www.gnu.org/licenses/>.
+
+
+This library provides access to the GF embedded grammars (PGF) API to C/C++
+applications. To use it:
+1. #include "pgf.h"
+2. call gf_init(&argc, &argv); at the beginning of main()
+3. call gf_exit(); before exiting the program
+4. build with: ghc --make -fglasgow-exts -O2 -no-hs-main $* x.c PGFFFI.hs -o x
+
+
+Currently, the following functions from PGF are wrapped:
+readPGF  :: FilePath -> IO PGF
+showLanguage :: Language -> String
+readLanguage :: String -> Maybe Language
+languages    :: PGF -> [Language]
+abstractName :: PGF -> Language
+languageCode :: PGF -> Language -> Maybe String
+showType :: Type -> String
+readType :: String -> Maybe Type
+categories :: PGF -> [Type]
+startCat   :: PGF -> Type
+mkCId :: String -> CId
+prCId :: CId -> String
+wildCId :: CId
+showTree :: Tree -> String
+readTree :: String -> Maybe Tree
+showExpr :: Expr -> String
+readExpr :: String -> Maybe Expr
+linearize    :: PGF -> Language -> Tree -> String
+showPrintName :: PGF -> Language -> Type -> String
+parse        :: PGF -> Language -> Type -> String -> [Tree]
+canParse     :: PGF -> Language -> Bool
+
+
+Some notes about the wrapping:
+* "gf_" is prepended to the wrapped functions as a form of namespacing.
+* Object types T are mapped to opaque C types GF_T which are handles to the
+  object. Whenever returned by a function, they get marked as used (so the
+  Haskell garbage collection won't delete them), so when you are done using
+  them, you should free them (assuming they're non-NULL) with the corresponding
+  gf_freeT function (i.e. one of: gf_freePGF, gf_freeLanguage, gf_freeType,
+  gf_freeCId, gf_freeTree, gf_freeExpr). (Internally, they are all Haskell
+  StablePtr handles, but this is subject to change.)
+* Strings are mapped to char *. Strings returned by functions, when not NULL,
+  are allocated with malloc and should thus be freed with free when no longer
+  needed.
+* A FilePath is a string.
+* A type Maybe T is mapped the same way as just T, except that the returned
+  handle or char * can be NULL, so you should test them with a test like if (p).
+  Otherwise functions can be expected to always return non-NULL
+  handles/pointers. Conversely, arguments to functions are always assumed to be
+  non-NULL.
+* Lists [T] are mapped to null-terminated arrays GF_T[], passed/returned as
+  pointers GF_T *. All objects in the array should be freed with the correct
+  gf_freeT function when no longer needed, the array itself with free. For your
+  convenience, the C header defines inline functions gf_freeLanguages,
+  gf_freeTypes and gf_freeTrees which free an entire array.
+* Bool is wrapped to int using the usual C convention of 1 = True, 0 = False.
+* A constant like wildCId is mapped to a function with no arguments, e.g.
+  GF_CId wildCId(void). The returned handle has to be freed as for any other
+  function.
+
+
+Thus, the C prototypes for the wrapped functions are:
+GF_PGF *gf_readPGF(char *path);
+char *gf_showLanguage(GF_Language lang);
+GF_Language gf_readLanguage(char *str); /* may return NULL */
+GF_Language *gf_languages(GF_PGF pgf);
+GF_Language gf_abstractName(GF_PGF pgf);
+char *gf_languageCode(GF_PGF pgf, GF_Language lang); /* may return NULL */
+char *gf_showType(GF_Type tp);
+GF_Type gf_readType(char *str); /* may return NULL */
+GF_Type *gf_categories(GF_PGF pgf);
+GF_Type gf_startCat(GF_PGF pgf);
+GF_CId gf_mkCId(char *str);
+char *gf_prCId(GF_CID cid);
+GF_CId wildCId(void);
+char *gf_showTree(GF_Tree tree);
+GF_Tree gf_readTree(char *str); /* may return NULL */
+char *gf_showExpr(GF_Expr expr);
+GF_Expr gf_readExpr(char *str); /* may return NULL */
+char *gf_linearize(GF_PGF pgf, GF_Language lang, GF_Tree tree);
+char *gf_showPrintName(GF_PGF pgf, GF_Language lang, GF_Type tp);
+GF_Tree *gf_parse(GF_PGF pgf, GF_Language lang, GF_Type cat, char *input);
+int gf_canParse(GF_PGF pgf, GF_Language lang); /* returns 0 or 1 */
+
+The C prototypes for the freeing functions are:
+void gf_freePGF(GF_PGF pgf);
+void gf_freeLanguage(GF_Language lang);
+void gf_freeType(GF_Type tp);
+void gf_freeCId(GF_CId cid);
+void gf_freeTree(GF_Tree tree);
+void gf_freeExpr(GF_Expr expr);
+void gf_freeLanguages(GF_Language *p);
+void gf_freeTypes(GF_Type *p);
+void gf_freeTrees(GF_Tree *p);
+
+
+
+In addition, the following function from GF.Text.Lexing:
+stringOp :: String -> Maybe (String -> String)
+is wrapped as:
+char *gf_stringOp(char *op, char *str)
+which returns NULL if op is not a valid operation name, otherwise applies the
+function corresponding to op to the string str. The resulting string must be
+freed with free if non-NULL.