THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

About this page

This page documents the interface that the Ubiquity parser uses to talk to the rest of the program. It may be of interest if you want to

1. Replace the parser with a new parser using a different algorithm
2. Take the Ubiquity parser for use in another program.

If you're looking for documentation on the language-specific parser plugin API, then you want Localizing Ubiquity to Your Language. If you're looking for documentation on the implementation of the current parser, you want the current parser documentation.

MakeParserForLanguage

The parser is wrapped in a JS object called NLParser. (This object just acts as a namespace.)

It exposes just one top-level function, which is a factory called makeParserForLanguage:

NLParser.makeParserForLanguage: function(languageCode, verbList, nounList,
                                         ContextUtils, suggestionMemory)

This returns a Parser object. The meanings of the arguments are:

• languageCode: a two-letter string identifying a langauge, like "en" or "jp". makeParserForLanguage returns a parser object appropriate for the language specified.
• verbList: An array of all the verb objects that exist in the command set.
• nounList: An array of all the nounType objects that exist in the command set.
• contextUtils: Optional. An object that the parser can use to grab the user's current selection. If not provided, the parser imports and uses the default ContextUtils object from ubiquity/modules/contxtutils.js. This is almost always what you want; the opportunity to override it is provided for unit-testing purposes.
• suggestionMemory: Optional. An object the parser can use to keep track of the suggestions the user has often chosen in the past. If not provided, the parser imports and uses the default SuggestionMemory object from ubiquity/modules/suggestion_memory.js. This is almost always what you want; the opportunity to override is provided for unit-testing purposes.

Methods of the Parser object

updateSuggestionList(query, context, asyncSuggestionCb)

Feeds the user's input into the parser. query is a string containing the raw user input. context is an object encapsulating the user's selection (see ContextUtils). asyncSuggestionCb is an optional function to be called back by nountypes doing asynchronous suggestions (TODO: document asyncSuggestionCb better.)

The effect of calling this method is to make the parser update its internal list of suggestions. It doesn't return anything. To get the suggestions back from the parser, call getSuggestionList().

getSuggestionList()

Returns an array containing a list of suggestions, ordered best to worst, that the parser has generated based on the most recent user input (i.e. the input given in the last call to updateSuggestionList().) Each item in the array is a ParsedSentence object.

strengthenMemory(query, chosenSuggestion)

Strengthens the association between a certain input and a certain suggestion. That is, if the user enters query, the query is given to the parser, the parser produces a list of suggestions, and the user chooses chosenSuggestion, then the UI code should then call parser.strengthenMemory(query, chosenSuggestion). The effect is to give a clue to the parser that the next time the user enters a string like query, then chosenSuggestion should be ranked higher in the suggestion list. This enables the parser to improve its suggestions over time.

getSentence(index)

Returns the ParsedSentence at the given index in the suggestion list.

getNumSuggestions()

Returns the number of suggestions in the suggestion list.

setCommandList(commandList)

Updates the parser's internal list of all available verb names in the command set. commandList is an array of verb objects. If you know what the whole verb list is going to be when you instantiate the parser, you can just pass it into makeParserForLanguage, and never bother with this function; otherwise, you can pass an empty array into makeParserForLanguage and then later on call this function.

setNounList(nounList)

Like setCommandList, but updates the parser's internal list of all available noun types. nounList is an array of nounType objects.

getSelectionObject()

(Why is this exposed?) Returns an object representing the user's current selection. The object has two attributes:

* .text a string containing the text selection only (i.e. no HTML tags)
* .html a string containing the html selection (i.e. text with HTML tags)

The Verb, Noun, and ParsedSentence object interfaces

TODO