diff --git a/src/www/gf-web-api.t2t b/src/www/gf-web-api.t2t new file mode 100644 index 000000000..9d895ddae --- /dev/null +++ b/src/www/gf-web-api.t2t @@ -0,0 +1,302 @@ +GF Web Service API +June 2016 + +%!style:cloud.css +%!options(html): --toc +%!options(html): --toc-level=3 +%!postproc(html): <meta charset="UTF-8"><meta name = "viewport" content = "width = device-width"> <TITLE> +%!postproc(html): <H1> <H1><a href="http://www.grammaticalframework.org/"><IMG src="Logos/gf0.png"></a> + +==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) could be used in web applications +%in the same way as JSP, ASP or PHP pages are used. +by placing somewhere under the document root. +%, usually in the ``grammars/`` subdirectory. +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 http://www.json.org/] 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 http://www.loc.gov/standards/iso639-2/php/code_list.php] 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 Diagram=== + +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. + +-------------------------------------------------------------------------------- + +[www.grammaticalframework.org http://www.grammaticalframework.org] diff --git a/src/www/index.html b/src/www/index.html index 3e3ad586a..317af6cf8 100644 --- a/src/www/index.html +++ b/src/www/index.html @@ -31,7 +31,7 @@ <li><a href="gfse/about.html">About the online grammar editor</a> <li><a href="translator/about.html">About the simple translation tool</a> <li><a href="gf-web-api-examples.html">PGF web service API examples</a> - <li><a href="http://code.google.com/p/grammatical-framework/wiki/GFWebServiceAPI">PGF web service API documentation</a> + <li><a href="gf-web-api.html">PGF web service API documentation</a> <li><a href="gf-cloud-api.html">GF Cloud Service API</a> </ul>