simplenlg.framework.NLGFactory Maven / Gradle / Ivy
Show all versions of SimpleNLG Show documentation
/*
* The contents of this file are subject to the Mozilla Public License
* Version 2.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* https://www.mozilla.org/en-US/MPL/
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
* License for the specific language governing rights and limitations
* under the License.
*
* The Original Code is "Simplenlg".
*
* The Initial Developer of the Original Code is Ehud Reiter, Albert Gatt and Dave Westwater.
* Portions created by Ehud Reiter, Albert Gatt and Dave Westwater are Copyright (C) 2010-11 The University of Aberdeen. All Rights Reserved.
*
* Contributor(s): Ehud Reiter, Albert Gatt, Dave Westwater, Roman Kutlak, Margaret Mitchell, and Saad Mahamood.
*/
package simplenlg.framework;
import java.util.Arrays;
import java.util.List;
import simplenlg.features.*;
import simplenlg.lexicon.Lexicon;
import simplenlg.phrasespec.*;
/**
*
* This class contains methods for creating syntactic phrases. These methods
* should be used instead of directly invoking new on SPhraseSpec, etc.
*
* The phrase factory should be linked to s lexicon if possible (although it
* will work without one)
*
*
* @author D. Westwater, University of Aberdeen.
* @version 4.0
*/
public class NLGFactory {
/***
* CODING COMMENTS The original version of phraseFactory created a crude
* realisation of the phrase in the BASE_FORM feature. This was just for
* debugging purposes (note BASE_FORM on a WordElement is meaningful), I've
* zapped this as it was makig things too complex
*
* This version of phraseFactory replicates WordElements (instead of reusing
* them). I think this is because elemente are linked to their parent
* phrases, via the parent data member. May be good to check if this is
* actually necessary
*
* The explicit list of pronouns below should be replaced by a reference to
* the lexicon
*
* Things to sort out at some point...
*
*/
/**
* The lexicon to be used with this factory.
*/
private Lexicon lexicon;
/**
* The list of English pronouns.
*/
@SuppressWarnings("nls")
private static final List PRONOUNS = Arrays.asList("I",
"you",
"he",
"she",
"it",
"me",
"you",
"him",
"her",
"it",
"myself",
"yourself",
"himself",
"herself",
"itself",
"mine",
"yours",
"his",
"hers",
"its",
"we",
"you",
"they",
"they",
"they",
"us",
"you",
"them",
"them",
"them",
"ourselves",
"yourselves",
"themselves",
"themselves",
"themselves",
"ours",
"yours",
"theirs",
"theirs",
"theirs",
"there");
/**
* The list of first-person English pronouns.
*/
@SuppressWarnings("nls")
private static final List FIRST_PRONOUNS = Arrays.asList("I",
"me",
"myself",
"we",
"us",
"ourselves",
"mine",
"my",
"ours",
"our");
/**
* The list of second person English pronouns.
*/
@SuppressWarnings("nls")
private static final List SECOND_PRONOUNS = Arrays.asList("you", "yourself", "yourselves", "yours", "your");
/**
* The list of reflexive English pronouns.
*/
@SuppressWarnings("nls")
private static final List REFLEXIVE_PRONOUNS = Arrays.asList("myself",
"yourself",
"himself",
"herself",
"itself",
"ourselves",
"yourselves",
"themselves");
/**
* The list of masculine English pronouns.
*/
@SuppressWarnings("nls")
private static final List MASCULINE_PRONOUNS = Arrays.asList("he", "him", "himself", "his");
/**
* The list of feminine English pronouns.
*/
@SuppressWarnings("nls")
private static final List FEMININE_PRONOUNS = Arrays.asList("she", "her", "herself", "hers");
/**
* The list of possessive English pronouns.
*/
@SuppressWarnings("nls")
private static final List POSSESSIVE_PRONOUNS = Arrays.asList("mine",
"ours",
"yours",
"his",
"hers",
"its",
"theirs",
"my",
"our",
"your",
"her",
"their");
/**
* The list of plural English pronouns.
*/
@SuppressWarnings("nls")
private static final List PLURAL_PRONOUNS = Arrays.asList("we",
"us",
"ourselves",
"ours",
"our",
"they",
"them",
"theirs",
"their");
/**
* The list of English pronouns that can be singular or plural.
*/
@SuppressWarnings("nls")
private static final List EITHER_NUMBER_PRONOUNS = Arrays.asList("there");
/**
* The list of expletive English pronouns.
*/
@SuppressWarnings("nls")
private static final List EXPLETIVE_PRONOUNS = Arrays.asList("there");
/**
* regex for determining if a string is a single word or not
**/
private static final String WORD_REGEX = "\\w*";
/**
* Creates a new phrase factory with no associated lexicon.
*/
public NLGFactory() {
this(null);
}
/**
* Creates a new phrase factory with the associated lexicon.
*
* @param newLexicon the Lexicon to be used with this factory.
*/
public NLGFactory(Lexicon newLexicon) {
setLexicon(newLexicon);
}
/**
* Sets the lexicon to be used by this factory. Passing a parameter of
* null will remove any existing lexicon from the factory.
*
* @param newLexicon the new Lexicon to be used.
*/
public void setLexicon(Lexicon newLexicon) {
this.lexicon = newLexicon;
}
/**
* Creates a new element representing a word. If the word passed is already
* an NLGElement then that is returned unchanged. If a
* String is passed as the word then the factory will look up
* the Lexicon if one exists and use the details found to
* create a new WordElement.
*
* @param word the base word for the new element. This can be a
* NLGElement, which is returned unchanged, or a
* String, which is used to construct a new
* WordElement.
* @param category the LexicalCategory for the word.
* @return an NLGElement representing the word.
*/
public NLGElement createWord(Object word, LexicalCategory category) {
NLGElement wordElement = null;
if(word instanceof NLGElement) {
wordElement = (NLGElement) word;
} else if(word instanceof String && this.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(word)) {
setPronounFeatures(wordElement, (String) word);
}
}
return wordElement;
}
/**
* 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 WordElements, 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).
*
*
* If the object passed is already a WordElement, then a new
*
* InflectedWordElement is returned which wraps this WordElement
* . If the object is a String, then the
* WordElement representing this String is looked
* up, and a new
* InflectedWordElement wrapping this is returned. If no such WordElement
* is found, the element returned is an InflectedWordElement
* with the supplied string as baseform and no base WordElement
* . If an NLGElement is passed, this is returned unchanged.
*
* @param word the word
* @param category the category
* @return an InflectedWordElement, or the original supplied
* object if it is an NLGElement.
*/
public NLGElement createInflectedWord(Object word, LexicalCategory category) {
// first get the word element
NLGElement inflElement = null;
if(word instanceof WordElement) {
inflElement = new InflectedWordElement((WordElement) word);
} else if(word instanceof String) {
NLGElement baseword = createWord((String) word, category);
if(baseword != null && baseword instanceof WordElement) {
inflElement = new InflectedWordElement((WordElement) baseword);
} else {
inflElement = new InflectedWordElement((String) word, category);
}
} else if(word instanceof NLGElement) {
inflElement = (NLGElement) word;
}
return inflElement;
}
/**
* 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.setCategory(LexicalCategory.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".equalsIgnoreCase(word)) { //$NON-NLS-1$
wordElement.setPlural(false);
} else if("yourselves".equalsIgnoreCase(word)) { //$NON-NLS-1$
wordElement.setPlural(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.setPlural(true);
} else if(!EITHER_NUMBER_PRONOUNS.contains(word)) {
wordElement.setPlural(false);
}
if(EXPLETIVE_PRONOUNS.contains(word)) {
wordElement.setFeature(InternalFeature.NON_MORPH, true);
wordElement.setFeature(LexicalFeature.EXPLETIVE_SUBJECT, true);
}
}
/**
* A helper method to look up the lexicon for the given word.
*
* @param category the LexicalCategory of the word.
* @param word the base form of the word.
* @param wordElement the created element representing the word.
*/
@SuppressWarnings("unused")
private void doLexiconLookUp(LexicalCategory category, String word, NLGElement wordElement) {
WordElement baseWord = null;
if(LexicalCategory.NOUN.equals(category) && this.lexicon.hasWord(word, LexicalCategory.PRONOUN)) {
baseWord = this.lexicon.lookupWord(word, LexicalCategory.PRONOUN);
if(baseWord != null) {
wordElement.setFeature(InternalFeature.BASE_WORD, baseWord);
wordElement.setCategory(LexicalCategory.PRONOUN);
if(!PRONOUNS.contains(word)) {
wordElement.setFeature(InternalFeature.NON_MORPH, true);
}
}
} else {
baseWord = this.lexicon.lookupWord(word, category);
wordElement.setFeature(InternalFeature.BASE_WORD, baseWord);
}
}
/**
* Creates a blank preposition phrase with no preposition or complements.
*
* @return a PPPhraseSpec representing this phrase.
*/
public PPPhraseSpec createPrepositionPhrase() {
return createPrepositionPhrase(null, null);
}
/**
* Creates a preposition phrase with the given preposition.
*
* @param preposition the preposition to be used.
* @return a PPPhraseSpec representing this phrase.
*/
public PPPhraseSpec createPrepositionPhrase(Object preposition) {
return createPrepositionPhrase(preposition, null);
}
/**
* Creates a preposition phrase with the given preposition and complement.
* An NLGElement 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 PPPhraseSpec representing this phrase.
*/
public PPPhraseSpec createPrepositionPhrase(Object preposition, Object complement) {
PPPhraseSpec phraseElement = new PPPhraseSpec(this);
NLGElement prepositionalElement = createNLGElement(preposition, LexicalCategory.PREPOSITION);
setPhraseHead(phraseElement, prepositionalElement);
if(complement != null) {
setComplement(phraseElement, complement);
}
return phraseElement;
}
/**
* 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);
}
/**
* this method creates an NLGElement from an object If object is null,
* return null If the object is already an NLGElement, it is returned
* unchanged Exception: if it is an InflectedWordElement, return underlying
* WordElement If it is a String which matches a lexicon entry or pronoun,
* the relevant WordElement is returned If it is a different String, a
* wordElement is created if the string is a single word Otherwise a
* StringElement is returned Otherwise throw an exception
*
* @param element - object to look up
* @param category - default lexical category of object
* @return NLGelement
*/
public NLGElement createNLGElement(Object element, LexicalCategory category) {
if(element == null)
return null;
// InflectedWordElement - return underlying word
else if(element instanceof InflectedWordElement)
return ((InflectedWordElement) element).getBaseWord();
// StringElement - look up in lexicon if it is a word
// otherwise return element
else if(element instanceof StringElement) {
if(stringIsWord(((StringElement) element).getRealisation(), category))
return createWord(((StringElement) element).getRealisation(), category);
else
return (StringElement) element;
}
// other NLGElement - return element
else if(element instanceof NLGElement)
return (NLGElement) element;
// String - look up in lexicon if a word, otherwise return StringElement
else if(element instanceof String) {
if(stringIsWord((String) element, category))
return createWord(element, category);
else
return new StringElement((String) element);
}
throw new IllegalArgumentException(element.toString() + " is not a valid type");
}
/**
* return true if string is a word
*/
private boolean stringIsWord(String string, LexicalCategory category) {
return lexicon != null && (lexicon.hasWord(string, category) || PRONOUNS.contains(string) || (string.matches(
WORD_REGEX)));
}
/**
* create an NLGElement from the element, no default lexical category
*
* @return NLGelement
*/
public NLGElement createNLGElement(Object element) {
return createNLGElement(element, LexicalCategory.ANY);
}
/**
* Creates a blank noun phrase with no subject or specifier.
*
* @return a NPPhraseSpec representing this phrase.
*/
public NPPhraseSpec createNounPhrase() {
return createNounPhrase(null, null);
}
/**
* Creates a noun phrase with the given subject but no specifier.
*
* @param noun the subject of the phrase.
* @return a NPPhraseSpec representing this phrase.
*/
public NPPhraseSpec createNounPhrase(Object noun) {
if(noun instanceof NPPhraseSpec)
return (NPPhraseSpec) noun;
else
return createNounPhrase(null, noun);
}
/**
* 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 NPPhraseSpec representing this phrase.
*/
public NPPhraseSpec createNounPhrase(Object specifier, Object noun) {
if(noun instanceof NPPhraseSpec)
return (NPPhraseSpec) noun;
NPPhraseSpec phraseElement = new NPPhraseSpec(this);
NLGElement nounElement = createNLGElement(noun, LexicalCategory.NOUN);
setPhraseHead(phraseElement, nounElement);
if(specifier != null)
phraseElement.setSpecifier(specifier);
return phraseElement;
}
/**
* 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.setParent(phraseElement);
}
}
/**
* Creates a blank adjective phrase with no base adjective set.
*
* @return a AdjPhraseSpec representing this phrase.
*/
public AdjPhraseSpec createAdjectivePhrase() {
return createAdjectivePhrase(null);
}
/**
* Creates an adjective phrase wrapping the given adjective.
*
* @param adjective the main adjective for this phrase.
* @return a AdjPhraseSpec representing this phrase.
*/
public AdjPhraseSpec createAdjectivePhrase(Object adjective) {
AdjPhraseSpec phraseElement = new AdjPhraseSpec(this);
NLGElement adjectiveElement = createNLGElement(adjective, LexicalCategory.ADJECTIVE);
setPhraseHead(phraseElement, adjectiveElement);
return phraseElement;
}
/**
* Creates a blank verb phrase with no main verb.
*
* @return a VPPhraseSpec representing this phrase.
*/
public VPPhraseSpec createVerbPhrase() {
return createVerbPhrase(null);
}
/**
* Creates a verb phrase wrapping the main verb given. If a
* String is passed in then some parsing is done to see if the
* verb contains a particle, for example fall down. The first word
* is taken to be the verb while all other words are assumed to form the
* particle.
*
* @param verb the verb to be wrapped.
* @return a VPPhraseSpec representing this phrase.
*/
public VPPhraseSpec createVerbPhrase(Object verb) {
VPPhraseSpec phraseElement = new VPPhraseSpec(this);
phraseElement.setVerb(verb);
setPhraseHead(phraseElement, phraseElement.getVerb());
return phraseElement;
}
/**
* Creates a blank adverb phrase that has no adverb.
*
* @return a AdvPhraseSpec representing this phrase.
*/
public AdvPhraseSpec createAdverbPhrase() {
return createAdverbPhrase(null);
}
/**
* Creates an adverb phrase wrapping the given adverb.
*
* @param adverb the adverb for this phrase.
* @return a AdvPhraseSpec representing this phrase.
*/
public AdvPhraseSpec createAdverbPhrase(String adverb) {
AdvPhraseSpec phraseElement = new AdvPhraseSpec(this);
NLGElement adverbElement = createNLGElement(adverb, LexicalCategory.ADVERB);
setPhraseHead(phraseElement, adverbElement);
return phraseElement;
}
/**
* Creates a blank clause with no subject, verb or objects.
*
* @return a SPhraseSpec representing this phrase.
*/
public SPhraseSpec createClause() {
return createClause(null, null, null);
}
/**
* Creates a clause with the given subject and verb but no objects.
*
* @param subject the subject for the clause as a NLGElement or
* String. This forms a noun phrase.
* @param verb the verb for the clause as a NLGElement or
* String. This forms a verb phrase.
* @return a SPhraseSpec representing this phrase.
*/
public SPhraseSpec createClause(Object subject, Object verb) {
return createClause(subject, verb, null);
}
/**
* Creates a clause with the given subject, verb or verb phrase and direct
* object but no indirect object.
*
* @param subject the subject for the clause as a NLGElement or
* String. This forms a noun phrase.
* @param verb the verb for the clause as a NLGElement or
* String. This forms a verb phrase.
* @param directObject the direct object for the clause as a NLGElement
* or String. This forms a complement for the
* clause.
* @return a SPhraseSpec representing this phrase.
*/
public SPhraseSpec createClause(Object subject, Object verb, Object directObject) {
SPhraseSpec phraseElement = new SPhraseSpec(this);
if(verb != null) {
// AG: fix here: check if "verb" is a VPPhraseSpec or a Verb
if(verb instanceof PhraseElement) {
phraseElement.setVerbPhrase((PhraseElement) verb);
} else {
phraseElement.setVerb(verb);
}
}
if(subject != null)
phraseElement.setSubject(subject);
if(directObject != null) {
phraseElement.setObject(directObject);
}
return phraseElement;
}
/* *//**
* A helper method to set the verb phrase for a clause.
*
* @param baseForm
* the base form of the clause.
* @param verbPhrase
* the verb phrase to be used in the clause.
* @param phraseElement
* the current representation of the clause.
*/
/*
* private void setVerbPhrase(StringBuffer baseForm, NLGElement verbPhrase,
* PhraseElement phraseElement) { if (baseForm.length() > 0) {
* baseForm.append(' '); }
* baseForm.append(verbPhrase.getFeatureAsString(Feature.BASE_FORM));
* phraseElement.setFeature(Feature.VERB_PHRASE, verbPhrase);
* verbPhrase.setParent(phraseElement);
* verbPhrase.setFeature(Feature.DISCOURSE_FUNCTION,
* DiscourseFunction.VERB_PHRASE); if
* (phraseElement.hasFeature(Feature.GENDER)) {
* verbPhrase.setFeature(Feature.GENDER, phraseElement
* .getFeature(Feature.GENDER)); } if
* (phraseElement.hasFeature(Feature.NUMBER)) {
* verbPhrase.setFeature(Feature.NUMBER, phraseElement
* .getFeature(Feature.NUMBER)); } if
* (phraseElement.hasFeature(Feature.PERSON)) {
* verbPhrase.setFeature(Feature.PERSON, phraseElement
* .getFeature(Feature.PERSON)); } }
*//**
* A helper method to add the direct object to the clause.
*
* @param baseForm
* the base form for the clause.
* @param directObject
* the direct object to be added.
* @param phraseElement
* the current representation of this clause.
* @param function
* the discourse function for this object.
*/
/*
* private void setObject(StringBuffer baseForm, Object object,
* PhraseElement phraseElement, DiscourseFunction function) { if
* (baseForm.length() > 0) { baseForm.append(' '); } if (object instanceof
* NLGElement) { phraseElement.addComplement((NLGElement) object);
* baseForm.append(((NLGElement) object)
* .getFeatureAsString(Feature.BASE_FORM));
*
* ((NLGElement) object).setFeature(Feature.DISCOURSE_FUNCTION, function);
*
* if (((NLGElement) object).hasFeature(Feature.NUMBER)) {
* phraseElement.setFeature(Feature.NUMBER, ((NLGElement) object)
* .getFeature(Feature.NUMBER)); } } else if (object instanceof String) {
* NLGElement complementElement = createNounPhrase(object);
* phraseElement.addComplement(complementElement);
* complementElement.setFeature(Feature.DISCOURSE_FUNCTION, function);
* baseForm.append((String) object); } }
*/
/* *//**
* A helper method that sets the subjects on a clause.
*
* @param phraseElement
* the element representing the clause.
* @param subjectPhrase
* the subject phrase for the clause.
* @param baseForm
* the base form for the clause.
*/
/*
* private void setPhraseSubjects(PhraseElement phraseElement, NLGElement
* subjectPhrase, StringBuffer baseForm) {
* subjectPhrase.setParent(phraseElement); List allSubjects =
* new ArrayList(); allSubjects.add(subjectPhrase);
* phraseElement.setFeature(Feature.SUBJECTS, allSubjects);
* baseForm.append(subjectPhrase.getFeatureAsString(Feature.BASE_FORM));
* subjectPhrase.setFeature(Feature.DISCOURSE_FUNCTION,
* DiscourseFunction.SUBJECT);
*
* if (subjectPhrase.hasFeature(Feature.GENDER)) {
* phraseElement.setFeature(Feature.GENDER, subjectPhrase
* .getFeature(Feature.GENDER)); } if
* (subjectPhrase.hasFeature(Feature.NUMBER)) {
* phraseElement.setFeature(Feature.NUMBER, subjectPhrase
* .getFeature(Feature.NUMBER));
*
* } if (subjectPhrase.hasFeature(Feature.PERSON)) {
* phraseElement.setFeature(Feature.PERSON, subjectPhrase
* .getFeature(Feature.PERSON)); } }
*/
/**
* Creates a blank canned text phrase with no text.
*
* @return a PhraseElement representing this phrase.
*/
public NLGElement createStringElement() {
return createStringElement(null);
}
/**
* Creates a canned text phrase with the given text.
*
* @param text the canned text.
* @return a PhraseElement representing this phrase.
*/
public NLGElement createStringElement(String text) {
return new StringElement(text);
}
/**
* Creates a new (empty) coordinated phrase
*
* @return empty CoordinatedPhraseElement
*/
public CoordinatedPhraseElement createCoordinatedPhrase() {
return new CoordinatedPhraseElement();
}
/**
* Creates a new coordinated phrase with two elements (initially)
*
* @param coord1 - first phrase to be coordinated
* @param coord2 = second phrase to be coordinated
* @return CoordinatedPhraseElement for the two given elements
*/
public CoordinatedPhraseElement createCoordinatedPhrase(Object coord1, Object coord2) {
return new CoordinatedPhraseElement(coord1, coord2);
}
/***********************************************************************************
* Document level stuff
***********************************************************************************/
/**
* Creates a new document element with no title.
*
* @return a DocumentElement
*/
public DocumentElement createDocument() {
return createDocument(null);
}
/**
* Creates a new document element with the given title.
*
* @param title the title for this element.
* @return a DocumentElement.
*/
public DocumentElement createDocument(String title) {
return new DocumentElement(DocumentCategory.DOCUMENT, title);
}
/**
* Creates a new document element with the given title and adds all of the
* given components in the list
*
* @param title the title of this element.
* @param components a List of NLGElements that form the
* components of this element.
* @return a DocumentElement
*/
public DocumentElement createDocument(String title, List components) {
DocumentElement document = new DocumentElement(DocumentCategory.DOCUMENT, title);
if(components != null) {
document.addComponents(components);
}
return document;
}
/**
* Creates a new document element with the given title and adds the given
* component.
*
* @param title the title for this element.
* @param component an NLGElement that becomes the first component of
* this document element.
* @return a DocumentElement
*/
public DocumentElement createDocument(String title, NLGElement component) {
DocumentElement element = new DocumentElement(DocumentCategory.DOCUMENT, title);
if(component != null) {
element.addComponent(component);
}
return element;
}
/**
* Creates a new list element with no components.
*
* @return a DocumentElement representing the list.
*/
public DocumentElement createList() {
return new DocumentElement(DocumentCategory.LIST, null);
}
/**
* Creates a new list element and adds all of the given components in the
* list
*
* @param textComponents a List of NLGElements that form the
* components of this element.
* @return a DocumentElement representing the list.
*/
public DocumentElement createList(List textComponents) {
DocumentElement list = new DocumentElement(DocumentCategory.LIST, null);
list.addComponents(textComponents);
return list;
}
/**
* Creates a new section element with the given title and adds the given
* component.
*
* @param component an NLGElement that becomes the first component of
* this document element.
* @return a DocumentElement representing the section.
*/
public DocumentElement createList(NLGElement component) {
DocumentElement list = new DocumentElement(DocumentCategory.LIST, null);
list.addComponent(component);
return list;
}
/**
* Creates a new enumerated list element with no components.
*
* @return a DocumentElement representing the list.
*/
public DocumentElement createEnumeratedList() {
return new DocumentElement(DocumentCategory.ENUMERATED_LIST, null);
}
/**
* Creates a new enumerated list element and adds all of the given components in the
* list
*
* @param textComponents a List of NLGElements that form the
* components of this element.
* @return a DocumentElement representing the list.
*/
public DocumentElement createEnumeratedList(List textComponents) {
DocumentElement list = new DocumentElement(DocumentCategory.ENUMERATED_LIST, null);
list.addComponents(textComponents);
return list;
}
/**
* Creates a new section element with the given title and adds the given
* component.
*
* @param component an NLGElement that becomes the first component of
* this document element.
* @return a DocumentElement representing the section.
*/
public DocumentElement createEnumeratedList(NLGElement component) {
DocumentElement list = new DocumentElement(DocumentCategory.ENUMERATED_LIST, null);
list.addComponent(component);
return list;
}
/**
* Creates a list item for adding to a list element.
*
* @return a DocumentElement representing the list item.
*/
public DocumentElement createListItem() {
return new DocumentElement(DocumentCategory.LIST_ITEM, null);
}
/**
* Creates a list item for adding to a list element. The list item has the
* given component.
*
* @return a DocumentElement representing the list item.
*/
public DocumentElement createListItem(NLGElement component) {
DocumentElement listItem = new DocumentElement(DocumentCategory.LIST_ITEM, null);
listItem.addComponent(component);
return listItem;
}
/**
* Creates a new paragraph element with no components.
*
* @return a DocumentElement representing this paragraph
*/
public DocumentElement createParagraph() {
return new DocumentElement(DocumentCategory.PARAGRAPH, null);
}
/**
* Creates a new paragraph element and adds all of the given components in
* the list
*
* @param components a List of NLGElements that form the
* components of this element.
* @return a DocumentElement representing this paragraph
*/
public DocumentElement createParagraph(List components) {
DocumentElement paragraph = new DocumentElement(DocumentCategory.PARAGRAPH, null);
if(components != null) {
paragraph.addComponents(components);
}
return paragraph;
}
/**
* Creates a new paragraph element and adds the given component
*
* @param component an NLGElement that becomes the first component of
* this document element.
* @return a DocumentElement representing this paragraph
*/
public DocumentElement createParagraph(NLGElement component) {
DocumentElement paragraph = new DocumentElement(DocumentCategory.PARAGRAPH, null);
if(component != null) {
paragraph.addComponent(component);
}
return paragraph;
}
/**
* Creates a new section element.
*
* @return a DocumentElement representing the section.
*/
public DocumentElement createSection() {
return new DocumentElement(DocumentCategory.SECTION, null);
}
/**
* Creates a new section element with the given title.
*
* @param title the title of the section.
* @return a DocumentElement representing the section.
*/
public DocumentElement createSection(String title) {
return new DocumentElement(DocumentCategory.SECTION, title);
}
/**
* Creates a new section element with the given title and adds all of the
* given components in the list
*
* @param title the title of this element.
* @param components a List of NLGElements that form the
* components of this element.
* @return a DocumentElement representing the section.
*/
public DocumentElement createSection(String title, List components) {
DocumentElement section = new DocumentElement(DocumentCategory.SECTION, title);
if(components != null) {
section.addComponents(components);
}
return section;
}
/**
* Creates a new section element with the given title and adds the given
* component.
*
* @param title the title for this element.
* @param component an NLGElement that becomes the first component of
* this document element.
* @return a DocumentElement representing the section.
*/
public DocumentElement createSection(String title, NLGElement component) {
DocumentElement section = new DocumentElement(DocumentCategory.SECTION, title);
if(component != null) {
section.addComponent(component);
}
return section;
}
/**
* Creates a new sentence element with no components.
*
* @return a DocumentElement representing this sentence
*/
public DocumentElement createSentence() {
return new DocumentElement(DocumentCategory.SENTENCE, null);
}
/**
* Creates a new sentence element and adds all of the given components.
*
* @param components a List of NLGElements that form the
* components of this element.
* @return a DocumentElement representing this sentence
*/
public DocumentElement createSentence(List components) {
DocumentElement sentence = new DocumentElement(DocumentCategory.SENTENCE, null);
sentence.addComponents(components);
return sentence;
}
/**
* Creates a new sentence element
*
* @param components an NLGElement that becomes the first component of
* this document element.
* @return a DocumentElement representing this sentence
*/
public DocumentElement createSentence(NLGElement components) {
DocumentElement sentence = new DocumentElement(DocumentCategory.SENTENCE, null);
sentence.addComponent(components);
return sentence;
}
/**
* Creates a sentence with the given subject and verb. The phrase factory is
* used to construct a clause that then forms the components of the
* sentence.
*
* @param subject the subject of the sentence.
* @param verb the verb of the sentence.
* @return a DocumentElement representing this sentence
*/
public DocumentElement createSentence(Object subject, Object verb) {
return createSentence(subject, verb, null);
}
/**
* Creates a sentence with the given subject, verb and direct object. The
* phrase factory is used to construct a clause that then forms the
* components of the sentence.
*
* @param subject the subject of the sentence.
* @param verb the verb of the sentence.
* @param complement the object of the sentence.
* @return a DocumentElement representing this sentence
*/
public DocumentElement createSentence(Object subject, Object verb, Object complement) {
DocumentElement sentence = new DocumentElement(DocumentCategory.SENTENCE, null);
sentence.addComponent(createClause(subject, verb, complement));
return sentence;
}
/**
* Creates a new sentence with the given canned text. The canned text is
* used to form a canned phrase (from the phrase factory) which is then
* added as the component to sentence element.
*
* @param cannedSentence the canned text as a String.
* @return a DocumentElement representing this sentence
*/
public DocumentElement createSentence(String cannedSentence) {
DocumentElement sentence = new DocumentElement(DocumentCategory.SENTENCE, null);
if(cannedSentence != null) {
sentence.addComponent(createStringElement(cannedSentence));
}
return sentence;
}
}