squidpony

Class Messaging

java.lang.Object

squidpony.Messaging

public class Messaging
extends java.lang.Object

Helps handle formation of messages from a template, using correct pronouns and helping handle various idiosyncrasies in English-language text. You call the static method transform(CharSequence, String, NounTrait, String, NounTrait) (or one of its overloads) with a template that has specific placeholder glyphs, along with a user name, optional target name, user NounTrait (an enum in this class) to specify how the user should be addressed, including their gender, optional target NounTrait, and possibly extra terms that should be inserted. The placeholder glyphs are usually followed by a specific word that is conjugated in the template for the first-person case, and will be changed to fit the NounTrait for the user or target. For example, you could use "@Name hit$ ^ for ~ damage!" as a message. You could transform it with user "Heero Supra", userTrait NounTrait.SECOND_PERSON_SINGULAR, target "the beast", targetTrait NounTrait.UNSPECIFIED_GENDER, and extra "10" to get the message "You hit the beast for 10 damage!". You could swap the user and target (along with their traits) to get the message "The beast hits you for 10 damage!" You can handle more complex verbs in some cases, such as "@I hurr$$$ to catch up!" can be transformed to "You hurry to catch up!" or "He hurries to catch up!". The rules are fairly simple; @word conjugates a specific word from a list to the correct kind for the user, while ^word does a similar thing but conjugates for the target. Between 1 and 3 $ chars can be used at the end of verbs to conjugate them appropriately for the present tense when the verb is performed by the user (with just $) or alternately the target (if the $ chars are preceded by a ^), while @s, @ss, @sss, ^s, ^ss, or ^sss can be added at the end of nouns to pluralize them if appropriate. Using one $ or s will add s or nothing, as in the case of hit becoming hits, using two $ or s chars will add es or nothing, as in the case of scratch becoming scratches, and using three will add ies or y, as in the case of carry becoming carries. Some unusual pluralization forms are handled; @usi will turn octop@usi into octopus or octopi, and radi@usi into radius or radii, while @fves will turn el@fves into elf or elves, or dwar@fves into dwarf or dwarves.
The words you can put after a @ or ^ start with a small list and can be added to with learnIrregularWord(String, String, String, String, String, String, String). The initial list is: name, name_s, i, me, my, mine, myself, am, have, do, haven_t, don_t, or any of these with the first char capitalized (meant for words at the start of sentences). The non-word shortened terms "m" and "ve" can be used for "I'm" and "I've", respectively, as well as "you're" and "you've", plus "he's" for "he is" and "he's" for "he has". Most of the rest conjugate as you would expect; @me will become him, her, it, them, you, or still more forms depending on userTrait. You can also use @ or ^ on its own as an equivalent to @name or ^name.
Examples:
Messaging.transform("@I @am @my own boss@ss.", "unused", changingTrait)

• When changingTrait is NounTrait.FIRST_PERSON_SINGULAR, this returns "I am my own boss."
• When changingTrait is NounTrait.FIRST_PERSON_PLURAL, this returns "We are our own bosses."
• When changingTrait is NounTrait.SECOND_PERSON_SINGULAR, this returns "You are your own boss."
• When changingTrait is NounTrait.SECOND_PERSON_PLURAL, this returns "You are your own bosses."
• When changingTrait is NounTrait.NO_GENDER, this returns "It is its own boss."
• When changingTrait is NounTrait.MALE_GENDER, this returns "He is his own boss."
• When changingTrait is NounTrait.FEMALE_GENDER, this returns "She is her own boss."
• When changingTrait is NounTrait.UNSPECIFIED_GENDER, this returns "They are their own boss."
• When changingTrait is NounTrait.ADDITIONAL_GENDER, this returns "Xe is xis own boss."
• When changingTrait is NounTrait.SPECIAL_CASE_GENDER, this returns "Qvqe is qvqis own boss."
• When changingTrait is NounTrait.GROUP, this returns "They are their own bosses."

Messaging.transform("@Name spit$ in ^name_s face^s!", userName, userTrait, targetName, targetTrait)

