diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/runtime-api.html | 175 |
1 files changed, 107 insertions, 68 deletions
diff --git a/doc/runtime-api.html b/doc/runtime-api.html index d8759e01b..100fd4ffb 100644 --- a/doc/runtime-api.html +++ b/doc/runtime-api.html @@ -550,13 +550,114 @@ There are also the methods <tt>UnAbs</tt>, <tt>UnInt</tt>, <tt>UnFloat</tt> and </span> </p> +Constructing new trees is also easy. You can either use +<tt>readExpr</tt> to read trees from strings, or you can +construct new trees from existing pieces. This is possible by +<span class="python"> +using the constructor for <tt>pgf.Expr</tt>: +<pre class="python"> +>>> quant = pgf.readExpr("DetQuant IndefArt NumSg") +>>> e2 = pgf.Expr("DetCN", [quant, e]) +>>> print(e2) +DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN theatre_N)) +</pre> +</span> +<span class="haskell"> +using the functions <tt>mkApp</tt>, <tt>mkStr</tt>, <tt>mkInt</tt>, <tt>mkFloat</tt> and <tt>mkMeta</tt>: +<pre class="haskell"> +Prelude PGF2> let Just quant = readExpr "DetQuant IndefArt NumSg" +Prelude PGF2> let e2 = mkApp "DetCN" [quant, e] +Prelude PGF2> print e2 +DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN theatre_N)) +</pre> +</span> +<span class="java"> +using the constructor for <tt>Expr</tt>: +<pre class="java"> +Expr quant = Expr.readExpr("DetQuant IndefArt NumSg"); +Expr e2 = new Expr("DetCN", new Expr[] {quant, e}); +System.out.println(e2); +</pre> +</span> +<span class="csharp"> +using the constructor for <tt>Expr</tt>: +<pre class="csharp"> +Expr quant = Expr.ReadExpr("DetQuant IndefArt NumSg"); +Expr e2 = new Expr("DetCN", new Expr[] {quant, e}); +Console.WriteLine(e2); +</pre> +</span> + +<h2>Embedded GF Grammars</h2> + +<p>If the host application needs to do a lot of expression manipulations, +then it is helpful to use a higher-level API to the grammar, +also known as "embedded grammars" in GF. The advantage is that +you can construct and analyze expressions in a more compact way.</p> + +<span class="python"> +<p>In Python you first have to <tt>embed</tt> the grammar by calling: +<pre class="python"> +>>> gr.embed("App") +<module 'App' (built-in)> +</pre> +After that whenever you need the API you should import the module: +<pre class="python"> +>>> import App +</pre> +</p> +<p>Now creating new trees is just a matter of calling ordinary Python +functions: +<pre class="python"> +>>> print(App.DetCN(quant,e)) +DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN house_N)) +</pre> +</p> +</span> +<span class="haskell"> +<p>In order to access the API you first need to generate +one boilerplate Haskell module with the compiler: +<pre class="haskell"> +$ gf -make -output-format=haskell App.pgf +</pre> +This module will expose all functions in the abstract syntax +as data type constructors together with methods for conversion from +a generic expression to Haskell data and vice versa. When you need the API you can just import the module: +<pre class="haskell"> +Prelude PGF2> import App +</pre> +</p> +<p>Now creating new trees is just a matter of writing ordinary Haskell +code: +<pre class="haskell"> +Prelude PGF2 App> print (gf (GDetCN (GDetQuant GIndefArt GNumSg) (GAdjCN (GPositA Gred_A) (GUseN Ghouse_N)))) +</pre> +The only difference is that to the name of every abstract syntax function +the compiler adds a capital 'G' in order to guarantee that there are no conflicts +and that all names are valid names for Haskell data constructors. Here <tt>gf</tt> is a function +which converts from the data type representation to generic GF expressions.</p> + +<p>The converse function <tt>fg</tt> converts an expression to a data type expression. +This is useful for instance if you want to do pattern matching +on the structure of the expression: +<pre class="haskell"> +visit = case fg e2 of + GDetCN quant cn -> do putStrLn "Found DetCN" + visit cn + GAdjCN adj cn -> do putStrLn "Found AdjCN" + visit cn + e -> return () +</pre> +</p> +</span> + <span class="python"> <p> -For more complex analyses you can use the visitor pattern. -In object oriented languages this is just a clumpsy way to do +Analysing expressions is also made easier by using the visitor pattern. +In object oriented languages this is a clumpsy way to do what is called pattern matching in most functional languages. You need to define a class which has one method for each function -in the abstract syntax of the grammar. If the functions is called +in the abstract syntax that you want to handle. If the functions is called <tt>f</tt> then you need a method called <tt>on_f</tt>. The method will be called each time when the corresponding function is encountered, and its arguments will be the arguments from the original tree. @@ -589,11 +690,11 @@ we call <tt>visit</tt> recursively to go deeper into the tree. </span> <span class="java"> <p> -For more complex analyses you can use the visitor pattern. -In object oriented languages this is just a clumpsy way to do +Analysing expressions is also made easier by using the visitor pattern. +In object oriented languages this is a clumpsy way to do what is called pattern matching in most functional languages. You need to define a class which has one method for each function -in the abstract syntax of the grammar. If the functions is called +in the abstract syntax that you want to handle. If the functions is called <tt>f</tt> then you need a method called <tt>on_f</tt>. The method will be called each time when the corresponding function is encountered, and its arguments will be the arguments from the original tree. @@ -627,68 +728,6 @@ we call <tt>visit</tt> recursively to go deeper into the tree. </p> </span> -Constructing new trees is also easy. You can either use -<tt>readExpr</tt> to read trees from strings, or you can -construct new trees from existing pieces. This is possible by -<span class="python"> -using the constructor for <tt>pgf.Expr</tt>: -<pre class="python"> ->>> quant = pgf.readExpr("DetQuant IndefArt NumSg") ->>> e2 = pgf.Expr("DetCN", [quant, e]) ->>> print(e2) -DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN theatre_N)) -</pre> -</span> -<span class="haskell"> -using the functions <tt>mkApp</tt>, <tt>mkStr</tt>, <tt>mkInt</tt>, <tt>mkFloat</tt> and <tt>mkMeta</tt>: -<pre class="haskell"> -Prelude PGF2> let Just quant = readExpr "DetQuant IndefArt NumSg" -Prelude PGF2> let e2 = mkApp "DetCN" [quant, e] -Prelude PGF2> print e2 -DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN theatre_N)) -</pre> -</span> -<span class="java"> -using the constructor for <tt>Expr</tt>: -<pre class="java"> -Expr quant = Expr.readExpr("DetQuant IndefArt NumSg"); -Expr e2 = new Expr("DetCN", new Expr[] {quant, e}); -System.out.println(e2); -</pre> -</span> -<span class="csharp"> -using the constructor for <tt>Expr</tt>: -<pre class="csharp"> -Expr quant = Expr.ReadExpr("DetQuant IndefArt NumSg"); -Expr e2 = new Expr("DetCN", new Expr[] {quant, e}); -Console.WriteLine(e2); -</pre> -</span> - -<span class="python"> -<h2>Embedded GF Grammars</h2> - -The GF compiler allows for easy integration of grammars in Haskell -applications. For that purpose the compiler generates Haskell code -that makes the integration of grammars easier. Since Python is a -dynamic language the same can be done at runtime. Once you load -the grammar you can call the method <tt>embed</tt>, which will -dynamically create a Python module with one Python function -for every function in the abstract syntax of the grammar. -After that you can simply import the module: -<pre class="python"> ->>> gr.embed("App") -<module 'App' (built-in)> ->>> import App -</pre> -Now creating new trees is just a matter of calling ordinary Python -functions: -<pre class="python"> ->>> print(App.DetCN(quant,e)) -DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA red_A) (UseN house_N)) -</pre> -</span> - <h2>Access the Morphological Lexicon</h2> There are two methods that gives you direct access to the morphological |