Class Messaging

java.lang.Object
com.github.yellowstonegames.text.Messaging
public final class Messaging extends 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, Pronoun, String, Pronoun) (or one of its overloads) with a template that has specific placeholder glyphs, along with a user name, optional target name, user Pronoun (an enum in this class) to specify how the user should be addressed, including their gender, optional target Pronoun, 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 Pronoun 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 Pronoun.SECOND_PERSON_SINGULAR, target "the beast", targetTrait Pronoun.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 Pronoun.FIRST_PERSON_SINGULAR, this returns "I am my own boss."
  • When changingTrait is Pronoun.FIRST_PERSON_PLURAL, this returns "We are our own bosses."
  • When changingTrait is Pronoun.SECOND_PERSON_SINGULAR, this returns "You are your own boss."
  • When changingTrait is Pronoun.SECOND_PERSON_PLURAL, this returns "You are your own bosses."
  • When changingTrait is Pronoun.NO_GENDER, this returns "It is its own boss."
  • When changingTrait is Pronoun.MALE_GENDER, this returns "He is his own boss."
  • When changingTrait is Pronoun.FEMALE_GENDER, this returns "She is her own boss."
  • When changingTrait is Pronoun.UNSPECIFIED_GENDER, this returns "They are their own boss."
  • When changingTrait is Pronoun.ADDITIONAL_GENDER, this returns "Xe is xis own boss."
  • When changingTrait is Pronoun.SPECIAL_CASE_GENDER, this returns "Qvqe is qvqis own boss."
  • When changingTrait is Pronoun.GROUP, this returns "They are their own bosses."
