/**
* Creates a list item for adding to a list element. The list item has the
* given component.
*
* @return a <code>DocumentElement</code> representing the list item.
*/
public virtual DocumentElement createListItem(NLGElement component)
{
DocumentElement listItem = new DocumentElement(new DocumentCategory(DocumentCategory.DocumentCategoryEnum.LIST_ITEM), null);
listItem.addComponent(component);
return(listItem);
}
/**
* <p>
* Adds a new complement to the phrase element. Complements will be realised
* in the syntax after the head element of the phrase. Complements differ
* from post-modifiers in that complements are crucial to the understanding
* of a phrase whereas post-modifiers are optional.
* </p>
*
* <p>
* If the new complement being added is a <em>clause</em> or a
* <code>CoordinatedPhraseElement</code> then its clause status feature is
* set to <code>ClauseStatus.SUBORDINATE</code> and it's discourse function
* is set to <code>DiscourseFunction.OBJECT</code> by default unless an
* existing discourse function exists on the complement.
* </p>
*
* <p>
* Complements can have different functions. For example, the phrase <I>John
* gave Mary a flower</I> has two complements, one a direct object and one
* indirect. If a complement is not specified for its discourse function,
* then this is automatically set to <code>DiscourseFunction.OBJECT</code>.
* </p>
*
* @param newComplement
* the new complement as an <code>NLGElement</code>.
*/
public virtual void addComplement(NLGElement newComplement)
{
IList <NLGElement> complements = getFeatureAsElementList(InternalFeature.COMPLEMENTS);
if (complements == null)
{
complements = new List <NLGElement>();
}
// check if the new complement has a discourse function; if not, assume object
if (!newComplement.hasFeature(InternalFeature.DISCOURSE_FUNCTION))
{
newComplement.setFeature(InternalFeature.DISCOURSE_FUNCTION, DiscourseFunction.OBJECT);
}
complements.Add(newComplement);
setFeature(InternalFeature.COMPLEMENTS, complements);
if (newComplement.isA(new PhraseCategory(PhraseCategory.PhraseCategoryEnum.CLAUSE)) || newComplement is CoordinatedPhraseElement)
{
newComplement.setFeature(InternalFeature.CLAUSE_STATUS, ClauseStatus.SUBORDINATE);
if (!newComplement.hasFeature(InternalFeature.DISCOURSE_FUNCTION))
{
newComplement.setFeature(InternalFeature.DISCOURSE_FUNCTION, DiscourseFunction.OBJECT);
}
}
}
/**
* Creates a new element representing a word. If the word passed is already
* an <code>NLGElement</code> then that is returned unchanged. If a
* <code>String</code> is passed as the word then the factory will look up
* the <code>Lexicon</code> if one exists and use the details found to
* create a new <code>WordElement</code>.
*
* @param word
* the base word for the new element. This can be a
* <code>NLGElement</code>, which is returned unchanged, or a
* <code>String</code>, which is used to construct a new
* <code>WordElement</code>.
* @param category
* the <code>LexicalCategory</code> for the word.
*
* @return an <code>NLGElement</code> representing the word.
*/
public virtual NLGElement createWord(object word, LexicalCategory category)
{
NLGElement wordElement = null;
if (word is NLGElement)
{
wordElement = (NLGElement)word;
}
else if (word is string && lexicon != null)
{
// AG: change: should create a WordElement, not an
// InflectedWordElement
// wordElement = new InflectedWordElement(
// (String) word, category);
// if (this.lexicon != null) {
// doLexiconLookUp(category, (String) word, wordElement);
// }
// wordElement = lexicon.getWord((String) word, category);
wordElement = lexicon.lookupWord((string)word, category);
if (PRONOUNS.Contains((string)word))
{
setPronounFeatures(wordElement, (string)word);
}
}
return(wordElement);
}
/**
* Creates a new sentence element
*
* @param components
* an <code>NLGElement</code> that becomes the first component of
* this document element.
* @return a <code>DocumentElement</code> representing this sentence
*/
public virtual DocumentElement createSentence(NLGElement components)
{
DocumentElement sentence = new DocumentElement(new DocumentCategory(DocumentCategory.DocumentCategoryEnum.SENTENCE), null);
sentence.addComponent(components);
return(sentence);
}
/**
* Create an inflected word element. InflectedWordElement represents a word
* that already specifies the morphological and other features that it
* should exhibit in a realisation. While normally, phrases are constructed
* using <code>WordElement</code>s, and features are set on phrases, it is
* sometimes desirable to set features directly on words (for example, when
* one wants to elide a specific word, but not its parent phrase).
*
* <P>
* If the object passed is already a <code>WordElement</code>, then a new
*
* <code>InflectedWordElement<code> is returned which wraps this <code>WordElement</code>
* . If the object is a <code>String</code>, then the
* <code>WordElement</code> representing this <code>String</code> is looked
* up, and a new
* <code>InflectedWordElement<code> wrapping this is returned. If no such <code>WordElement</code>
* is found, the element returned is an <code>InflectedWordElement</code>
* with the supplied string as baseform and no base <code>WordElement</code>
* . If an <code>NLGElement</code> is passed, this is returned unchanged.
*
* @param word
* the word
* @param category
* the category
* @return an <code>InflectedWordElement</code>, or the original supplied
* object if it is an <code>NLGElement</code>.
*/
public virtual NLGElement createInflectedWord(object word, LexicalCategory category)
{
// first get the word element
NLGElement inflElement = null;
if (word is WordElement)
{
inflElement = new InflectedWordElement((WordElement)word);
}
else if (word is string)
{
NLGElement baseword = createWord((string)word, category);
if (baseword != null && baseword is WordElement)
{
inflElement = new InflectedWordElement((WordElement)baseword);
}
else
{
inflElement = new InflectedWordElement((string)word, category);
}
}
else if (word is NLGElement)
{
inflElement = (NLGElement)word;
}
return(inflElement);
}
/** promote an NLGElement so that it is at the right level to be added to a DocumentElement/
* Promotion means adding surrounding nodes at higher doc levels
* @param element
* @return
*/
private NLGElement promote(NLGElement element)
{
// check if promotion needed
if (((DocumentCategory)Category).hasSubPart(element.Category))
{
return(element);
}
// if element is not a DocumentElement, embed it in a sentence and recurse
if (!(element is DocumentElement))
{
DocumentElement sentence = new DocumentElement(new DocumentCategory(DocumentCategory.DocumentCategoryEnum.SENTENCE), null);
sentence.addElementToComponents(element);
return(promote(sentence));
}
// if element is a Sentence, promote it to a paragraph
if (element.Category.Equals(DocumentCategory.DocumentCategoryEnum.SENTENCE))
{
DocumentElement paragraph = new DocumentElement(new DocumentCategory(DocumentCategory.DocumentCategoryEnum.PARAGRAPH), null);
paragraph.addElementToComponents(element);
return(promote(paragraph));
}
// otherwise can't do anything
return(null);
}
/**
* <p>
* Add a single child component to the current list of child components. If
* there are no existing child components a new list is created.
* </p>
* <p>
* Note that there are restrictions on which child types can be added to
* which parent types. Intermediate nodes are added if necessary; eg,
* if a sentence is added to a document, the sentence will be embedded
* in a paragraph before it is added
* See <code>
* DocumentCategory</code> for further information.
* </p>
*
* @param element
* the <code>NLGElement</code> to be added. If this is
* <code>NULL</code> the method does nothing.
*/
public virtual void addComponent(NLGElement element)
{
if (element != null)
{
ElementCategory thisCategory = Category;
ElementCategory category = element.Category;
if (category != null && thisCategory is DocumentCategory)
{
if (((DocumentCategory)thisCategory).hasSubPart(category))
{
addElementToComponents(element);
}
else
{
NLGElement promotedElement = promote(element);
if (promotedElement != null)
{
addElementToComponents(promotedElement);
}
else // error condition - add original element so something is visible
{
addElementToComponents(element);
}
}
}
else
{
addElementToComponents(element);
}
}
}
/**
* Creates a new section element with the given title and adds the given
* component.
*
* @param component
* an <code>NLGElement</code> that becomes the first component of
* this document element.
* @return a <code>DocumentElement</code> representing the section.
* @author Rodrigo de Oliveira - Data2Text Ltd
*/
public virtual DocumentElement createEnumeratedList(NLGElement component)
{
DocumentElement list = new DocumentElement(new DocumentCategory(DocumentCategory.DocumentCategoryEnum.ENUMERATED_LIST), null);
list.addComponent(component);
return(list);
}
/**
* A helper method to set the head feature of the phrase.
*
* @param phraseElement
* the phrase element.
* @param headElement
* the head element.
*/
private void setPhraseHead(PhraseElement phraseElement, NLGElement headElement)
{
if (headElement != null)
{
phraseElement.setHead(headElement);
headElement.Parent = phraseElement;
}
}
/** add an element to a components list
* @param element
*/
private void addElementToComponents(NLGElement element)
{
IList <NLGElement> components = Components;
components.Add(element);
element.Parent = this;
Components = components;
}
/**
* Creates an adverb phrase wrapping the given adverb.
*
* @param adverb
* the adverb for this phrase.
* @return a <code>AdvPhraseSpec</code> representing this phrase.
*/
public virtual AdvPhraseSpec createAdverbPhrase(string adverb)
{
AdvPhraseSpec phraseElement = new AdvPhraseSpec(this);
NLGElement adverbElement = createNLGElement(adverb, new LexicalCategory(LexicalCategory.LexicalCategoryEnum.ADVERB));
setPhraseHead(phraseElement, adverbElement);
return(phraseElement);
}
/**
* Adds the given component to the list element.
*
* @param newComponent
* the <code>NLGElement</code> component to be added.
*/
public virtual void addComponent(NLGElement newComponent)
{
IList<NLGElement> components = getFeatureAsElementList(InternalFeature.COMPONENTS);
if (components == null)
{
components = new List<NLGElement>();
}
setFeature(InternalFeature.COMPONENTS, components);
components.Add(newComponent);
}
/**
* Creates a new paragraph element and adds the given component
*
* @param component
* an <code>NLGElement</code> that becomes the first component of
* this document element.
* @return a <code>DocumentElement</code> representing this paragraph
*/
public virtual DocumentElement createParagraph(NLGElement component)
{
DocumentElement paragraph = new DocumentElement(new DocumentCategory(DocumentCategory.DocumentCategoryEnum.PARAGRAPH), null);
if (component != null)
{
paragraph.addComponent(component);
}
return(paragraph);
}
/**
* Creates a new document element with the given title and adds the given
* component.
*
* @param title
* the title for this element.
* @param component
* an <code>NLGElement</code> that becomes the first component of
* this document element.
* @return a <code>DocumentElement</code>
*/
public virtual DocumentElement createDocument(string title, NLGElement component)
{
DocumentElement element = new DocumentElement(new DocumentCategory(DocumentCategory.DocumentCategoryEnum.DOCUMENT), title);
if (component != null)
{
element.addComponent(component);
}
return(element);
}
/**
* Creates an adjective phrase wrapping the given adjective.
*
* @param adjective
* the main adjective for this phrase.
* @return a <code>AdjPhraseSpec</code> representing this phrase.
*/
public virtual AdjPhraseSpec createAdjectivePhrase(object adjective)
{
AdjPhraseSpec phraseElement = new AdjPhraseSpec(this);
NLGElement adjectiveElement = createNLGElement(adjective, new LexicalCategory(LexicalCategory.LexicalCategoryEnum.ADJECTIVE));
setPhraseHead(phraseElement, adjectiveElement);
return(phraseElement);
}
/**
* Creates a new section element with the given title and adds the given
* component.
*
* @param title
* the title for this element.
* @param component
* an <code>NLGElement</code> that becomes the first component of
* this document element.
* @return a <code>DocumentElement</code> representing the section.
*/
public virtual DocumentElement createSection(string title, NLGElement component)
{
DocumentElement section = new DocumentElement(new DocumentCategory(DocumentCategory.DocumentCategoryEnum.SECTION), title);
if (component != null)
{
section.addComponent(component);
}
return(section);
}
/**
* Adds a new front modifier to the phrase element.
*
* @param newFrontModifier
* the new front modifier as an <code>NLGElement</code>.
*/
public virtual void addFrontModifier(NLGElement newFrontModifier)
{
IList <NLGElement> frontModifiers = getFeatureAsElementList(InternalFeature.FRONT_MODIFIERS);
if (frontModifiers == null)
{
frontModifiers = new List <NLGElement>();
}
frontModifiers.Add(newFrontModifier);
setFeature(InternalFeature.FRONT_MODIFIERS, frontModifiers);
}
/**
* Adds a new post-modifier to the phrase element. Post-modifiers will be
* realised in the syntax after the coordinates.
*
* @param newPostModifier
* the new post-modifier as an <code>NLGElement</code>.
*/
public virtual void addPostModifier(NLGElement newPostModifier)
{
IList <NLGElement> postModifiers = getFeatureAsElementList(InternalFeature.POSTMODIFIERS);
if (postModifiers == null)
{
postModifiers = new List <NLGElement>();
}
postModifiers.Add(newPostModifier);
setFeature(InternalFeature.POSTMODIFIERS, postModifiers);
}
/**
* An NLG element is equal to some object if the object is an NLGElement,
* they have the same category and the same features.
*/
public override bool Equals(object o)
{
bool eq = false;
if (o is NLGElement)
{
NLGElement element = (NLGElement)o;
eq = category == element.category && features.Equals(element.features);
}
return(eq);
}
/**
* Adds a new post-modifier to the phrase element. Post-modifiers will be
* realised in the syntax after the complements.
*
* @param newPostModifier
* the new post-modifier as an <code>NLGElement</code>.
*/
public virtual void addPostModifier(NLGElement newPostModifier)
{
IList <NLGElement> postModifiers = getFeatureAsElementList(InternalFeature.POSTMODIFIERS);
if (postModifiers == null)
{
postModifiers = new List <NLGElement>();
}
newPostModifier.setFeature(InternalFeature.DISCOURSE_FUNCTION, DiscourseFunction.POST_MODIFIER);
postModifiers.Add(newPostModifier);
setFeature(InternalFeature.POSTMODIFIERS, postModifiers);
}
/**
* Removes the specified component from the list of child components.
*
* @param textComponent
* the component to be removed.
* @return <code>true</code> if the element was removed, or
* <code>false</code> if the element did not exist, there is no
* component list or the the given component to remove is
* <code>NULL</code>.
*/
public virtual bool removeComponent(NLGElement textComponent)
{
bool removed = false;
if (textComponent != null)
{
IList <NLGElement> components = Components;
if (components != null)
{
removed = components.Remove(textComponent);
}
}
return(removed);
}
/**
* Creates a preposition phrase with the given preposition and complement.
* An <code>NLGElement</code> representing the preposition is added as the
* head feature of this phrase while the complement is added as a normal
* phrase complement.
*
* @param preposition
* the preposition to be used.
* @param complement
* the complement of the phrase.
* @return a <code>PPPhraseSpec</code> representing this phrase.
*/
public virtual PPPhraseSpec createPrepositionPhrase(object preposition, object complement)
{
PPPhraseSpec phraseElement = new PPPhraseSpec(this);
NLGElement prepositionalElement = createNLGElement(preposition, new LexicalCategory(LexicalCategory.LexicalCategoryEnum.PREPOSITION));
setPhraseHead(phraseElement, prepositionalElement);
if (complement != null)
{
setComplement(phraseElement, complement);
}
return(phraseElement);
}
/**
* Retrieves the value of the feature as a <code>NLGElement</code>. If the
* value is a string then it is wrapped in a <code>StringElement</code>. If
* the feature does not exist or is of any other type then <code>null</code>
* is returned.
*
* @param featureName
* the name of the feature.
* @return the <code>NLGElement</code>.
*/
public virtual NLGElement getFeatureAsElement(string featureName)
{
object value = getFeature(featureName);
NLGElement elementValue = null;
if (value is NLGElement)
{
elementValue = (NLGElement)value;
}
else if (value is string)
{
elementValue = new StringElement((string)value);
}
return(elementValue);
}
/**
* Creates a noun phrase with the given specifier and subject.
*
* @param specifier
* the specifier or determiner for the noun phrase.
* @param noun
* the subject of the phrase.
* @return a <code>NPPhraseSpec</code> representing this phrase.
*/
public virtual NPPhraseSpec createNounPhrase(object specifier, object noun)
{
if (noun is NPPhraseSpec)
{
return((NPPhraseSpec)noun);
}
NPPhraseSpec phraseElement = new NPPhraseSpec(this);
NLGElement nounElement = createNLGElement(noun, new LexicalCategory(LexicalCategory.LexicalCategoryEnum.NOUN));
setPhraseHead(phraseElement, nounElement);
if (specifier != null)
{
phraseElement.setSpecifier(specifier);
}
return(phraseElement);
}
/**
* A helper method to look up the lexicon for the given word.
*
* @param category
* the <code>LexicalCategory</code> of the word.
* @param word
* the base form of the word.
* @param wordElement
* the created element representing the word.
*/
private void doLexiconLookUp(LexicalCategory category, string word, NLGElement wordElement)
{
WordElement baseWord = null;
if (category.GetLexicalCategory() == LexicalCategory.LexicalCategoryEnum.NOUN && lexicon.hasWord(word, new LexicalCategory(LexicalCategory.LexicalCategoryEnum.PRONOUN)))
{
baseWord = lexicon.lookupWord(word, new LexicalCategory(LexicalCategory.LexicalCategoryEnum.PRONOUN));
if (baseWord != null)
{
wordElement.setFeature(InternalFeature.BASE_WORD, baseWord);
wordElement.Category = new LexicalCategory(LexicalCategory.LexicalCategoryEnum.PRONOUN);
if (!PRONOUNS.Contains(word))
{
wordElement.setFeature(InternalFeature.NON_MORPH, true);
}
}
}
else
{
baseWord = lexicon.lookupWord(word, category);
wordElement.setFeature(InternalFeature.BASE_WORD, baseWord);
}
}
/**
* A helper method for setting the complement of a phrase.
*
* @param phraseElement
* the created element representing this phrase.
* @param complement
* the complement to be added.
*/
private void setComplement(PhraseElement phraseElement, object complement)
{
NLGElement complementElement = createNLGElement(complement);
phraseElement.addComplement(complementElement);
}
/**
* A helper method to set the features on newly created pronoun words.
*
* @param wordElement
* the created element representing the pronoun.
* @param word
* the base word for the pronoun.
*/
private void setPronounFeatures(NLGElement wordElement, string word)
{
wordElement.Category = new LexicalCategory(LexicalCategory.LexicalCategoryEnum.PRONOUN);
if (FIRST_PRONOUNS.Contains(word))
{
wordElement.setFeature(Feature.PERSON, Person.FIRST);
}
else if (SECOND_PRONOUNS.Contains(word))
{
wordElement.setFeature(Feature.PERSON, Person.SECOND);
if ("yourself".Equals(word, StringComparison.OrdinalIgnoreCase))
{ //$NON-NLS-1$
wordElement.Plural = false;
}
else if ("yourselves".Equals(word, StringComparison.OrdinalIgnoreCase))
{ //$NON-NLS-1$
wordElement.Plural = true;
}
else
{
wordElement.setFeature(Feature.NUMBER, NumberAgreement.BOTH);
}
}
else
{
wordElement.setFeature(Feature.PERSON, Person.THIRD);
}
if (REFLEXIVE_PRONOUNS.Contains(word))
{
wordElement.setFeature(LexicalFeature.REFLEXIVE, true);
}
else
{
wordElement.setFeature(LexicalFeature.REFLEXIVE, false);
}
if (MASCULINE_PRONOUNS.Contains(word))
{
wordElement.setFeature(LexicalFeature.GENDER, Gender.MASCULINE);
}
else if (FEMININE_PRONOUNS.Contains(word))
{
wordElement.setFeature(LexicalFeature.GENDER, Gender.FEMININE);
}
else
{
wordElement.setFeature(LexicalFeature.GENDER, Gender.NEUTER);
}
if (POSSESSIVE_PRONOUNS.Contains(word))
{
wordElement.setFeature(Feature.POSSESSIVE, true);
}
else
{
wordElement.setFeature(Feature.POSSESSIVE, false);
}
if (PLURAL_PRONOUNS.Contains(word) && !SECOND_PRONOUNS.Contains(word))
{
wordElement.Plural = true;
}
else if (!EITHER_NUMBER_PRONOUNS.Contains(word))
{
wordElement.Plural = false;
}
if (EXPLETIVE_PRONOUNS.Contains(word))
{
wordElement.setFeature(InternalFeature.NON_MORPH, true);
wordElement.setFeature(LexicalFeature.EXPLETIVE_SUBJECT, true);
}
wordElement.setFeature(Feature.IS_CAPITALIZED, false); //added by GJdV, some default value
}
/**
* Creates a new list element containing the given component.
*
* @param newComponent
* the initial component for this list element.
*/
public ListElement(NLGElement newComponent) : this()
{
addComponent(newComponent);
}
/**
* Set the premodifier for this phrase. This resets all previous
* premodifiers to <code>null</code> and replaces them with the given
* string.
*
* @param newPreModifier
* the premodifier
*/
public virtual void setPreModifier(NLGElement value)
{
setFeature(InternalFeature.PREMODIFIERS, null);
addPreModifier(value);
}
/** * Realises the given element. This call is usually recursive as the call * processes the child elements of the given element. * * @param element * the <code>NLGElement</code> to be realised. * @return the <code>NLGElement</code> representing the realised state. This * may be the initial element in a changed form or be a completely * new element. */ public abstract NLGElement realise(NLGElement element);
