.. _jsgf_parser:

JSGF Parser
===========

| This JavaSpeechGrammarFormat-parser can generate grammar-trees.
| It is used by the :ref:`speech_recognition_tool` and can also operate alone.
| It also contains an annotation library from the Stanford CoreNLP toolkit in development.

Related resources
-----------------

Related projects:
 - `JSGF at w3.org <https://www.w3.org/TR/jsgf/>`_
 - :ref:`speech_recognition_tool`
 - `Sphinx4 at sourceforge <http://cmusphinx.sourceforge.net/>`_
 - `Sphinx4 at github <https://github.com/cmusphinx/>`_
 - `Stanford CoreNLP <https://stanfordnlp.github.io/CoreNLP/>`_


Component repository: 
 - Browse component repository: `jsgf-parser <https://projects.cit-ec.uni-bielefeld.de/projects/agaispeechprocessing/repository/jsgf-parser/>`_.
 - ``git clone http://projects.cit-ec.uni-bielefeld.de/git/agaispeechprocessing.git.jsgf-parser.git``


System startup:

The start script jsgfparser.sh can be found at ``/vol/csra//releases/trusty/lsp-csra-nightly/opt/jsgfparser/bin/jsgfparser``.

The program can be invoked with the following parameters:

 -i <STRING[]>, --hypotheses <STRING[]>  Input-Hypotheses. Multiple hypotheses separated by semicolon. e.g.:'hypothesis;another hypothesis'.

 -o <ABSOLUTE_FILE_PATH>, --output <ABSOLUTE_FILE_PATH>  File for result-output.

 -g <ABSOLUTE_FILE_PATH>, --grammar <ABSOLUTE_FILE_PATH>  JSGF-grammar to build trees from.

 -n <BOOLEAN>, --incremental <BOOLEAN>  Boolean if the given input-hypotheses may contain incremental units.


Interfaces
-----------

Input/Output: 

It can parse a result generated from a grammar against this grammar to show its tree.
For incremental units all possible trees are generated.
The Parser is case-sensitive!
Output format is xml.

Example:
 
<GREETING> HELLO <ROBOT> FLOBI </ROBOT> </GREETING>


Examples
----------

Example 1:

You have a hypothesis that was generated from a jsgf-grammar and want to see its grammartree.
For this task you can use the jsgf-parser quite simple.
Start the script with the properties for the hypotheses and the used grammar-file.

So you have ``./jsgfparser -g /somedirectory/jsgfgrammar.gram/ -i 'this is a hypothesis'``.

This will print the grammar tree to terminal.

Example 2:

If you want to store it in a file, just add it like following:

``./jsgfparser -g /somedirectory/jsgfgrammar.gram/ -i 'this is a hypothesis' -o /whereYouWantYourOutputFile.txt``.

Example 3:

You may have incremental hypothesis you want to get a tree for.
For this case, flag your input as incremental and the parser will produce trees that could fit the hypotheses.

``./jsgfparser -g /somedirectory/jsgfgrammar.gram/ -i 'this is a' -n true``.