From adcc6a53fef7e56b93c8574c4822f9c7b4d1ea82 Mon Sep 17 00:00:00 2001 From: Krasimir Angelov Date: Tue, 29 Aug 2017 15:28:37 +0200 Subject: a preliminary version of the C# documentation --- doc/runtime-api.html | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 198 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/runtime-api.html b/doc/runtime-api.html index e63899ded..bdff41a06 100644 --- a/doc/runtime-api.html +++ b/doc/runtime-api.html @@ -47,7 +47,7 @@

Loading the Grammar

-Before you use the Python binding you need to import the PGF2 modulepgf modulepgf package. +Before you use the Python binding you need to import the PGF2 modulepgf modulepgf packagePGFSharp package: 
 >>> import pgf
@@ -57,6 +57,9 @@ Prelude> import PGF2 
 import org.grammaticalframework.pgf.*;
+
+using PGFSharp;
+
Once you have the module imported, you can use the dir and help functions to see what kind of functionality is available. @@ -83,10 +86,13 @@ Prelude PGF2> gr <- readPGF "App12.pgf" 
 PGF gr = PGF.readPGF("App12.pgf");
+
+PGF gr = PGF.ReadPGF("App12.pgf");
+
From the grammar you can query the set of available languages. It is accessible through the property languages which -is a map from language name to an object of class pgf.Concrtype Concrclass Concr +is a map from language name to an object of class pgf.Concrtype Concrclass Concrclass Concr which respresents the language. For example the following will extract the English language: 
@@ -102,11 +108,14 @@ eng :: Concr
 
 Concr eng = gr.getLanguages().get("AppEng");
 

+
+Concr eng = gr.Languages["AppEng"];
+

 
 
Parsing

 
 All language specific services are available as 
-methods of the class pgf.Concrfunctions that take as an argument an object of type Concrmethods of the class Concr.
+methods of the class pgf.Concrfunctions that take as an argument an object of type Concrmethods of the class Concrmethods of the class Concr.
 For example to invoke the parser, you can call:
 
 >>> i = eng.parse("this is a small theatre")
@@ -117,6 +126,9 @@ Prelude PGF2> let res = parse eng (startCat gr) "this is a small theatre"
 
 Iterable<ExprProb> iterable = eng.parse(gr.getStartCat(), "this is a small theatre");
 

+
+IEnumerable<Tuple<Expr, float>> enumerable = eng.Parse(gr.StartCat, "this is a small theatre");
+

 
 This gives you an iterator which can enumerate all possible
 abstract trees. You can get the next tree by calling next:
@@ -145,6 +157,14 @@ Iterator<ExprProb> iter = iterable.iterator();
 ExprProb ep = iter.next();
 

 
+
+This gives you an enumerable which can enumerate all possible
+abstract trees. You can get the next tree by calling MoveNext:
+
+enumerable.MoveNext();
+Tuple<Expr, float> ep = enumerable.Current;
+

+
 
 
The results are pairs of probability and tree. The probabilities
 are negated logarithmic probabilities and this means that the lowest
@@ -164,6 +184,10 @@ Prelude PGF2> print p
 System.out.println(ep.getProb());
 35.9166526794
+
+Console.WriteLine(ep.Item2);
+35.9166526794
+
and this is the corresponding abstract tree: 
 >>> print(e)
