
This is a preview release of libpgf, a native-code library for parsing
and linearization of the PGF grammars produced by the Grammatical 
Framework <http://www.grammaticalframework.org/>.

This release is not yet ready for production use: essential
functionality is still missing, the API is still likely to change, and
the documentation is incomplete. This release is primarily meant for
developers who are interested in using libpgf, and who wish to
contribute to its design. An essential feature which distinguishes
libpgf from the reference Haskell implementation is that
the parser is able to use statistical disambiguation models
while parsing and that it can be robust for ungrammatical sentences.


PREREQUISITES
-------------

This is a self-contained library: only a C99-conformant C compiler is
needed. The code is mostly portable C, although it makes some very
general assumptions about the architecture (mostly regarding the
representation of addresses) that should hold on modern systems. Still,
the code has only been tested on Linux-x86(-64) so far. Reports of
porting problems on other platforms are appreciated.

Although the code "only" requires C99-conformance, it seems that many
compilers fail at it subtly. In particular:

- Clang does not currently support "extern inline" properly.

- Sun C 5.9 apparently has a bug in its treatment of sizeof on compound
  array literals.

As a consequence, these compilers cannot be used in the current state of
the code. Modern versions of GCC, on the other hand, seem to work fine.


INSTALLING
----------

This is a standard GNU Autotools package. Read the attached INSTALL file
for generic installation instructions. There are currently no
interesting special configuration options.

Pkg-config configuration files for the library are also provided.

STATUS
------

Currently only very basic PGF functionality is supported. The focus
is on the experimental statistical parser and many other features
which are not essential in this aspect are still missing:

- higher-order abstract syntax variables
- type checking and inference
- dependent types
- generation of random syntax trees
- linearization of incomplete trees

Most of these will eventually get added.


PROGRAMS
--------

There are two small programs included. These are mainly for testing
purposes and for demonstrating how to use the library.

The pgf2yaml program simply reads a PGF file from the standard input and
dumps it to the standard output in YAML <http://yaml.org/> format.

The pgf-print program reads a PGF file from the standard input and
dumps it to the standard output in the same format that the Haskell
implementation provides when the option -output-format=pgf_pretty
is passed to the compiler.

The pgf-translate program translates sentences of one language in a PGF
grammar into another. It is invoked:

pgf-translate PGF CAT FROM_LANG TO_LANG

Where PGF is a PGF file, CAT is the name of the category whose sentences
are to be translated, and FROM_LANG and TO_LANG are names of concrete
grammars within the PGF file.

The program prompts for a line containing a full sentence of the
specified category in the source language, and displays the 
best syntax tree according to the statistical model.
If linearization in the target language is possible then 
it is displayed. If you want the next best tree then
just press enter again without typing anything else in the command line.


LIBGU
-----

Along with libpgf proper, this distribution includes libgu, a
general-purpose utility library that libpgf is based on. Libgu is usable
independently of libpgf, and may eventually be split into a separate
package. Do give it a try if you are looking for a library to make C
programming less painful.


DOCUMENTATION
-------------

Documentation is still fragmentary, but some of the most important
headers have documentation comments. If you have Doxygen
<http://doxygen.org/> installed, "make doxygen-doc" will generate HTML
documentation for the library.

The sources in utils/pgf-translate.c have some comments which may also
clarify how to use the library.


FEEDBACK
--------

Please report bugs to the Grammatical Framework bug tracker
<https://code.google.com/p/grammatical-framework/issues/>.

For general questions, comments and suggestions on libpgf, write to the
GF mailing list at <mailto:gf-dev@googlegroups.com> or
<https://groups.google.com/group/gf-dev>.

For questions and comments that are related to the core libgu library,
but not to PGF, please write directly to the authors at
<mailto:lealanko@ling.helsinki.fi> or <mailto:krasimir@chalmers.se>.
