PATR100 DLL Reference Manual COM Interface for unification based parsing based on PATR functions version 1.2.2 April 2000 by Stephen McConnel Copyright (C) 2000 SIL International Published by: Language Software Development SIL International 7500 W. Camp Wisdom Road Dallas, TX 75236 U.S.A. Permission is granted to make and distribute verbatim copies of this file provided the copyright notice and this permission notice are preserved in all copies. The author may be reached at the address above or via email as `steve@acadcomp.sil.org'. Introduction to the AMPLE DLL ***************************** PC-PATR is an implementation for personal computers of the PATR-II computational linguistic formalism. The PATR-II formalism can be viewed as a computer language for encoding linguistic information. It does not presuppose any particular theory of syntax. It was originally developed by Stuart M. Shieber at Stanford University in the early 1980's. A PATR-II grammar consists of a set of rules and a lexicon. Each rule consists of a context-free _phrase structure rule_ and a set of _feature constraints_, that is, _unifications_ on the _feature structures_ associated with the constituents of the phrase structure rules. The lexicon provides the items that can replace the terminal symbols of the phrase structure rules, that is, the words of the language together with their relevant features. The PATR100 DLL is built with the processing functions used by PC-PATR and related programs. It has been developed with the goal of making it easier to use PATR-II style parsing as a component in Windows programs written in different programming languages such as C++ or Visual Basic. PC-PATR (and thus this COM DLL) is still under development. The author would appreciate feedback directed to the following address: Stephen McConnel (972)708-7361 (office) Language Software Development (972)708-7561 (fax) SIL International 7500 W. Camp Wisdom Road Dallas, TX 75236 steve@acadcomp.sil.org U.S.A. or Stephen_McConnel@sil.org The PatrParser Interface ************************ In order to facilitate using the PC-PATR functions from programming languages such as Visual Basic, a COM interface named `IPatrParser' has been written to encapsulate the essential PC-PATR functionality. This interface has the properties and methods described below. The AmplePropertyIsFeature property =================================== Interface description --------------------- [propget] HRESULT AmplePropertyIsFeature([out, retval] BOOL * pVal); [propput] HRESULT AmplePropertyIsFeature([in] BOOL newVal); C++ prototypes -------------- HRESULT get_AmplePropertyIsFeature(BOOL * pVal); HRESULT put_AmplePropertyIsFeature(BOOL newVal); Description ----------- This Boolean property controls whether or not the values in the AMPLE analysis `\p' (property) field are to be interpreted as feature template names, the same as the values in the AMPLE analysis `\fd' (feature descriptor) field. If it is `true', then the values in the AMPLE analysis `\p' field are interpreted as feature template names. If it is `false', then the AMPLE analysis `\p' field is ignored except for adding it verbatim to the lexicon feature structure as an atomic feature value with the label `"properties"'. The `AmplePropertyIsFeature' property corresponds to the `set property-is-feature' command in the PCPATR program. Default Value ------------- `false' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox AmplePropertyIsFeature Caption = "Interpret AMPLE Properties as Features" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... AmplePropertyIsFeature.Value = m_patr.AmplePropertyIsFeature ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.AmplePropertyIsFeature = AmplePropertyIsFeature.Value ... End Function C++ Example ----------- // TODO: write an example The CheckCycles property ======================== Interface description --------------------- [propget] HRESULT CheckCycles([out, retval] BOOL * pVal); [propput] HRESULT CheckCycles([in] BOOL newVal); C++ prototypes -------------- HRESULT get_CheckCycles(BOOL * pVal); HRESULT put_CheckCycles(BOOL newVal); Description ----------- This Boolean property controls whether or not feature structures are checked for cycles following unification. If it is `true', then feature structures are checked. If it is `false', then no check is performed. It is a bad idea to set this property to `false' unless the grammer is known to _never_ create cycles during parsing, even for failed parses. The `CheckCycles' property corresponds to the `set check-cycles' command in the PCPATR program. Default Value ------------- `true' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox CheckCycles Caption = "Check Features for Cycles" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... CheckCycles.Value = m_patr.CheckCycles ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.CheckCycles = CheckCycles.Value ... End Function C++ Example ----------- // TODO: write an example The Clear method ================ Interface description --------------------- HRESULT Clear(); C++ prototypes -------------- HRESULT Clear(); Description ----------- This method frees all of the allocated memory, erasing any lexicon or grammar file that has been loaded. The `Clear' method corresponds to the `clear' command in the PCPATR program. Return Value ------------ `S_OK' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.Menu FileMenu Caption = "&File" ... Begin VB.Menu ClearCmd Caption = "Clear" End ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub ClearCmd_Click() On Error GoTo Failed m_patr.Clear Call resetdialogbox ... Exit Sub Failed: MsgBox "Clear Failed" Exit Sub End Sub C++ Example ----------- // TODO: write an example The CloseLog method =================== Interface description --------------------- HRESULT CloseLog(); C++ prototypes -------------- HRESULT CloseLog(); Description ----------- This method closes the open log file. The `CloseLog' method corresponds to the `close' command in the PCPATR program. Return Value ------------ `S_OK', or E_UNEXPECTED if a log file was not open Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.Menu FileMenu Caption = "&File" ... Begin VB.Menu CloseLogCmd Caption = "&Close Log" End ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub CloseLogCmd_Click() On Error GoTo Failed m_patr.CloseLog LogFile.Text = "" Exit Sub Failed: MsgBox "Closing Log File Failed" Exit Sub End Sub C++ Example ----------- // TODO: write an example The CodePage property ===================== Interface description --------------------- [propget] HRESULT CodePage([out, retval] long * pVal); [propput] HRESULT CodePage([in] long newVal); C++ prototypes -------------- HRESULT get_CodePage(long * pVal); HRESULT put_CodePage(long newVal); Description ----------- This integer property selects the code page used for converting between the 16-bit Unicode characters used in BSTRs (and XML) and the 8-bit multibyte characters used by the PCPATR functions and the grammar and lexicon files. The `CodePage' property has no corresponding command in the PCPATR program. It is useful primarily for converting from the 8-bit characters used by the PCPATR functions and files into the 16-bit Unicode characters used by the BSTRs used by COM interface methods. It is also useful for designating the encoding in XML files produced by the PCPATR output functions. Default Value ------------- `CP_ACP' (the ANSI code page) Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox CodePage ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... Select Case m_patr.CodePage Case 0 CodePage.Text = "ANSI" Case 1 CodePage.Text = "OEM" Case 2 CodePage.Text = "MAC" Case 42 CodePage.Text = "SYMBOL" Case 65000 CodePage.Text = "UTF7" Case 65001 CodePage.Text = "UTF8" Case Else CodePage.Text = m_patr.CodePage End Select ... End Sub ... Private Function DoSettings() As Boolean ... If CodePage.Text = "ANSI" Then m_patr.CodePage = 0 ElseIf CodePage.Text = "OEM" Then m_patr.CodePage = 1 ElseIf CodePage.Text = "MAC" Then m_patr.CodePage = 2 ElseIf CodePage.Text = "SYMBOL" Then m_patr.CodePage = 42 ElseIf CodePage.Text = "UTF7" Then m_patr.CodePage = 65000 ElseIf CodePage.Text = "UTF8" Then m_patr.CodePage = 65001 Else m_patr.CodePage = CodePage.Text End If ... End Function C++ Example ----------- // TODO: write an example The CommentChar property ======================== Interface description --------------------- [propget] HRESULT CommentChar([out, retval] long * pVal); [propput] HRESULT CommentChar([in] long newVal); C++ prototypes -------------- HRESULT get_CommentChar(long * pVal); HRESULT put_CommentChar(long newVal); Description ----------- This integer property selects the 8-bit character used to mark the beginning of comments in the grammar and lexicon files. If `newVal' is 0, then no comments are allowed in the grammar and lexicon files. The `CommentChar' property corresponds to the `set comment' command in the PCPATR program. Default Value ------------- the semicolon character (`;') Return Value ------------ `S_OK', or one of these COM error codes: * `E_INVALIDARG' if `newVal' is out of range (less than 0 or greater than 255) * `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox CommentChar ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... CommentChar.Text = Chr(m_patr.CommentChar) ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.CommentChar = Asc(CommentChar.Text) ... End Function C++ Example ----------- // TODO: write an example The DebuggingLevel property =========================== Interface description --------------------- [propget] HRESULT DebuggingLevel([out, retval] long * pVal); [propput] HRESULT DebuggingLevel([in] long newVal); C++ prototypes -------------- HRESULT get_DebuggingLevel(long * pVal); HRESULT put_DebuggingLevel(long newVal); Description ----------- This integer property selects the level of debugging output written to the log file. This property is of use primarily to the programmer maintaining PCPATR. It corresponds to the virtually undocumented `-/' command line option. Default Value ------------- `0' Return Value ------------ `S_OK', or one of these COM error codes: * `E_INVALIDARG' if `newVal' is out of range (less than 0) * `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox DebugLevel ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... DebugLevel.Text = m_patr.DebuggingLevel ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.DebuggingLevel = DebugLevel.Text ... End Function C++ Example ----------- // TODO: write an example The DisambiguateAnaFile method ============================== Interface description --------------------- HRESULT DisambiguateAnaFile([in] BSTR bstrInput, [in] BSTR bstrOutput); C++ prototypes -------------- HRESULT DisambiguateAnaFile(BSTR bstrInput, BSTR bstrOutput); Description ----------- This method disambiguates word analyses in an AMPLE analysis file by applying a syntactice parse to the sentences in the analysis file. It reads the file given by `bstrInput', and writes a new AMPLE analysis file given by `bstrOutput'. Return Value ------------ `S_OK', `E_INVALIDARG', `E_FAIL', or another appropriate COM error code Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin MSComDlg.CommonDialog AnaDlg ... End Begin MSComDlg.CommonDialog AnbDlg ... End Begin VB.Menu FileMenu Caption = "&File" ... Begin VB.Menu DisambigFileCmd Caption = "&Disambiguate File..." End ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... AnaDlg.Filter = "AMPLE ANA files|*.ana" AnaDlg.CancelError = True AnbDlg.Filter = "Disam ANA files|*.anb" AnbDlg.CancelError = True ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub DisambigFileCmd_Click() If Not IsReadyToParse Then Exit Sub End If If Not DoSettings Then Exit Sub End If On Error GoTo Cancelled AnaDlg.ShowOpen AnbDlg.ShowOpen On Error GoTo Failed m_patr.SentenceFinalPunctuation m_patr.DisambiguateAnaFile AnaDlg.FileName, AnbDlg.FileName MsgBox "Done parsing " & AnaDlg.FileName Exit Sub Failed: MsgBox "Parsing " & AnaDlg.FileName & " into " & AnbDlg.FileName & " Failed" Exit Sub Cancelled: Exit Sub End Sub C++ Example ----------- // TODO: write an example The DisplayFeatures property ============================ Interface description --------------------- [propget] HRESULT DisplayFeatures([out, retval] BOOL * pVal); [propput] HRESULT DisplayFeatures([in] BOOL newVal); C++ prototypes -------------- HRESULT get_DisplayFeatures(BOOL * pVal); HRESULT put_DisplayFeatures(BOOL newVal); Description ----------- This Boolean property controls whether or not any feature structures are displayed in the parse output. If it is `true', then one or more features structures are displayed, with the exact details controlled by the `FlatFeatureDisplay', `TopFeatureOnly', and `TrimEmptyFeatures' properties. If `DisplayFeatures' is `false', then no features are displayed in parse output. The `DisplayFeatures' property corresponds to the `set features on' and `set features off' commands in the PCPATR program. Default Value ------------- `true' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.Frame Frame1 ... Begin VB.OptionButton FeaturesOn Caption = "On" ... End Begin VB.OptionButton FeaturesOff Caption = "Off" ... End End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... If m_patr.DisplayFeatures Then FeaturesOn.Value = True ... Else FeaturesOff.Value = True ... End If ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.DisplayFeatures = FeaturesOn.Value ... End Function C++ Example ----------- // TODO: write an example The Failures property ===================== Interface description --------------------- [propget] HRESULT Failures([out, retval] BOOL * pVal); [propput] HRESULT Failures([in] BOOL newVal); C++ prototypes -------------- HRESULT get_Failures(BOOL * pVal); HRESULT put_Failures(BOOL newVal); Description ----------- This Boolean property controls how the PCPATR parse functions deal with sentences that fail to parse. If it is `true', then an attempt is made to produce partial results in a three stage process: 1. If unification is on, turn it off, try again to parse the sentence, and turn unification back on. 2. If the preceding step does not produce any results, and top-down filtering is on, turn off top-down filtering, try again to parse the sentence, and turn top-down filtering back on. 3. If the preceding steps have not produced any results, call a special function to link the partial results stored in the parse chart together for display as a set of (possibly intersecting) parse "bushes". If any sort of partial result is obtained by these steps, then that partial result will be returned by the parse method, along with a parse failure indication. The `Failures' property corresponds to the `set failures' command in the PCPATR program. Default Value ------------- `false' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox PartialResults Caption = "Partial Results for Failures" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... PartialResults.Value = m_patr.Failures ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.Failures = PartialResults.Value ... End Function C++ Example ----------- // TODO: write an example The FlatFeatureDisplay property =============================== Interface description --------------------- [propget] HRESULT FlatFeatureDisplay([out, retval] BOOL * pVal); [propput] HRESULT FlatFeatureDisplay([in] BOOL newVal); C++ prototypes -------------- HRESULT get_FlatFeatureDisplay(BOOL * pVal); HRESULT put_FlatFeatureDisplay(BOOL newVal); Description ----------- This Boolean property controls how feature structures are displayed (if `DisplayFeatures' is `true'). If it is `true', then each parse node feature is written as a flat bracketed string, with open and close brackets marking the boundaries of complex features. This format requires the least amount of space on the screen or in a file. If `FlatFeaturesDisplay' is `false', then each parse node feature is written as a bracketed string, with open and close brackets marking the boundaries of complex features, and with newlines and spaces used to line up the labels of internal features in a column for embedded features. This works best for short labels and fixed width fonts. Note that while the `DisplayFeatures' property is `false', this property has no effect on the parse output. The `FlatFeatureDisplay' property corresponds to the `set features flat' and `set features full' commands in the PCPATR program. Default Value ------------- `false' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox FlatFeatures Caption = "Flat Feature Format" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... FlatFeatures.Value = m_patr.FlatFeatureDisplay ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.FlatFeatureDisplay = FlatFeatures.Value ... End Function C++ Example ----------- // TODO: write an example The Gloss property ================== Interface description --------------------- [propget] HRESULT Gloss([out, retval] BOOL * pVal); [propput] HRESULT Gloss([in] BOOL newVal); C++ prototypes -------------- HRESULT get_Gloss(BOOL * pVal); HRESULT put_Gloss(BOOL newVal); Description ----------- This Boolean property controls whether glosses are displayed in the parse tree output in addition to the lexical forms for the leaf nodes of the parse tree. If the lexicon does not contain any glosses, this property has no effect. If `Gloss' is `true', then glosses are displayed in parse trees (if the lexicon contains glosses). If `Gloss' is `false', then glosses are not displayed in parse trees even if they exist in the lexicon. Note that feature structures associated with leaf nodes in the parse tree will contain any glosses found in the lexicon regardless of the value of this property. The `Gloss' property corresponds to the `set gloss' command in the PCPATR program. Default Value ------------- `true' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox EnableGlosses Caption = "Enable Display of Glosses" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... EnableGlosses.Value = m_patr.Gloss ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.Gloss = EnableGlosses.Value ... End Function C++ Example ----------- // TODO: write an example The GrammarFile property ======================== Interface description --------------------- [propget] HRESULT GrammarFile([out, retval] BSTR * pVal); C++ prototypes -------------- HRESULT get_GrammarFile(BSTR * pVal); Description ----------- This string property contains the name of the grammar file most recently loaded by a `LoadGrammarFile' method. If `LoadGrammarFile' has never been called, or if `Clear' has been called since `LoadGrammarFile', then this property is set to `NULL'. The `GrammarFile' property corresponds to part of the `status' command in the PCPATR program. Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory for the output `BSTR' fails * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox GrammarFile Enabled = 0 'False ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... GrammarFile.Text = m_patr.GrammarFile ... End Sub C++ Example ----------- // TODO: write an example The LexCategoryMarker property ============================== Interface description --------------------- [propget] HRESULT LexCategoryMarker([out, retval] BSTR * pVal); [propput] HRESULT LexCategoryMarker([in] BSTR newVal); C++ prototypes -------------- HRESULT get_LexCategoryMarker(BSTR * pVal); HRESULT put_LexCategoryMarker(BSTR newVal); Description ----------- This string property contains the standard format marker used to indicate the syntactic category field of lexicon entries. The "category" is what connect the lexicon entry to the grammar rules. It is copied to the word's lexical feature structure as the embedded `cat' feature. The `LexCategoryMarker' property corresponds to the `set marker category' command in the PCPATR program. Default Value ------------- `\c' (C string would be `"\\c"') Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory fails for either the output `BSTR' or the internal 8-bit character string * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox CategoryMarker ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... CategoryMarker.Text = m_patr.LexCategoryMarker ... End Sub ... Private Function SetLexMarkers() As Boolean SetLexMarkers = False On Error GoTo Failed ... If (CategoryMarker.Text = "") Or (CategoryMarker.Text = "\") Then MsgBox "The Category marker must be set before loading the lexicon" Exit Function End If ... m_patr.LexCategoryMarker = CategoryMarker.Text ... SetLexMarkers = True Exit Function Failed: Exit Function End Function C++ Example ----------- // TODO: write an example The LexFeaturesMarker property ============================== Interface description --------------------- [propget] HRESULT LexFeaturesMarker([out, retval] BSTR * pVal); [propput] HRESULT LexFeaturesMarker([in] BSTR newVal); C++ prototypes -------------- HRESULT get_LexFeaturesMarker(BSTR * pVal); HRESULT put_LexFeaturesMarker(BSTR newVal); Description ----------- This string property contains the standard format marker used to indicate the features field of lexicon entries. The content of this field is usually a set of names of feature templates (or lexical rules) defined in the grammar file. The `LexFeaturesMarker' property corresponds to the `set marker features' command in the PCPATR program. Default Value ------------- `\f' (C string would be `"\\f"') Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory fails for either the output `BSTR' or the internal 8-bit character string * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox FeatureMarker ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... FeatureMarker.Text = m_patr.LexFeaturesMarker ... End Sub ... Private Function SetLexMarkers() As Boolean SetLexMarkers = False On Error GoTo Failed ... If (FeatureMarker.Text = "") Or (FeatureMarker.Text = "\") Then MsgBox "The Feature marker must be set before loading the lexicon" Exit Function End If ... m_patr.LexFeaturesMarker = FeatureMarker.Text ... SetLexMarkers = True Exit Function Failed: Exit Function End Function C++ Example ----------- // TODO: write an example The LexGlossMarker property =========================== Interface description --------------------- [propget] HRESULT LexGlossMarker([out, retval] BSTR * pVal); [propput] HRESULT LexGlossMarker([in] BSTR newVal); C++ prototypes -------------- HRESULT get_LexGlossMarker(BSTR * pVal); HRESULT put_LexGlossMarker(BSTR newVal); Description ----------- This string property contains the standard format marker used to indicate the gloss field of lexicon entries. The content of this field is copied to the word's lexical feature structure as the embedded `gloss' feature. The `LexGlossMarker' property corresponds to the `set marker gloss' command in the PCPATR program. Default Value ------------- `\g' (C string would be `"\\g"') Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory fails for either the output `BSTR' or the internal 8-bit character string * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox GlossMarker ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... GlossMarker.Text = m_patr.LexGlossMarker ... End Sub ... Private Function SetLexMarkers() As Boolean SetLexMarkers = False On Error GoTo Failed ... If (GlossMarker.Text = "") Or (GlossMarker.Text = "\") Then MsgBox "The Gloss marker must be set before loading the lexicon" Exit Function End If ... m_patr.LexGlossMarker = GlossMarker.Text ... SetLexMarkers = True Exit Function Failed: Exit Function End Function C++ Example ----------- // TODO: write an example The LexiconFile property ======================== Interface description --------------------- [propget] HRESULT LexiconFile([in] long iFile, [out, retval] BSTR * pVal); C++ prototypes -------------- HRESULT get_LexiconFile(long iFile, BSTR * pVal); Description ----------- This string property contains the name of one of the lexicon files most recently loaded by a `LoadLexiconFile' method. If `LoadLexiconFile' has never been called, or if `Clear' has been called since `LoadLexiconFile', then this property is set to `NULL'. This property is also set to `NULL' if `iFile' is outside the range (`0', `LexiconFileCount - 1'). The `LexiconFile' property corresponds to part of the `status' command in the PCPATR program. Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory for the output `BSTR' fails * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- ' TODO: write an example retrieving multiple lexicon filenames. Begin VB.Form Form1 ... Begin VB.TextBox LexiconFile Enabled = 0 'False ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... LexiconFile.Text = m_patr.LexiconFile(0) ... End Sub ... Private Function DoSettings() As Boolean ... ... End Function C++ Example ----------- // TODO: write an example The LexiconFileCount property ============================= Interface description --------------------- [propget] HRESULT LexiconFileCount([out, retval] long * pVal); C++ prototypes -------------- HRESULT get_LexiconFileCount(long * pVal); Description ----------- This integer property contains the number of lexicon files that are currently loaded. It is always greater than or equal to zero. Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.Label LexFileCnt ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... LexFileCnt.Caption = m_patr.LexiconFileCount & "Lexicon Files" ... End Sub C++ Example ----------- // TODO: write an example The LexRecordMarker property ============================ Interface description --------------------- [propget] HRESULT LexRecordMarker([out, retval] BSTR * pVal); [propput] HRESULT LexRecordMarker([in] BSTR newVal); C++ prototypes -------------- HRESULT get_LexRecordMarker(BSTR * pVal); HRESULT put_LexRecordMarker(BSTR newVal); Description ----------- This string property contains the standard format marker used to indicate the beginning of each entry in the lexicon file. It may be the same as one of the other lexicon marker properties. The `LexRecordMarker' property corresponds to the `set marker record' command in the PCPATR program. Default Value ------------- `\w' (C string would be `"\\w"') Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory fails for either the output `BSTR' or the internal 8-bit character string * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox RecordMarker ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... RecordMarker.Text = m_patr.LexRecordMarker ... End Sub ... Private Function SetLexMarkers() As Boolean SetLexMarkers = False On Error GoTo Failed ... If (RecordMarker.Text = "") Or (RecordMarker.Text = "\") Then MsgBox "The Record marker must be set before loading the lexicon" Exit Function End If ... m_patr.LexRecordMarker = RecordMarker.Text ... SetLexMarkers = True Exit Function Failed: Exit Function End Function C++ Example ----------- // TODO: write an example The LexWordMarker property ========================== Interface description --------------------- [propget] HRESULT LexWordMarker([out, retval] BSTR * pVal); [propput] HRESULT LexWordMarker([in] BSTR newVal); C++ prototypes -------------- HRESULT get_LexWordMarker(BSTR * pVal); HRESULT put_LexWordMarker(BSTR newVal); Description ----------- This string property contains the standard format marker used to indicate the word field of lexicon entries. The content of this field is copied to the word's lexical feature structure as the embedded `lex' feature. The `LexWordMarker' property corresponds to the `set marker word' command in the PCPATR program. Default Value ------------- `\w' (C string would be `"\\w"') Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory fails for either the output `BSTR' or the internal 8-bit character string * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox WordMarker ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... WordMarker.Text = m_patr.LexWordMarker ... End Sub ... Private Function SetLexMarkers() As Boolean SetLexMarkers = False On Error GoTo Failed ... If (WordMarker.Text = "") Or (WordMarker.Text = "\") Then MsgBox "The Word marker must be set before loading the lexicon" Exit Function End If ... m_patr.LexWordMarker = WordMarker.Text ... SetLexMarkers = True Exit Function Failed: Exit Function End Function C++ Example ----------- // TODO: write an example The LoadAnaFile method ====================== Interface description --------------------- HRESULT LoadAnaFile([in] BSTR bstrAnaFile, [in] BOOL fAdd); C++ prototypes -------------- HRESULT LoadAnaFile(BSTR bstrAnaFile, BOOL fAdd); Description ----------- This method loads an AMPLE analysis file as a lexicon file. Return Value ------------ `S_OK', or one of these COM error codes: * `E_INVALIDARG' if `bstrAnaFile' is `NULL', or if that file has already been loaded as a lexicon file * `E_FAIL' if an error occurs during the load process * `E_OUTOFMEMORY' if allocating memory fails for any reason. In this case, the in-memory lexicon may or may not contain any entries. * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin MSComDlg.CommonDialog AnaDlg ... End ... Begin VB.Menu FileMenu Caption = "&File" ... Begin VB.Menu LoadLexiconCmd Caption = "Load &Ana file..." End ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If ... AnaDlg.Filter = "AMPLE Analysis Files|*.ana" AnaDlg.CancelError = True ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub LoadLexiconCmd_Click() If Not SetLexMarkers Then Exit Sub End If If Not DoSettings Then Exit Sub End If On Error GoTo Cancelled AnaDlg.ShowOpen On Error GoTo Failed m_patr.LoadAnaFile AnaDlg.FileName, False LexiconFile.Text = AnaDlg.FileName Exit Sub Failed: MsgBox "Loading " & AnaDlg.FileName & " Failed" Exit Sub Cancelled: Exit Sub End Sub C++ Example ----------- // TODO: write an example The LoadGrammarFile method ========================== Interface description --------------------- HRESULT LoadGrammarFile([in] BSTR bstrGrammarFile); C++ prototypes -------------- HRESULT LoadGrammarFile(BSTR bstrGrammarFile); Description ----------- This method loads a PCPATR grammar file into memory, first erasing any grammar that had been previously loaded. The `LoadGrammarFile' method corresponds to the `load grammar' command in the PCPATR program. Return Value ------------ `S_OK', or one of these COM error codes: * `E_INVALIDARG' if `bstrGrammarFile' is `NULL' * `E_FAIL' if an error occurs during the load process * `E_OUTOFMEMORY' if allocating memory fails converting `bstrGrammarFile' to an 8-bit character string * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin MSComDlg.CommonDialog GrmDlg ... End ... Begin VB.Menu FileMenu Caption = "&File" Begin VB.Menu LoadGrammarCmd Caption = "Load &Grammar..." End ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If ... GrmDlg.Filter = "PC-PATR Grammar Files|*.grm" GrmDlg.CancelError = True ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub LoadGrammarCmd_Click() If Not DoSettings Then Exit Sub End If On Error GoTo Cancelled GrmDlg.ShowOpen On Error GoTo Failed m_patr.LoadGrammarFile GrmDlg.FileName GrammarFile.Text = GrmDlg.FileName Exit Sub Failed: MsgBox "Loading " & GrmDlg.FileName & " Failed" Exit Sub Cancelled: Exit Sub End Sub C++ Example ----------- // TODO: write an example The LoadLexiconFile method ========================== Interface description --------------------- HRESULT LoadLexiconFile([in] BSTR bstrLexiconFile, [in] BOOL fAdd); C++ prototypes -------------- HRESULT LoadLexiconFile(BSTR bstrLexiconFile, BOOL fAdd); Description ----------- This method loads a PCPATR lexicon file into memory, first erasing any lexicon that had been previously loaded unless `fAdd' is `True'. If `fAdd' is `True', then `bstrLexiconFile' must not have already been loaded. The `LoadLexiconFile' method corresponds to the `load lexicon' command in the PCPATR program. Return Value ------------ `S_OK', or one of these COM error codes: * `E_INVALIDARG' if `bstrLexiconFile' is `NULL', or if that file has already been loaded as a lexicon file * `E_FAIL' if an error occurs during the load process * `E_OUTOFMEMORY' if allocating memory fails converting `bstrLexiconFile' to an 8-bit character string, or storing the filename. In the latter case, the entire lexicon is unloaded from memory. * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin MSComDlg.CommonDialog LexDlg ... End ... Begin VB.Menu FileMenu Caption = "&File" ... Begin VB.Menu LoadLexiconCmd Caption = "Load &Lexicon..." End ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If ... LexDlg.Filter = "PC-PATR Lexicon Files|*.lex" LexDlg.CancelError = True ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub LoadLexiconCmd_Click() If Not SetLexMarkers Then Exit Sub End If If Not DoSettings Then Exit Sub End If On Error GoTo Cancelled LexDlg.ShowOpen On Error GoTo Failed m_patr.LoadLexiconFile LexDlg.FileName, False LexiconFile.Text = LexDlg.FileName Exit Sub Failed: MsgBox "Loading " & LexDlg.FileName & " Failed" Exit Sub Cancelled: Exit Sub End Sub C++ Example ----------- // TODO: write an example The LogFile property ==================== Interface description --------------------- [propget] HRESULT LogFile([out, retval] BSTR * pVal); C++ prototypes -------------- HRESULT get_LogFile(BSTR * pVal); Description ----------- This string property contains the name of the currently open log file, if there is one. If no log file is currently open, then this property is set to `NULL'. The `LogFile' property corresponds to part of the `status' command in the PCPATR program. Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory for the output `BSTR' fails * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox LogFile Enabled = 0 'False ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... LogFile.Text = m_patr.LogFile ... End Sub C++ Example ----------- // TODO: write an example The MaxAmbiguity property ========================= Interface description --------------------- [propget] HRESULT MaxAmbiguity([out, retval] long * pVal); [propput] HRESULT MaxAmbiguity([in] long newVal); C++ prototypes -------------- HRESULT get_MaxAmbiguity(long * pVal); HRESULT put_MaxAmbiguity(long newVal); Description ----------- This integer property specifies the maximum number of parses displayed for an ambiguous parse. This can be critical because the number of parses for long sentences can run into the thousands, especially in the early stages of developing a grammar. The `MaxAmbiguity' property corresponds to the `set ambiguities' command in the PCPATR program. Default Value ------------- `10' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox MaxAmbiguity ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... MaxAmbiguity.Text = m_patr.MaxAmbiguity ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.MaxAmbiguity = MaxAmbiguity.Text ... End Function C++ Example ----------- // TODO: write an example The OpenLog method ================== Interface description --------------------- HRESULT OpenLog([in] BSTR bstrLogFile); C++ prototypes -------------- HRESULT OpenLog(BSTR bstrLogFile); Description ----------- This method opens a log file after first closing any previously opened log file. The log file receives various error messages and other information produced by the load and parse methods which would otherwise go unreported. If a file of the same name already exists, it is replaced by the new log file. The `OpenLog' method corresponds to the `log' command in the PCPATR program. Return Value ------------ `S_OK', or one of these COM error codes: * `E_INVALIDARG' if `bstrLogFile' is `NULL' * `E_FAIL' if the log file cannot be opened * `E_OUTOFMEMORY' if allocating memory fails converting `bstrLogFile' to an 8-bit character string * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin MSComDlg.CommonDialog LogDlg ... End ... Begin VB.TextBox LogFile Enabled = 0 'False ... End ... Begin VB.Menu FileMenu Caption = "&File" ... Begin VB.Menu OpenLogCmd Caption = "&Open Log" End ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If ... LogDlg.Filter = "PC-PATR Log Files|*.log" LogDlg.CancelError = True ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub OpenLogCmd_Click() On Error GoTo Cancelled LogDlg.ShowOpen On Error GoTo Failed m_patr.OpenLog LogDlg.FileName LogFile.Text = LogDlg.FileName Exit Sub Failed: MsgBox "Opening Log File " & LogDlg.FileName & " Failed" Exit Sub Cancelled: Exit Sub End Sub C++ Example ----------- // TODO: write an example The ParseFile method ==================== Interface description --------------------- HRESULT ParseFile([in] BSTR bstrInput, [in] BSTR bstrOutput); C++ prototypes -------------- HRESULT ParseFile(BSTR bstrInput, BSTR bstrOutput); Description ----------- This method reads sentences from a file and writes the resulting parses to another file. Each line of the input file represents a separate "sentence", and punctuation and sentence capitalization should not be used. Proper names should be capitalized the same way they are in the lexicon. Actually, punctuation can be used if three conditions are met: 1. Punctuation "categories" are used in the grammar rules. 2. Punctuation characters and their "categories" are listed in the lexicon. 3. Punctuation characters are separated by spaces from words and from each other in the input sentences. Constructs which use a specific punctuation character such as an apostrophe (English possessives and contractions) must be handled differently, possibly by a preprocessor step that splits contractions into multiple words as needed. [NOTE: PCPATR can handle having a phrase as a single entry (category) in the lexicon. Can it also handle a contraction representing two or more consecutive syntactic categories? Should it?] The `ParseFile' method corresponds to the `file parse' command in the PCPATR program. Return Value ------------ `S_OK', or one of these COM error codes: * `E_INVALIDARG' if either `bstrInput' or `bstrOutput' is `NULL' * `E_FAIL' if either the input file or the output file cannot be opened * `E_OUTOFMEMORY' if allocating memory fails converting either `bstrInput' or `bstrOutput' to an 8-bit character string * `E_UNEXPECTED' in very bizarre circumstances Note that the return value does not depend on whether or not any of the sentences successfully parses. Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin MSComDlg.CommonDialog SenDlg ... End Begin MSComDlg.CommonDialog ParDlg ... End Begin VB.Menu FileMenu Caption = "&File" ... Begin VB.Menu ParseFileCmd Caption = "&Parse File..." End ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... SenDlg.Filter = "Sentence files|*.sen" SenDlg.CancelError = True ParDlg.Filter = "Parse output files|*.par" ParDlg.CancelError = True ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub ParseFileCmd_Click() If Not IsReadyToParse Then Exit Sub End If If Not DoSettings Then Exit Sub End If On Error GoTo Cancelled SenDlg.ShowOpen ParDlg.ShowOpen On Error GoTo Failed m_patr.ParseFile SenDlg.FileName, ParDlg.FileName MsgBox "Done parsing " & SenDlg.FileName Exit Sub Failed: MsgBox "Parsing " & SenDlg.FileName & " into " & ParDlg.FileName & " Failed" Exit Sub Cancelled: Exit Sub End Sub C++ Example ----------- // TODO: write an example The ParseString method ====================== Interface description --------------------- HRESULT ParseString( [in] BSTR bstrSentence, [out, retval] BSTR * pbstrParse); C++ prototypes -------------- HRESULT ParseString(BSTR bstrSentence, BSTR * pbstrParse); Description ----------- This method parses the input sentence and produces a string containing the parse results. Punctuation and sentence capitalization should not be used in the input sentence. Proper names should be capitalized the same way they are in the lexicon. Actually, punctuation can be used if three conditions are met: 1. Punctuation "categories" are used in the grammar rules. 2. Punctuation characters and their "categories" are listed in the lexicon. 3. Punctuation characters are separated by spaces from words and from each other in the input sentence. Constructs which use a specific punctuation character such as an apostrophe (English possessives and contractions) must be handled differently, possibly by a preprocessor step that splits contractions into multiple words as needed. [NOTE: PCPATR can handle having a phrase as a single entry (category) in the lexicon. Can it also handle a contraction representing two or more consecutive syntactic categories? Should it?] The `ParseString' method corresponds to the `parse' command in the PCPATR program. Return Value ------------ `S_OK', or one of these COM error codes: * `E_INVALIDARG' if `bstrSentence' is `NULL', * `E_POINTER' if `pbstrParse' is `NULL', * `E_UNEXPECTED' if either the grammar or the lexicon has not yet been loaded (or possibly in some other, very bizarre, circumstances), * `E_OUTOFMEMORY' if allocating memory fails during the parse setup, or in converting the internal parse result to the output `BSTR', * `E_FAIL' if any of the words in the sentence cannot be found in the lexicon, * `S_FALSE' if the parse fails. (Partial results may be available for display depending on the value of the `Failures'.) Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CommandButton ParseButton Caption = "Parse" ... End Begin VB.TextBox Sentence ... End Begin RichTextLib.RichTextBox SentenceParse ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... Sentence.Text = "" SentenceParse.Text = "" ... End Sub ... Private Sub ParseButton_Click() If Not IsReadyToParse Then Exit Sub End If If Not DoSettings Then Exit Sub End If If Sentence.Text = "" Then MsgBox "Must enter sentence before parsing it!" Exit Sub End If On Error GoTo Failed SentenceParse.Text = m_patr.ParseString(Sentence.Text) Exit Sub Failed: MsgBox "Parsing sentence failed" Exit Sub End Sub C++ Example ----------- // TODO: write an example The PromoteDefaultAtoms property ================================ Interface description --------------------- [propget] HRESULT PromoteDefaultAtoms([out, retval] BOOL * pVal); [propput] HRESULT PromoteDefaultAtoms([in] BOOL newVal); C++ prototypes -------------- HRESULT get_PromoteDefaultAtoms(BOOL * pVal); HRESULT put_PromoteDefaultAtoms(BOOL newVal); Description ----------- This Boolean property controls whether default atomic feature values loaded from the lexicon are "promoted" to ordinary atomic feature values before parsing. If this property is `true', then default atomic values are changed to atomic values before parsing; otherwise, they remain marked as default atomic values. (This can affect feature unification since a conflicting default value does not cause a failure: the default value merely disappears.) The `PromoteDefaultAtoms' property corresponds to the `set promote-defaults' command in the PCPATR program. Default Value ------------- `true' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- ' TODO: write an example C++ Example ----------- // TODO: write an example The ReloadLexicon method ======================== Interface description --------------------- HRESULT ReloadLexicon(); C++ prototypes -------------- HRESULT ReloadLexicon(); Description ----------- This method clears the lexicon from memory, and reloads the current set of lexicon files. If any of the files fails to load, it is removed from the list of loaded files. Only if none of the files loads successfully is an error returned. If no lexicon files are currently loaded, the function returns immediately, reporting success. Return Value ------------ `S_OK', or an appropriate COM error code Visual Basic Example -------------------- // TODO: write an example C++ Example ----------- #include "PatrParser.h" ... PatrParser * patr; ... HRESULT hr = patr->ReloadLexicon(); if (FAILED(hr)) { ... } The SentenceFinalPunctuation property ===================================== Interface description --------------------- [propget] HRESULT SentenceFinalPunctuation([out, retval] BSTR * pVal); [propput] HRESULT SentenceFinalPunctuation([in] BSTR newVal); C++ prototypes -------------- HRESULT get_SentenceFinalPunctuation(BSTR * pVal); HRESULT put_SentenceFinalPunctuation(BSTR newVal); Description ----------- This string property specifies the set of (possibly muligraph) characters that can terminate a sentence in the `\n' fields of input AMPLE analysis files. It affects only the `DisambiguateAnaFile' method. The `SentenceFinalPunctuation' property corresponds to the `set final-punctuation' command in the PCPATR program. Default Value ------------- `. ? ! : ;' (standard English punctuation for marking clauses) Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL' * `E_OUTOFMEMORY' if allocating memory fails for either the output `BSTR' or the internal list of 8-bit character strings * `E_UNEXPECTED' in very bizarre circumstances Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox SentencePunc ... End ... Begin MSComDlg.CommonDialog AnaDlg ... End Begin MSComDlg.CommonDialog AnbDlg ... End Begin VB.Menu FileMenu Caption = "&File" ... Begin VB.Menu DisambigFileCmd Caption = "&Disambiguate File..." End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... SentencePunc.Text = m_patr.SentenceFinalPunctuation ... End Sub ... Private Sub DisambigFileCmd_Click() If Not IsReadyToParse Then Exit Sub End If If Not DoSettings Then Exit Sub End If On Error GoTo Cancelled AnaDlg.ShowOpen AnbDlg.ShowOpen On Error GoTo Failed m_patr.SentenceFinalPunctuation = SentencePunc.Text m_patr.DisambiguateAnaFile AnaDlg.FileName, AnbDlg.FileName MsgBox "Done parsing " & AnaDlg.FileName Exit Sub Failed: MsgBox "Parsing " & AnaDlg.FileName & " into " & AnbDlg.FileName & " Failed" Exit Sub Cancelled: Exit Sub End Sub C++ Example ----------- // TODO: write an example The TimeLimit property ====================== Interface description --------------------- [propget] HRESULT TimeLimit([out, retval] long * pVal); [propput] HRESULT TimeLimit([in] long newVal); C++ prototypes -------------- HRESULT get_TimeLimit(long * pVal); HRESULT put_TimeLimit(long newVal); Description ----------- This integer property specifies the maximum number of seconds that a parse is allowed to take. A value of `0' means that no time limit is imposed. NOTE: this is still experimental. The program _may_ crash some time after terminating a parse due to exceeding the time limit. (Don't say I didn't warn you!) The `TimeLimit' property corresponds to the `set limit' command in the PCPATR program. Default Value ------------- `0' (no limit) Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.TextBox TimeLimit ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... Dim limit As Integer limit = m_patr.TimeLimit If limit = 0 Then TimeLimit.Text = "(no limit)" Else TimeLimit.Text = limit End If ... End Sub ... Private Function DoSettings() As Boolean ... If TimeLimit.Text = "(no limit)" Then m_patr.TimeLimit = 0 Else m_patr.TimeLimit = TimeLimit.Text End If ... End Function C++ Example ----------- // TODO: write an example The TopDownFilter property ========================== Interface description --------------------- [propget] HRESULT TopDownFilter([out, retval] BOOL * pVal); [propput] HRESULT TopDownFilter([in] BOOL newVal); C++ prototypes -------------- HRESULT get_TopDownFilter(BOOL * pVal); HRESULT put_TopDownFilter(BOOL newVal); Description ----------- This Boolean property controls whether top-down filtering is imposed on the chart parser. If this property is `true', then top-down filtering is used; otherwise, top-down filtering is not used. Top-down filtering speeds up parsing by ruling out obviously invalid parses earlier in the process. However, it may possibly rule out valid parses as well in rare cases. This is not a problem for most grammars. The `TopDOwnFilter' property corresponds to the `set top-down-filter' command in the PCPATR program. Default Value ------------- `true' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox TopDownFilter Caption = "Enable Top Down Filtering" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... TopDownFilter.Value = m_patr.TopDownFilter ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.TopDownFilter = TopDownFilter.Value ... End Function C++ Example ----------- // TODO: write an example The TopFeatureOnly property =========================== Interface description --------------------- [propget] HRESULT TopFeatureOnly([out, retval] BOOL * pVal); [propput] HRESULT TopFeatureOnly([in] BOOL newVal); C++ prototypes -------------- HRESULT get_TopFeatureOnly(BOOL * pVal); HRESULT put_TopFeatureOnly(BOOL newVal); Description ----------- This Boolean property controls whether features structures are displayed for all nodes of a parse tree, or only for the top node. If it is `true', then only the feature structure for the top node in the parse tree is displayed. If it is `false', then the feature structures for all nodes in the parse tree are displayed. Note that while the `DisplayFeatures' property is `false', this property has no effect on the parse output. The `TopFeatureOnly' property corresponds to the `set features top' and `set features all' commands in the PCPATR program. Default Value ------------- `true' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox TopFeatureOnly Caption = "Top Feature Only" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... TopFeatureOnly.Value = m_patr.TopFeatureOnly ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.TopFeatureOnly = TopFeatureOnly.Value ... End Function C++ Example ----------- // TODO: write an example The TreeDisplay property ======================== Interface description --------------------- [propget] HRESULT TreeDisplay([out, retval] long * pVal); [propput] HRESULT TreeDisplay([in] long newVal); C++ prototypes -------------- HRESULT get_TreeDisplay(long * pVal); HRESULT put_TreeDisplay(long newVal); Description ----------- This integer property controls the format of the parse trees displayed in the parse output. It can take one of these values: `0' No parse tree is displayed. `1' The parse tree is displayed as a parenthesized list, similar to how LISP would represent a tree. `2' The parse tree is displayed as a tree using ASCII characters to draw the branches, and depending on using a fixed width font to look reasonable. `3' The parse tree is displayed as an indented list with each node on a separate line, similar to an outline. `4' The parse tree is displayed in XML format, with the feature structure for each node included with the node rather than being displayed separately. This is the least readable form for humans, but the most tractable for computer programs to parse for displaying results graphically. (This setting overrides any properties that control the display of feature structures.) The `TreeDisplay' property corresponds to the `set tree' command in the PCPATR program. Default Value ------------- `2' (full ASCII tree) Return Value ------------ `S_OK', or one of these COM error codes: * `E_POINTER' if `pVal' is `NULL', * `E_INVALIDARG' if `NewVal' is out of range (less than `0' or greater than `4') Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.Frame Frame2 ... Begin VB.OptionButton ParseTreeXML Caption = "XML" ... End Begin VB.OptionButton ParseTreeIndented Caption = "Indented" ... End Begin VB.OptionButton ParseTreeFlat Caption = "Flat" ... End Begin VB.OptionButton ParseTreeFull Caption = "Full" ... End Begin VB.OptionButton ParseDisplayOff Caption = "Off" ... End End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... Select Case m_patr.TreeDisplay Case 0 ParseDisplayOff.Value = True Case 1 ParseTreeFlat.Value = True Case 2 ParseTreeFull.Value = True Case 3 ParseTreeIndented.Value = True Case 4 ParseTreeXML.Value = True Case Else ' actually an error, but ... ParseTreeFull.Value = True m_patr.TreeDisplay = 2 End Select ... End Sub ... Private Function DoSettings() As Boolean ... If ParseDisplayOff.Value Then m_patr.TreeDisplay = 0 ElseIf ParseTreeFlat.Value Then m_patr.TreeDisplay = 1 ElseIf ParseTreeFull.Value Then m_patr.TreeDisplay = 2 ElseIf ParseTreeIndented.Value Then m_patr.TreeDisplay = 3 ElseIf ParseTreeXML.Value Then m_patr.TreeDisplay = 4 Else ' should never happen m_patr.TreeDisplay = 2 End If ... End Function C++ Example ----------- // TODO: write an example The TrimEmptyFeatures property ============================== Interface description --------------------- [propget] HRESULT TrimEmptyFeatures([out, retval] BOOL * pVal); [propput] HRESULT TrimEmptyFeatures([in] BOOL newVal); C++ prototypes -------------- HRESULT get_TrimEmptyFeatures(BOOL * pVal); HRESULT put_TrimEmptyFeatures(BOOL newVal); Description ----------- This Boolean property controls whether feature structures with null values are displayed. If it is `true', then feature structures that are null are not displayed, and if they have a label as part of a complex feature structure, their label is not displayed either. If it is `false', then null feature structures are displayed as `[]' in the parse output. Note that while the `DisplayFeatures' property is `false', this property has no effect on the parse output. The `TrimEmptyFeatures' property corresponds to the `set trim-empty-features' command in the PCPATR program. Default Value ------------- `true' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox TrimEmptyFeatures Caption = "Trim Empty Features" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... TrimEmptyFeatures.Value = m_patr.TrimEmptyFeatures ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.TrimEmptyFeatures = TrimEmptyFeatures.Value ... End Function C++ Example ----------- // TODO: write an example The Unification property ======================== Interface description --------------------- [propget] HRESULT Unification([out, retval] BOOL * pVal); [propput] HRESULT Unification([in] BOOL newVal); C++ prototypes -------------- HRESULT get_Unification(BOOL * pVal); HRESULT put_Unification(BOOL newVal); Description ----------- This Boolean property controls whether feature unification failures affect the parse process. If it is `true', then a unification failure causes a parse failure. If it is `false', then a unification failure is noted, but does not otherwise affect the parse. Note that this property does _not_ control whether feature unification is performed: it controls only whether the result of the unification affects the parse process. The `Unification' property corresponds to the `set unification' command in the PCPATR program. Default Value ------------- `true' Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox EnableUnification Caption = "Enable Unification" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... EnableUnification.Value = m_patr.Unification ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.Unification = EnableUnification.Value ... End Function C++ Example ----------- // TODO: write an example The WriteAmpleParses property ============================= Interface description --------------------- HRESULT WriteAmpleParses([out, retval] BOOL * pVal); HRESULT WriteAmpleParses([in] BOOL newVal); C++ prototypes -------------- HRESULT get_WriteAmpleParses(BOOL * pVal); HRESULT put_WriteAmpleParses(BOOL newVal); Description ----------- This Boolean property controls whether syntactic parse trees are written to the disambiguated AMPLE analysis file created by a call to the `DisambiguateAnaFile' method. Return Value ------------ `S_OK', or `E_POINTER' if `pVal' is `NULL' Visual Basic Example -------------------- Begin VB.Form Form1 ... Begin VB.CheckBox WriteParses Caption = "Write Parses of AMPLE Sentences" ... End ... End ... Dim m_patr As PatrParser Private Sub Form_Load() On Error GoTo Failed If m_patr Is Nothing Then Set m_patr = New PatrParser End If Call resetdialogbox ... Exit Sub Failed: MsgBox "Unexpected error while initializing" Exit Sub End Sub ... Private Sub resetdialogbox() ... WriteParses.Value = m_patr.WriteAmpleParses ... End Sub ... Private Function DoSettings() As Boolean ... m_patr.WriteAmpleParses = WriteParses.Value ... End Function C++ Example ----------- // TODO: write an example Error Message Strings ********************* THIS HAS YET TO BE WRITTEN. Table of Contents ***************** Introduction to the AMPLE DLL The PatrParser Interface The AmplePropertyIsFeature property The CheckCycles property The Clear method The CloseLog method The CodePage property The CommentChar property The DebuggingLevel property The DisambiguateAnaFile method The DisplayFeatures property The Failures property The FlatFeatureDisplay property The Gloss property The GrammarFile property The LexCategoryMarker property The LexFeaturesMarker property The LexGlossMarker property The LexiconFile property The LexiconFileCount property The LexRecordMarker property The LexWordMarker property The LoadAnaFile method The LoadGrammarFile method The LoadLexiconFile method The LogFile property The MaxAmbiguity property The OpenLog method The ParseFile method The ParseString method The PromoteDefaultAtoms property The ReloadLexicon method The SentenceFinalPunctuation property The TimeLimit property The TopDownFilter property The TopFeatureOnly property The TreeDisplay property The TrimEmptyFeatures property The Unification property The WriteAmpleParses property Error Message Strings