@@ -177,6 +201,10 @@ PhrUtt NoPConj (UttS (UseCl (TTAnt TPres ASimul) PPos (PredVP (DetNP (DetQuant t
 System.out.println(ep.getExpr());
 PhrUtt NoPConj (UttS (UseCl (TTAnt TPres ASimul) PPos (PredVP (DetNP (DetQuant this_Quant NumSg)) (UseComp (CompNP (DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA small_A) (UseN theatre_N)))))))) NoVoc
+
+Console.WriteLine(ep.Item1);
+PhrUtt NoPConj (UttS (UseCl (TTAnt TPres ASimul) PPos (PredVP (DetNP (DetQuant this_Quant NumSg)) (UseComp (CompNP (DetCN (DetQuant IndefArt NumSg) (AdjCN (PositA small_A) (UseN theatre_N)))))))) NoVoc
+

Note that depending on the grammar it is absolutely possible that for a single sentence you might get infinitely many trees. @@ -219,6 +247,14 @@ over the parser's behaviour: Iterable<ExprProb> iterable = eng.parseWithHeuristics(gr.startCat(), heuristic_factor, callbacks); + +There is also the method ParseWithHeuristics which +takes two more paramaters which let you to have a better control +over the parser's behaviour: +

+IEnumerable<Tuple<Expr, float>> enumerable = eng.ParseWithHeuristics(gr.StartCat, heuristic_factor, callbacks);
+
+

The heuristics factor can be used to trade parsing speed for quality. By default the list of trees is sorted by probability and this corresponds @@ -252,6 +288,9 @@ Prelude PGF2> let Just e = readExpr "AdjCN (PositA red_A) (UseN theatre_N)" 

 Expr e = Expr.readExpr("AdjCN (PositA red_A) (UseN theatre_N)");
+
+Expr e = Expr.ReadExpr("AdjCN (PositA red_A) (UseN theatre_N)");
+
and then we can linearize it: 
 >>> print(eng.linearize(e))
@@ -265,6 +304,10 @@ red theatre
 System.out.println(eng.linearize(e));
 red theatre
+
+Console.WriteLine(eng.Linearize(e));
+red theatre
+
This method produces only a single linearization. If you use variants in the grammar then you might want to see all possible linearizations. For that purpouse you should use linearizeAll: @@ -286,6 +329,13 @@ for (String s : eng.linearizeAll(e)) { red theatre red theater +
+for (String s : eng.LinearizeAll(e)) {
+    Console.WriteLine(s);
+}
+red theatre
+red theater
+
If, instead, you need an inflection table with all possible forms then the right method to use is tabularLinearize: 
@@ -305,6 +355,15 @@ s Pl Nom: red theatres
 s Pl Gen: red theatres'
 s Sg Gen: red theatre's
+
+for (Map.Entry<String,String> entry : eng.TabularLinearize(e).EntrySet()) {
+    Console.WriteLine(entry.Key + ": " + entry.Value);
+}
+s Sg Nom: red theatre
+s Pl Nom: red theatres
+s Pl Gen: red theatres'
+s Sg Gen: red theatre's
+

Finally, you could also get a linearization which is bracketed into @@ -322,6 +381,9 @@ Prelude PGF2> putStrLn (showBracketedString b) 

 Object[] bs = eng.bracketedLinearize(e);
+
+Object[] bs = eng.BracketedLinearize(e);
+
Each element in the sequence above is either a string or an object of type pgf.Bracket. When it is actually a bracket then @@ -362,6 +424,18 @@ the object has the following public final variables:
  • Object[] children - a list with the children of this bracket
    •  + +Each element in the sequence above is either a string or an object +of type Bracket. When it is actually a bracket then +the object has the following public final variables: + +

    The linearization works even if there are functions in the tree @@ -381,6 +455,10 @@ True System.out.println(eng.hasLinearization("apple_N")); true +
    +Console.WriteLine(eng.HasLinearization("apple_N"));
+true
+

    Analysing and Constructing Expressions

    @@ -403,6 +481,13 @@ for (Expr arg : app.getArguments()) { System.out.println(arg); } +
    +ExprApplication app = e.UnApp();
+System.out.println(app.Function);
+for (Expr arg : app.Arguments) {
+   Console.WriteLine(arg);
+}
+

    @@ -438,6 +523,17 @@ For example the output from: Expr elit = Expr.readExpr("\"literal\""); System.out.println(elit.unStr()); + +The result from UnApp is not null if the expression +is an application, and null in all other cases. +Similarly, if the tree is a literal string then the return value +from UnStr will not be null with the actual literal. +For example the output from: + +

    +Expr elit = Expr.ReadExpr("\"literal\"");
+Console.WriteLine(elit.UnStr());
+
    is just the string "literal". Situations like this can be detected in Python by checking the type of the result from unpack. @@ -449,6 +545,9 @@ There are also the functions unAbs, unInt, unFloat an There are also the methods unAbs, unInt, unFloat and unMeta for all other possible cases. + +There are also the methods UnAbs, UnInt, UnFloat and UnMeta for all other possible cases. +

    @@ -518,6 +617,14 @@ Expr e2 = new Expr("DetCN", new Expr[] {quant, e}); System.out.println(e2); + +using the constructor for Expr: +
    +Expr quant = Expr.ReadExpr("DetQuant IndefArt NumSg");
+Expr e2 = new Expr("DetCN", new Expr[] {quant, e});
+Console.WriteLine(e2);
+
    +

    Embedded GF Grammars

    @@ -563,6 +670,13 @@ for (FullFormEntry entry in eng.fullFormLexicon()) { ///// TODO } } +
    +for (FullFormEntry entry in eng.FullFormLexicon) {
+	for (MorphoAnalysis analysis : entry.Analyses) {
+		Console.WriteLine(entry.Form+" "+analysis.Prob+" "+analysis.Lemma+" "+analysis.Field);
+	}
+}
+
    The second one implements a simple lookup. The argument is a word form and the result is a list of analyses: 
    @@ -580,6 +694,13 @@ for (MorphoAnalysis an : eng.lookupMorpho("letter")) {
 letter_1_N, s Sg Nom, inf
 letter_2_N, s Sg Nom, inf
    +
    +for (MorphoAnalysis an : eng.LookupMorpho("letter")) {
+    Console.WriteLine(an.Lemma+", "+an.Field+", "+an.Prob);
+}
+letter_1_N, s Sg Nom, inf
+letter_2_N, s Sg Nom, inf
+

    Access the Abstract Syntax

    @@ -593,7 +714,12 @@ you can get a list of abstract functions: Prelude PGF2> functions gr .... -gr.getFunctions() +
    +List<String> funs = gr.getFunctions()
+....
+
    +
    +IList<String> funs = gr.Functions;
 ....
    or a list of categories: @@ -609,6 +735,10 @@ Prelude PGF2> categories gr List<String> cats = gr.getCategories(); .... +
    +IList<String> cats = gr.Categories;
+....
+
    You can also access all functions with the same result category: 
     >>> gr.functionsByCat("Weekday")
@@ -622,6 +752,10 @@ Prelude PGF2> functionsByCat gr "Weekday"
 List<String> funsByCat = gr.getFunctionsByCat("Weekday");
 ....
    +
    +IList<String> funsByCat = gr.FunctionsByCat("Weekday");
+....
+
    The full type of a function can be retrieved as: 
     >>> print(gr.functionType("DetCN"))
@@ -660,6 +794,11 @@ TypedExpr te = gr.inferExpr(e);
 System.out.println(te.getExpr()+" : "+te.getType());
 AdjCN (PositA red_A) (UseN theatre_N) : CN
    +
    +TypedExpr te = gr.InferExpr(e);
+Console.WriteLine(te.Expr+" : "+te.Type);
+AdjCN (PositA red_A) (UseN theatre_N) : CN
+
    The result is a potentially updated expression and its type. In this case we always deal with simple types, which means that the new expression will be always equal to the original expression. However, this @@ -682,6 +821,10 @@ AdjCN (PositA red_A) (UseN theatre_N) Expr new_e = gr.checkExpr(e,Type.readType("CN")); //// TODO System.out.println(e) +
    +Expr new_e = gr.CheckExpr(e,Type.ReadType("CN"));
+Console.WriteLine(e)
+

    In case of type error you will get an error: 

     >>> e = gr.checkExpr(e,pgf.readType("A"))
@@ -840,6 +983,20 @@ n3 -- n4 [style = "solid"]
 n0 -- n3 [style = "solid"]
 }
    +
    +Console.WriteLine(gr.GraphvizAbstractTree(e));
+graph {
+n0[label = "AdjCN", style = "solid", shape = "plaintext"]
+n1[label = "PositA", style = "solid", shape = "plaintext"]
+n2[label = "red_A", style = "solid", shape = "plaintext"]
+n1 -- n2 [style = "solid"]
+n0 -- n1 [style = "solid"]
+n3[label = "UseN", style = "solid", shape = "plaintext"]
+n4[label = "theatre_N", style = "solid", shape = "plaintext"]
+n3 -- n4 [style = "solid"]
+n0 -- n3 [style = "solid"]
+}
+
     >>> print(eng.graphvizParseTree(e))
@@ -951,6 +1108,43 @@ graph {
   n0 -- n100000
   n2 -- n100001
 }
+
    +
    +Console.WriteLine(eng.GraphvizParseTree(e));
+graph {
+  node[shape=plaintext]
+
+  subgraph {rank=same;
+    n4[label="CN"]
+  }
+
+  subgraph {rank=same;
+    edge[style=invis]
+    n1[label="AP"]
+    n3[label="CN"]
+    n1 -- n3
+  }
+  n4 -- n1
+  n4 -- n3
+
+  subgraph {rank=same;
+    edge[style=invis]
+    n0[label="A"]
+    n2[label="N"]
+    n0 -- n2
+  }
+  n1 -- n0
+  n3 -- n2
+
+  subgraph {rank=same;
+    edge[style=invis]
+    n100000[label="red"]
+    n100001[label="theatre"]
+    n100000 -- n100001
+  }
+  n0 -- n100000
+  n2 -- n100001
+}
    -- cgit v1.2.3