GF Logo

GF Web Service API

June 2016



Introduction

The PGF API is available as Web Service through the built-in HTTP server in the main GF executable. It is activated by starting GF with the -server flag:

  $ gf -server
  This is GF version 3.8.
  Document root = /usr/share/gf-3.8/www
  Starting HTTP server, open http://localhost:41296/ in your web browser.

A compiled GF grammar (a .pgf file) can be used in web applications by placing it somewhere under the document root. When there is a request for access to a .pgf file, the GF web server will load and cache the grammar and interpret any parameters included in the URL (in the url-encoded-query format). The response you get back is usually a data structure in JSON format, but it could also be an image or plain text.

For example, if my_grammar.pgf is a grammar placed directly under the document root, then the grammar could be accessed using this URL:

  http://localhost:41296/my_grammar.pgf

The default when no parameters are included in the URL is a response with some general information about the grammar, encoded in JSON format. To perform specific command you have to tell what command you want to perform. The command is encoded in the parameter command, i.e.:

http://localhost/my_grammar.pgf?command=cmd

where cmd is the name of the command. Most commands require additional arguments, which are encoded as parameters as well. The supported commands and their arguments are described below.

Commands


Grammar

This command provides some general information about the grammar. This command is also executed if no `command` parameter is given.

Input
Parameter Description Default
command should be grammar -
Output

A JSON object including the following fields:

Field Description
name the name of the abstract syntax in the grammar
userLanguage the concrete language in the grammar which best matches the default language set in the user's browser
categories list of all abstract syntax categories defined in the grammar
functions list of all abstract syntax functions defined in the grammar
languages list of concrete languages available in the grammar

Every language is described with object having this two fields:

Field Description
name the name of the concrete syntax for the language
languageCode the two-character language code according to the ISO standard i.e. en for English, bg for Bulgarian, etc.

The language codes need to be specified in the grammar with flags language=.... The web service receives the code of the language set in the browser and compares it with the codes defined in the grammar. If there is a match then the service returns the corresponding concrete syntax name. If no match is found then the first language in alphabetical order is returned.


Parsing

This command parses a string and returns a list of abstract syntax trees.

Input

Parameter Description Default
command should be parse -
cat the start category for the parser the default start category for the grammar
input the string to be parsed empty string
from the name of the concrete syntax to use for parsing all languages in the grammar will be tried
limit limit how many trees are returned (gf>3.3.3) no limit is applied

Output

List of objects where every object represents the analyzes for every input language. The objects have three fields:

Field Description
from the concrete language used in the parsing
brackets the bracketed string from the parser
trees list of abstract syntax trees
typeErrors list of errors from the type checker

The abstract syntax trees are sent as plain strings. The type errors are objects with two fields:

Field Description
fid forest id which points to a bracket in the bracketed string where the error occurs
msg the text message for the error

The current implementation either returns a list of abstract syntax trees or a list of type errors. By checking whether the field trees is not null we check whether the type checking was successful.


Linearization

The command takes an abstract syntax tree and produces string in the specified language(s).

Input

Parameter Description Default
command should be linearize -
tree the abstract syntax tree to linearize -
to the name of the concrete syntax to use in the linearization linearizations for all languages in the grammar will be generated

Output

Field Description
to the concrete language used for the linearization
tree the output text

Translation

The translation is a two step process. First the input sentence is parsed with the source language and after that the output sentence(s) are produced via linearization with the target language(s). For that reason the input and the output for this command is the union of the input/output of the commands for parsing and the one for linearization.

Input

Parameter Description Default
command should be translate -
cat the start category for the parser the default start category for the grammar
input the input string to be translated empty string
from the source language all languages in the grammar will be tried
to the target language linearizations for all languages in the grammar will be generated
limit limit how many parse trees are used (gf>3.3.3) no limit is applied

Output

The output is a list of objects with these fields:

Field Description
from the concrete language used in the parsing
brackets the bracketed string from the parser
translations list of translations
typeErrors list of errors from the type checker

Every translation is an object with two fields:

tree abstract syntax tree
linearizations list of linearizations

Every linearization is an object with two fields:

Field Description
to the concrete language used in the linearization
text the sentence produced

The type errors are objects with two fields:

Field Description
fid forest id which points to a bracket in the bracketed string where the error occurs
msg the text message for the error