Messaging.transform("@Name spit$ in ^name_s face^s!", userName, userTrait, targetName, targetTrait)
  • When userTrait is Pronoun.SECOND_PERSON_SINGULAR, targetName is "the goblin", and targetTrait is Pronoun.MALE_GENDER, this returns "You spit in the goblin's face!"
  • When userName is "the goblin", userTrait is Pronoun.MALE_GENDER, and targetTrait is Pronoun.SECOND_PERSON_SINGULAR, this returns "The goblin spits in your face!"
  • When userTrait is Pronoun.SECOND_PERSON_SINGULAR, targetName is "the goblins", and targetTrait is Pronoun.GROUP, this returns "You spit in the goblins' faces!"
  • When userName is "the goblins", userTrait is Pronoun.GROUP, and targetTrait is Pronoun.SECOND_PERSON_SINGULAR, this returns "The goblins spit in your face!"

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static class 
    Messaging.BeingSubstitution
    Undocumented; use at your own peril.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    learnIrregularWord(String word, String firstPersonSingular, String firstPersonPlural, String secondPersonSingular, String secondPersonPlural, String thirdPersonSingular, 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 String
    transform(CharSequence message, String[] users, Pronoun 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 Pronoun.
    static String
    transform(CharSequence message, String[] users, Pronoun userTrait, String[] targets, Pronoun targetTrait)
    Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given array of users, that group's associated Pronoun, the given array of targets, and that group's Pronoun.
    static String
    transform(CharSequence message, String[] users, Pronoun userTrait, String[] targets, Pronoun targetTrait, String... extra)
    Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given array of users, that group's associated Pronoun, the given group of targets, and that group's Pronoun.
    static String
    transform(CharSequence message, String[] users, Pronoun userTrait, String target, Pronoun targetTrait)
    Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given array of users, that group's associated Pronoun, the given target, and their Pronoun.
    static String
    transform(CharSequence message, String[] users, Pronoun userTrait, String target, Pronoun targetTrait, String... extra)
    Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given array of users, that group's associated Pronoun, the given target, and their Pronoun.
    static String
    transform(CharSequence message, String user, Pronoun 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 Pronoun.
    static String
    transform(CharSequence message, String user, Pronoun userTrait, String[] targets, Pronoun 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 Pronoun, the given array of targets, and that group's Pronoun.
    static String
    transform(CharSequence message, String user, Pronoun userTrait, String[] targets, Pronoun targetTrait, 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 Pronoun, the given array of targets, and that group's Pronoun.
    static String
    transform(CharSequence message, String user, Pronoun userTrait, String target, Pronoun 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 Pronoun, the given target, and their Pronoun.
    static String
    transform(CharSequence message, String user, Pronoun userTrait, String target, Pronoun targetTrait, 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 Pronoun, the given target, and their Pronoun.

    Methods inherited from class Object

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

  • Method Details

    • transform

      public static String transform(CharSequence message, String user, Pronoun 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 Pronoun.
      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 Pronoun enum that determines how user should be referred to
      Returns:
      a String resulting from the processing of message

    • transform

      public static String transform(CharSequence message, String[] users, Pronoun 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 Pronoun. The Pronoun only matters if it is first-person or second-person (in which case this uses the plural form) or if users contains one member (in which case it uses any gendered pronouns specified by userTrait); it uses Pronoun.GROUP in any other case.
      Parameters:
      message - the message to transform; should contain "@" or "$" in it, at least, to be replaced
      users - a String array as a group of users for cases where it can replace text, like "@" or "@Name"
      userTrait - the Pronoun enum that determines how users should be referred to
      Returns:
      a String resulting from the processing of message

    • transform

      public static String transform(CharSequence message, String user, Pronoun userTrait, String target, Pronoun 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 Pronoun, the given target, and their Pronoun.
      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 Pronoun 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 Pronoun enum that determines how the target should be referred to
      Returns:
      a String resulting from the processing of message

    • transform

      public static String transform(CharSequence message, String[] users, Pronoun userTrait, String target, Pronoun targetTrait)
      Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given array of users, that group's associated Pronoun, the given target, and their Pronoun. The Pronoun for users only matters if it is first-person or second-person (in which case this uses the plural form) or if users contains one member (in which case it uses any gendered pronouns specified by userTrait); it uses Pronoun.GROUP in any other case.
      Parameters:
      message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced
      users - a String array as a group of users for cases where they can replace text like "@" or "@Name"
      userTrait - the Pronoun enum that determines how users should be referred to
      target - the name of the target for cases where it can replace text like "^" or "^Name"
      targetTrait - the Pronoun enum that determines how the target should be referred to
      Returns:
      a String resulting from the processing of message

    • transform

      public static String transform(CharSequence message, String[] users, Pronoun userTrait, String[] targets, Pronoun targetTrait)
      Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given array of users, that group's associated Pronoun, the given array of targets, and that group's Pronoun. The Pronouns only matter if they are is first-person or second-person (in which case this uses the plural form) or if an array contains one member (in which case it uses any gendered pronouns specified by userTrait or targetTrait); it uses Pronoun.GROUP in any other case.
      Parameters:
      message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced
      users - a String array as a group of users for cases where they can replace text like "@" or "@Name"
      userTrait - the Pronoun enum that determines how users should be referred to
      targets - a String array as a group of targets for cases where they can replace text like "@" or "@Name"
      targetTrait - the Pronoun enum that determines how the targets should be referred to
      Returns:
      a String resulting from the processing of message

    • transform

      public static String transform(CharSequence message, String user, Pronoun userTrait, String[] targets, Pronoun 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 Pronoun, the given array of targets, and that group's Pronoun. The Pronoun for targets only matters if it is first-person or second-person (in which case this uses the plural form) or if the array contains one member (in which case it uses any gendered pronouns specified by targetTrait); it uses Pronoun.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 Pronoun enum that determines how user should be referred to
      targets - a String array as a group of targets for cases where they can replace text like "@" or "@Name"
      targetTrait - the Pronoun enum that determines how the targets should be referred to
      Returns:
      a String resulting from the processing of message

    • transform

      public static String transform(CharSequence message, String user, Pronoun userTrait, String target, Pronoun targetTrait, 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 Pronoun, the given target, and their Pronoun. 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 Pronoun 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 Pronoun 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 String transform(CharSequence message, String[] users, Pronoun userTrait, String target, Pronoun targetTrait, String... extra)
      Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given array of users, that group's associated Pronoun, the given target, and their Pronoun. 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 Pronoun for users only matters if it is first-person or second-person (in which case this uses the plural form) or if the array contains one member (in which case it uses any gendered pronouns specified by userTrait); it uses Pronoun.GROUP in any other case.
      Parameters:
      message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced
      users - a String array as a group of users for cases where they can replace text like "@" or "@Name"
      userTrait - the Pronoun enum that determines how users should be referred to
      target - the name of the target for cases where it can replace text like "^" or "^Name"
      targetTrait - the Pronoun 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 String transform(CharSequence message, String[] users, Pronoun userTrait, String[] targets, Pronoun targetTrait, String... extra)
      Takes message and replaces any of the special terms this recognizes, like @, ^, and $, with the appropriately- conjugated terms for the given array of users, that group's associated Pronoun, the given group of targets, and that group's Pronoun. 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 Pronouns only matter if they are is first-person or second-person (in which case this uses the plural form) or if an array contains one member (in which case it uses any gendered pronouns specified by userTrait or targetTrait); it uses Pronoun.GROUP in any other case.
      Parameters:
      message - the message to transform; should contain "@", "^", or "$" in it, at least, to be replaced
      users - a String array as a group of users for cases where they can replace text like "@" or "@Name"
      userTrait - the Pronoun enum that determines how users should be referred to
      targets - a String array as a group of targets for cases where they can replace text like "@" or "@Name"
      targetTrait - the Pronoun enum that determines how the targets 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 String transform(CharSequence message, String user, Pronoun userTrait, String[] targets, Pronoun targetTrait, 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 Pronoun, the given array of targets, and that group's Pronoun. 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 Pronoun for targets only matters if it is first-person or second-person (in which case this uses the plural form) or if the array contains one member (in which case it uses any gendered pronouns specified by targetTrait); it uses Pronoun.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 Pronoun enum that determines how user should be referred to
      targets - a String array as a group of targets for cases where they can replace text like "@" or "@Name"
      targetTrait - the Pronoun enum that determines how the targets 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(String word, String firstPersonSingular, String firstPersonPlural, String secondPersonSingular, String secondPersonPlural, String thirdPersonSingular, 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")