• When userTrait is NounTrait.SECOND_PERSON_SINGULAR, targetName is "the goblin", and targetTrait is NounTrait.MALE_GENDER, this returns "You spit in the goblin's face!"
• When userName is "the goblin", userTrait is NounTrait.MALE_GENDER, and targetTrait is NounTrait.SECOND_PERSON_SINGULAR, this returns "The goblin spits in your face!"
• When userTrait is NounTrait.SECOND_PERSON_SINGULAR, targetName is "the goblins", and targetTrait is NounTrait.GROUP, this returns "You spit in the goblins' faces!"
• When userName is "the goblins", userTrait is NounTrait.GROUP, and targetTrait is NounTrait.SECOND_PERSON_SINGULAR, this returns "The goblins spit in your face!"

Created by Tommy Ettinger on 10/31/2016.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Messaging.BeingSubstitution
static class	Messaging.Group
static class	Messaging.NounTrait Properties of nouns needed to correctly conjugate those nouns and refer to them with pronouns, such as genders.

Field Summary

Fields

Modifier and Type	Field and Description
protected static regexodus.Pattern	targetPattern
protected static regexodus.Pattern	userPattern

Constructor Summary

Constructors

Constructor and Description
Messaging()

Method Summary

Modifier and Type	Method and Description
static void	learnIrregularWord(java.lang.String word, java.lang.String firstPersonSingular, java.lang.String firstPersonPlural, java.lang.String secondPersonSingular, java.lang.String secondPersonPlural, java.lang.String thirdPersonSingular, java.lang.String thirdPersonPlural) Adds a given word, which should start with a lower-case letter and use lower-case letters and underscores only, to the dictionary this stores.
static java.lang.String	transform(java.lang.CharSequence message, Messaging.Group user, Messaging.NounTrait userTrait) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given group of users and that group's associated NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, Messaging.Group user, Messaging.NounTrait userTrait, Messaging.Group target, Messaging.NounTrait targetTrait) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given Group of users, that group's associated NounTrait, the given group of targets, and that group's NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, Messaging.Group user, Messaging.NounTrait userTrait, Messaging.Group target, Messaging.NounTrait targetTrait, java.lang.String... extra) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given Group of users, that group's associated NounTrait, the given group of targets, and that group's NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, Messaging.Group user, Messaging.NounTrait userTrait, java.lang.String target, Messaging.NounTrait targetTrait) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given Group of users, that group's associated NounTrait, the given target, and their NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, Messaging.Group user, Messaging.NounTrait userTrait, java.lang.String target, Messaging.NounTrait targetTrait, java.lang.String... extra) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given Group of users, that group's associated NounTrait, the given target, and their NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, java.lang.String user, Messaging.NounTrait userTrait) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user and their associated NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, java.lang.String user, Messaging.NounTrait userTrait, Messaging.Group target, Messaging.NounTrait targetTrait) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user, that user's associated NounTrait, the given Group of targets, and that group's NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, java.lang.String user, Messaging.NounTrait userTrait, Messaging.Group target, Messaging.NounTrait targetTrait, java.lang.String... extra) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user, that user's associated NounTrait, the given Group of targets, and that group's NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, java.lang.String user, Messaging.NounTrait userTrait, java.lang.String target, Messaging.NounTrait targetTrait) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user, their associated NounTrait, the given target, and their NounTrait.
static java.lang.String	transform(java.lang.CharSequence message, java.lang.String user, Messaging.NounTrait userTrait, java.lang.String target, Messaging.NounTrait targetTrait, java.lang.String... extra) Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user, their associated NounTrait, the given target, and their NounTrait.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

userPattern

protected static final regexodus.Pattern userPattern

targetPattern

protected static final regexodus.Pattern targetPattern

Constructor Detail

Messaging

public Messaging()

Method Detail

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         java.lang.String user,
                                         Messaging.NounTrait userTrait)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user and their associated NounTrait.

Parameters:

message - the message to transform; should contain "@" or "$" in it, at least, to be replaced