The current implementation either returns a list of translations or a list of type errors. By checking whether the field translations is not null we check whether the type checking was successful.


Random Generation

This command generates random abstract syntax tree where the top-level function will be of the specified category. The categories for the sub-trees will be determined by the type signatures of the parent function.

Input

Parameter Description Default
command should be random -
cat the start category for the generator the default start category for the grammar
limit maximal number of trees generated 1

Output

The output is a list of objects with only one field:

Field Description
tree the generated abstract syntax tree

The length of the list is limited by the limit parameter.


Word Completion

Word completion is a special case of parsing. If there is an incomplete sentence then it is first parsed and after that the state of the parse chart is used to predict the set of words that could follow in a grammatically correct sentence.

Input

Parameter Description Default
command should be complete -
cat the start category for the parser the default start category for the grammar
input the string to the left of the cursor that is already typed empty string
from the name of the concrete syntax to use for parsing all languages in the grammar will be tried
limit maximal number of trees generated all words will be returned

Output

The output is a list of objects with two fields which describe the completions.

Field Description
from the concrete syntax for this word
text the word itself

Abstract Syntax Tree Visualization

This command renders an abstract syntax tree into an image. Several image formats are supported.

Input

Parameter Description Default
command should be abstrtree -
tree the abstract syntax tree to render -
format output format (gf>3.3.3) png

Output

By default, the output is an image in PNG format. The Content-Type is set to image/png, so the easiest way to visualize the generated image is to add HTML element <img/> which points to URL for the visualization command i.e.:

  <img src="http://localhost/my_grammar.pgf?command=abstrtree&tree=..."/>

The format parameter can also be gif, svg or gv, for GIF (image/gif), SVG (image/svg+xml) or graphviz (text/plain) format, respectively.


Parse Tree Visualization

This command renders the parse tree that corresponds to a specific abstract syntax tree. The generated image is in PNG format.

Input

Parameter Description Default
command should be parsetree -
tree the abstract syntax tree to render -
from the name of the concrete syntax to use in the rendering -
format output format (gf>3.3.3) png
options additional rendering options (gf>3.4) -

The additioal rendering options are: noleaves, nofun and nocat (booleans, false by default); nodefont, leaffont, nodecolor, leafcolor, nodeedgestyle and leafedgestyle (strings, have builtin defaults).

Output

By default, the output is an image in PNG format. The Content-Type is set to image/png, so the easiest way to visualize the generated image is to add HTML element <img/> which points to URL for the visualization command i.e.:

  <img src="http://localhost/my_grammar.pgf?command=parsetree&tree=..."/>

The format parameter can also be gif, svg or gv, for GIF (image/gif), SVG (image/svg+xml) or graphviz (text/plain) format, respectively.


Word Alignment Diagrams

This command renders the word alignment diagram for some sentence and all languages in the grammar. The sentence is generated from a given abstract syntax tree.

Input

Parameter Description Default
command should be alignment -
tree the abstract syntax tree to render -
format output format (gf>3.3.3) png
to list of languages to include in the diagram (gf>3.4) all languages supported by the grammar

Output

By default, the output is an image in PNG format. The Content-Ttype is set to image/png, so the easiest way to visualize the generated image is to add HTML element <img/> which points to URL for the visualization command i.e.:

  <img src="http://localhost/my_grammar.pgf?command=alignment&tree=..."/>

The format parameter can also be gif, svg or gv, for GIF (image/gif), SVG (image/svg+xml) or graphviz (text/plain) format, respectively.


Word Dependency Diagrams

This command (available in GF>=3.8) outputs word dependency diagrams in various format.

Input

Parameter Description Default
command should be deptree -
tree the abstract syntax tree to render -
format output format, see below dot
to name of the concrete syntax to use in the diagram -

The format is one of the following:


Undocumented commands

There a few additional commands that lack proper documentation:

See the source code for details.


Commands that use the C run-time system

GF includes two implementations of the PGF API: the traditional Haskell implementation and the newer C implementation. The commands documented above all use the Haskell implementation. The following commands use the C implementation instead:

They implement the same functionality as the corresponding commands without the c- prefix, although there are some restrictions in what parameters they support, and some differences in the JSON data structures they output.

When using these commands, the grammar will be loaded and cached by the C run-time system. If you use commands from both the Haskell and C implementations with the same grammar, the grammar will be loaded twice.


www.grammaticalframework.org