gf-core

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.


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, enough to
translate sentences of the Phrasebook grammar in the GF distribution.
Among missing features are:

- querying a parser for tokens expected next
- literals and custom categories
- higher-order abstract syntax variables
- type checking and inference
- generation of random syntax 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-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 syntax trees
and destination language linearizations of all possible parses of that
sentence.


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 author at
<mailto:lealanko@ling.helsinki.fi>.