user - the name of the user for cases where it can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         Messaging.Group user,
                                         Messaging.NounTrait userTrait)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given group of users and that group's associated NounTrait. The NounTrait only matters if it is first-person or second-person (in which case this uses the plural form) or if the Group contains one member (in which case it uses any gendered pronouns specified by userTrait); it uses Messaging.NounTrait.GROUP in any other case.

Parameters:

message - the message to transform; should contain "@" or "$" in it, at least, to be replaced

user - a Messaging.Group of users (a String array) for cases where it can replace text, like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         java.lang.String user,
                                         Messaging.NounTrait userTrait,
                                         java.lang.String target,
                                         Messaging.NounTrait targetTrait)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user, their associated NounTrait, the given target, and their NounTrait.

Parameters:

message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced

user - the name of the user for cases where it can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

target - the name of the target for cases where it can replace text like "^" or "^Name"

targetTrait - the Messaging.NounTrait enum that determines how the target should be referred to

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         Messaging.Group user,
                                         Messaging.NounTrait userTrait,
                                         java.lang.String target,
                                         Messaging.NounTrait targetTrait)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given Group of users, that group's associated NounTrait, the given target, and their NounTrait. The NounTrait for user only matters if it is first-person or second-person (in which case this uses the plural form) or if the Group contains one member (in which case it uses any gendered pronouns specified by userTrait); it uses Messaging.NounTrait.GROUP in any other case.

Parameters:

message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced

user - the Messaging.Group of users for cases where they can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

target - the name of the target for cases where it can replace text like "^" or "^Name"

targetTrait - the Messaging.NounTrait enum that determines how the target should be referred to

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         Messaging.Group user,
                                         Messaging.NounTrait userTrait,
                                         Messaging.Group target,
                                         Messaging.NounTrait targetTrait)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given Group of users, that group's associated NounTrait, the given group of targets, and that group's NounTrait. The NounTraits only matter if they are is first-person or second-person (in which case this uses the plural form) or if a Group contains one member (in which case it uses any gendered pronouns specified by userTrait or targetTrait); it uses Messaging.NounTrait.GROUP in any other case.

Parameters:

message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced

user - the Messaging.Group of users for cases where they can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

target - the Messaging.Group of targets for cases where they can replace text like "@" or "@Name"

targetTrait - the Messaging.NounTrait enum that determines how the target should be referred to

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         java.lang.String user,
                                         Messaging.NounTrait userTrait,
                                         Messaging.Group target,
                                         Messaging.NounTrait targetTrait)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user, that user's associated NounTrait, the given Group of targets, and that group's NounTrait. The NounTrait for target only matters if it is first-person or second-person (in which case this uses the plural form) or if the Group contains one member (in which case it uses any gendered pronouns specified by targetTrait); it uses Messaging.NounTrait.GROUP in any other case.

Parameters:

message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced

user - the name of the user for cases where it can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

target - the Messaging.Group of targets for cases where they can replace text like "@" or "@Name"

targetTrait - the Messaging.NounTrait enum that determines how the target should be referred to

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         java.lang.String user,
                                         Messaging.NounTrait userTrait,
                                         java.lang.String target,
                                         Messaging.NounTrait targetTrait,
                                         java.lang.String... extra)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user, their associated NounTrait, the given target, and their NounTrait. Also replaces the nth occurrence of "~" with the matching nth item in extra, so the first "~" is replaced with the first item in extra, the second "~" with the second item, and so on until one is exhausted.

Parameters:

message - the message to transform; should contain "@", "^", "$", or "~" in it, at least, to be replaced

user - the name of the user for cases where it can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

target - the name of the target for cases where it can replace text like "^" or "^Name"

targetTrait - the Messaging.NounTrait enum that determines how the target should be referred to

extra - an array or vararg of String where the nth item in extra will replace the nth occurrence of "~"

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         Messaging.Group user,
                                         Messaging.NounTrait userTrait,
                                         java.lang.String target,
                                         Messaging.NounTrait targetTrait,
                                         java.lang.String... extra)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given Group of users, that group's associated NounTrait, the given target, and their NounTrait. Also replaces the nth occurrence of "~" with the matching nth item in extra, so the first "~" is replaced with the first item in extra, the second "~" with the second item, and so on until one is exhausted. The NounTrait for user only matters if it is first-person or second-person (in which case this uses the plural form) or if the Group contains one member (in which case it uses any gendered pronouns specified by userTrait); it uses Messaging.NounTrait.GROUP in any other case.

