Inflectible

Inflectible is a flexible template engine with inflection. It can use correct word forms where other template engines can't.

Maven dependency

<dependency>
    <groupId>org.tendiwa</groupId>
    <artifactId>inflectible</artifactId>
    <version>0.2.0</version>
</dependency>

What problem does it solve?

Many natural languages rely heavily on non-trivial rules of inflection. In order to construct texts in those languages with variable members of sentences, we can't always just concatenate strings: generally we have to know the grammatical structure of sentences we're constructing, and we have to know how words in particular form are spelled. For example, in Russian, a typical noun can have up to a dozen forms that are written differently in different sentences, and there is no simple "cram-it-in-printf" rule for how those forms are derived from the dictionary form of a word.

In English it is not usually a problem. But even in English, sometimes just concatenating strings is not enough to produce a grammatically correct sentence.

Consider this example: we need to display a message that some cutting tool cuts paper well. With something like printf function, we could use a template like this:

%s cuts paper well

We could pass "Knife" or "Razor", but if we pass "Scissors", then it produces a grammatically incorrect sentence "Scissors cuts paper well". This is just the most basic example how properly constructed sentences require the template engine to be aware of inflection rules.

How does it work?

Inflectible introduces two kinds of markup: vocabularies and templates.

In vocabularies, you put words of a language in all their various forms, and assign each form a grammatical meaning:

WOLF (Noun) {
    wolf
    wolves <Plur>
}
CHILD (Noun) {
    child
    children <Plur>
}
SCISSORS (Noun) <Plur> {
    scissors
}

In templatuaries, you put templates. Templates declare arguments and describe how those arguments are used to fill out the template:

actions.bite(subject, object) {
   [Subject] (and [subject]<Plur> are well known for their painful bites!) is biting a [object].
}

In your application, you have classes to represents the same concept that the words of a language represent. Those classes would implement Concept interface that require them to return the identifier of their lexeme:

class Wolf implements Concept {
    @Override
    public String identifier() {
        return "WOLF";
    }
}

With those classes, you construct a NativeSpeaker that knows how to speak a particular language using proper inflection rules, and ask him to fill out a particular template with particular concepts:

Wolf wolf = new Wolf();
Human girl = new Human("GIRL");
System.out.printf(
    nativeSpeaker.fillOut("actions.bite", wolf, girl);
);
// -> Output: Wolf (and wolves are known for their painful bites!) is biting a girl.

This may seem not very useful for English, but it makes a lot of sense e.g. in Russian, where a lexeme for НОЖ (KNIFE) would look like this:

НОЖ (Сущ) <Муж Неодуш> {
    нож
    ножа   <Ед Р>
    ножу   <Ед Д>
    нож    <Ед В>
    ножом  <Ед Т>
    ноже   <Ед П>
    ножи   <Мн И>
    ножей  <Мн Р>
    ножам  <Мн Д>
    ножи   <Мн В>
    ножами <Мн Т>
    ножах  <Мн П>
}

There are 12 different forms a word НОЖ can assume under different grammatical meanings, so choosing the correct one can become crucial.

Of course, it would be a pain to type all these words manually in a vocabulary markup. But the good news are that a machine can often guess with very high accuracy what would a particular word form would be, if we know the persistent grammatical meaning of a word and its dictionary form. Inflectible can generate those word forms for you, all you need to do is:

НОЖ (Сущ) <Муж Неодуш> {
    нож
    ...
}

That's the actual markup, and if template engine sees it, it can automatically produce a lexeme equivalent to the previous tediously written example. It even supports suppletion!

ЧЕЛОВЕК (Сущ) <Муж Одуш> {
    человек
    люди   <Мн>
    людьми <Мн Т>
    ...
}

What features is it going to provide?

The goals for version 1.0.0 are:

• Full automated word form generation support for every part of speech in Russian and English;
• Flexible design that allows allows automating inflection in any flective language;
• Agreement with numbers (двух коней, два коня, две лошади, пять коней, один конь, миллион и двадцать один конь — that is the Russian for two horses, two male horses, two female horses, five horses, one horse, million and twenty one horses. Just look at all the different endings);
• Phonetic "agreement" (indefinite article "a"/"an" in English and "de/d'" in French depend not on grammatical features of another word, but on its phonetical features);
• Complete basic vocabularies for English and Russian — built-in vocabularies with the most common words, such as articles, pronouns and numbers. It wouldn't make sense to ask every user of the template engine to compose or copy their own vocabulary for the most basic words of a language.
• Multipart templates for the cases when you want to split the result of filling a template into logical parts;
• IntelliJ IDEA plugin for markup editing;
• Maven plugin for generating explicit lexemes from partially defined ones at build time.