Section 3 Getting started

This page is based on a page of the wiki for the original SimpleNLG.

It’s important to note that SimpleNLG-NL is a library [1], not an application! This means you cannot run it as a Java program – it does not have a "main" method. You need to create your own Java program which makes use of simplenlg classes and methods.

To enable your program to make use of the simplenlg library, you’ll need to:

• Clone the repository or download the zip file by clicking here: Download zip.

• Extract it and then add SimpleNLG-NL to your classpath or import the source as a module and add it as a dependency of your project. (For instructions on how to do this in Eclipse, see Appendix B of the original wiki).

• Create a new Java class which has the main method in it. In this example, let’s call the new class TestMain.

• At the top of that class, put in the following import statements:

    import simplenlg.framework.*;
    import simplenlg.lexicon.*;
    import simplenlg.realiser.*;
    import simplenlg.phrasespec.*;
    import simplenlg.features.*;
  

• Create a SimpleNLG lexicon, NLGFactory, and realiser using the following statements: Replace dutch with your intended language.

    Lexicon lexicon = new simplenlg.lexicon.dutch.XMLLexicon();
    NLGFactory nlgFactory = new NLGFactory(lexicon);
    Realiser realiser = new Realiser();
  

Note that multiple instances of the lexicon and the factory can be created to make your system multilingual. The Realiser class is language-independent.

Also note: The method of initialising the lexicon differs from the example given for the original SimpleNLG.

Following these steps, you should have code that looks like the following:

    import simplenlg.framework.*;
    import simplenlg.lexicon.*;
    import simplenlg.realiser.*;
    import simplenlg.phrasespec.*;
    import simplenlg.features.*;


    public class TestMain {

            public static void main(String[] args) {
                    Lexicon lexicon = new simplenlg.lexicon.dutch.XMLLexicon();
                    NLGFactory nlgFactory = new NLGFactory(lexicon);
                    Realiser realiser = new Realiser();

            }

    }

Figure 1: A Java class which is ready to make use of the SimpleNLG-NL library.

You’re now ready to make use of SimpleNLG-NL to generate sentences!

For further examples on ways to use the English SimpleNLG, take a look at the java files in SimpleNLG's tests.

Setting the language

The language used by the lexicon and the nlgFactory is determined by the implementation of XMLLexicon that is used. To build on the earlier example, here is a version that can use all three languages:

    import simplenlg.framework.*;
    import simplenlg.lexicon.*;
    import simplenlg.realiser.*;
    import simplenlg.phrasespec.*;
    import simplenlg.features.*;


    public class TestMain {

            public static void main(String[] args) {
                    Lexicon dutchLexicon = new simplenlg.lexicon.dutch.XMLLexicon();
                    Lexicon frenchLexicon = new simplenlg.lexicon.french.XMLLexicon();;
                    Lexicon englishLexicon = new simplenlg.lexicon.english.XMLLexicon();;
                    
                    NLGFactory dutchFactory = new NLGFactory(dutchLexicon);
                    NLGFactory frenchFactory = new NLGFactory(frenchLexicon);
                    NLGFactory englishFactory = new NLGFactory(englishLexicon);
                   
                    Realiser realiser = new Realiser();

            }

    }

In this wiki nlgFactory is used, but should be replaced by the factory you created for you desired language, e.g. dutchFactory.

Generating the simplest kind of phrase in SimpleNLG

Let’s create the simplest kind of sentence allowed in SimpleNLG: canned text, i.e., a string which we’d like output to the screen as is. For instance, let’s say we are writing a program which takes input from users and generates a different paragraph depending on the various inputs. But let’s say that no matter what, we always want the first line of the paragraph to be “My dog is happy” because we feel everyone should share in the good news. The SimpleNLG code to do this is:

    NLGElement s1 = nlgFactory.createSentence("my dog is happy");

We now need to use the Realiser to output the string:

    String output = realiser.realiseSentence(s1);
    System.out.println(output);

It’s important to note that you only need to create the Lexicon, NLGFactory, and Realiser once within your program for each language, as mentioned earlier; you don’t need to create them for every sentence you generate. So a good idea is to create these at the start of your program and use them over the lifetime of the program run.

The main steps involved in generating a more complicated sentence

The last example was the simplest way to create a sentence, and as you can see, it requires you to do most of the work. Now let's take a look at how to get SimpleNLG-NL to do most of the work. Keep in mind that SimpleNLG-NL is pretty flexible in this way, and there are several other ways to generate sentences – many of the things that you think of will probably work as well.

At the most fine-grained level, SimpleNLG understands what a sentence is using a class called SPhraseSpec. This is accessible through the NLGFactory, using the createClause method. The ideas of ‘verb phrase’, ‘noun phrase’, ‘prepositional phrase’, ‘adjective phrase’, and ‘adverb phrase’ are are also all accessible through NLGFactory, using createVerbPhrase, createNounPhrase, createPrepositionPhrase, etc. These return similarly named classes – VPPhraseSpec, NPPhraseSpec, PPPhraseSpec, AdjPhraseSpec, and AdvPhraseSpec.

In order to build a sentence using these SimpleNLG concepts or classes, you will normally follow these steps (all of this will be further explained in Sections V and on):

• Create an instance of NLGFactory if you didn't already.
• Create a placeholder for the sentence using NLGFactory's createClause() method. (This returns an SPhraseSpec instance.)
• Create a verb, subject, and object using NLGFactory's createVerbPhrase() and createNounPhrase() methods. (These return VPPhraseSpec and NPPhraseSpec instances.)
• If you want, create prepositional phrases, adjective phrases, and adverb phrases using NLGFactory's createPrepositionPhrase(), createAdjectivePhrase(), and createAdverbPhrase() methods. (These return PPPhraseSpec, AdjPhraseSpec and AdvPhraseSpec instances.)
• Indicate what role these various parts of speech will play in the desired sentence. For example, specify that you want a particular noun phrase to be the subject of the sentence, and some other noun phrase to be the object, using setSubject and setObject. Specify the verb using setVerb, and the complement (e.g., the prepositional phrase) using addComplement.
• Create a SimpleNLG object called the Realiser if you didn't already.
• Ask the Realiser to ‘realise’ or transform the SPhraseSpec instance into a syntactically correct string.

You now have a string which is a grammatical phrase or sentence and it can be treated like any other Java string. For instance, you can manipulate it further or print it out using the Java method System.out.println().

Note that this is the most detailed approach: You can actually just use setSubject, setVerb, etc., by passing these methods simple strings as arguments. Unless you're doing more complicated things, first specifying that a subject is an NPPhraseSpec or that a verb is a VPPhraseSpec is not even necessary! See Section V for an example of actual Java code used to generate a sentence.

Below is quick breakdown of the main parts of speech that SimpleNLG-NL can handle. Not that there can be differences between the language in terms of coverage. The rest of the tutorial will discuss each of these parts of speech in more detail.

---

[1] A library or API is a collection of methods/functions that people can make use of in their programs. This saves programmers from having to write that code themselves.