Parameters:

message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced

user - the Messaging.Group of users for cases where they can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

target - the name of the target for cases where it can replace text like "^" or "^Name"

targetTrait - the Messaging.NounTrait enum that determines how the target should be referred to

extra - an array or vararg of String where the nth item in extra will replace the nth occurrence of "~"

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         Messaging.Group user,
                                         Messaging.NounTrait userTrait,
                                         Messaging.Group target,
                                         Messaging.NounTrait targetTrait,
                                         java.lang.String... extra)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given Group of users, that group's associated NounTrait, the given group of targets, and that group's NounTrait. Also replaces the nth occurrence of "~" with the matching nth item in extra, so the first "~" is replaced with the first item in extra, the second "~" with the second item, and so on until one is exhausted. The NounTraits only matter if they are is first-person or second-person (in which case this uses the plural form) or if a Group contains one member (in which case it uses any gendered pronouns specified by userTrait or targetTrait); it uses Messaging.NounTrait.GROUP in any other case.

Parameters:

message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced

user - the Messaging.Group of users for cases where they can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

target - the Messaging.Group of targets for cases where they can replace text like "@" or "@Name"

targetTrait - the Messaging.NounTrait enum that determines how the target should be referred to

extra - an array or vararg of String where the nth item in extra will replace the nth occurrence of "~"

Returns:

a String resulting from the processing of message

transform

public static java.lang.String transform(java.lang.CharSequence message,
                                         java.lang.String user,
                                         Messaging.NounTrait userTrait,
                                         Messaging.Group target,
                                         Messaging.NounTrait targetTrait,
                                         java.lang.String... extra)

Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given user, that user's associated NounTrait, the given Group of targets, and that group's NounTrait. Also replaces the nth occurrence of "~" with the matching nth item in extra, so the first "~" is replaced with the first item in extra, the second "~" with the second item, and so on until one is exhausted. The NounTrait for target only matters if it is first-person or second-person (in which case this uses the plural form) or if the Group contains one member (in which case it uses any gendered pronouns specified by targetTrait); it uses Messaging.NounTrait.GROUP in any other case.

Parameters:

message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced

user - the name of the user for cases where it can replace text like "@" or "@Name"

userTrait - the Messaging.NounTrait enum that determines how user should be referred to

target - the Messaging.Group of targets for cases where they can replace text like "@" or "@Name"

targetTrait - the Messaging.NounTrait enum that determines how the target should be referred to

extra - an array or vararg of String where the nth item in extra will replace the nth occurrence of "~"

Returns:

a String resulting from the processing of message

learnIrregularWord

public static void learnIrregularWord(java.lang.String word,
                                      java.lang.String firstPersonSingular,
                                      java.lang.String firstPersonPlural,
                                      java.lang.String secondPersonSingular,
                                      java.lang.String secondPersonPlural,
                                      java.lang.String thirdPersonSingular,
                                      java.lang.String thirdPersonPlural)

Adds a given word, which should start with a lower-case letter and use lower-case letters and underscores only, to the dictionary this stores. The 6 additional arguments are used for first person singular ("I am"), first person plural ("we are"), second person singular ("you are"), second person plural ("you are", the same as the last one usually, but not always), third person singular ("he is"), third person plural ("they are").

Parameters:

word - the word to learn; must start with a letter and use only lower-case letters and underscores

firstPersonSingular - the conjugated form of the word for first-person singular ("I do", "I am")

firstPersonPlural - the conjugated form of the word for first-person plural ("we do", "we are")

secondPersonSingular - the conjugated form of the word for second-person singular ("you do", "you are")

secondPersonPlural - the conjugated form of the word for second-person plural ("you do", "you are")

thirdPersonSingular - the conjugated form of the word for third-person singular ("he does", "he is")

thirdPersonPlural - the conjugated form of the word for third-person plural and unspecified-gender singular ("they do", "they are")