Simple, flexible and helpful library to handle messages with internationalization support for Java 8+

<h2>Convenience Methods</h2>
There are many methods for ease the message handling in the <code>MessageHandler</code> interface.
<h3>Obtaining messages</h3>
Methods for obtaining messages (not sending)
<h4>MessageHandler#get</h4>
<pre><code class="hljs language-java">String message = messageHandler.get(entity, messagePath, /* optional, varargs */ jitEntities);
</code></pre>
where <code>message</code> is the obtained message, <code>entity</code> is the used entity for placeholders and
language specification (it can be an entity that will be resolved to another entity, <code>messagePath</code>
is the message location in a file, commonly separating by dots <code>.</code> for internal sections
(depending on <code>NodeFile</code>) and <code>jitEntities</code> are the just-in-time entities, used to replace
placeholders only in that method call.
For example:
<pre><code class="hljs language-java">MailList userMailList = mails.getRecentMails(user);
String message = messageHandler.get(user, "message.welcome", userMailList);
</code></pre>
where <code>userMailList</code> is a Just-In-Time entity, and it will call a <code>PlaceholderProvider</code> registered
for type <code>MailList</code> and identifier specified in the message at <code>message.welcome</code> message
<h4>MessageHandler#replacing</h4>
<pre><code class="hljs language-java">String message = messageHandler.replacing(entity, messagePath, /* var-args */ replacementPack);
</code></pre>
Same as above, but replaces literal strings specified in code. Where <code>replacementPack</code> is a
var-args array of <code>Object</code>. It's a pair array of <code>String</code> and <code>Object</code>. I mean, you must add
a <code>String</code> and then an <code>Object</code>, and so on. Elements in even indexes are replaced by the elements
in odd indexes in the message. It's util for just-in-time replacements that aren't necessary
entities.
See this example in a 'command' using a command manager with parametric commands support
(like <a href="https://github.com/unnamed/command-flow/">command-flow</a>)
<pre><code class="hljs language-java">// command: setmoney &#x3C;money>
@Command(name = "setmoney")
void setMoney(@Sender User user, int money) {
 String message = messageHandler.replacing(
 user, "message.updated-money",
 "{{added}}", money,
 "{{total}}", user.getBalance() + money
 );
 // send the message
}
</code></pre>
<h3>Sending messages</h3>
Sending has a similar definition. They have the prefix <code>send</code> and then <code>replacing</code> (or not, if no
replacements are required), they also accept a string <code>mode</code> when the method name ends with <code>in</code>.
For example: <code>messageHandler.sendIn(target, "message.path", "title-mode");</code>

Convenience Methods

<h2>Getting Started</h2>
Welcome to the <code>nmessage</code> documentation.
<code>nmessage</code> is a simple, flexible and helpful library to handle messages with
internationalization support for multiple platforms like Bukkit (Minecraft)
<h3>Features</h3>
<ul>
<li>Use any message source (file, database, JAR file resources, etc.)</li>
<li>VERY helpful, just use <code>handler.send(receiver, "message.node")</code> and let
nmessage do the translation, sending and formatting job</li>
</ul>

Getting Started

<h2>Installation</h2>
You can add nmessage to your project using <a href="https://gradle.org/">Gradle</a>
(recommended), <a href="https://maven.apache.org/">Maven</a> or manually downloading
the JAR files
<h3>Gradle</h3>
Add our repository
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}
</code></pre>
Add the necessary dependencies
<pre><code class="hljs language-kotlin">dependencies {
 // Core API, necessary for everything
 implementation("me.yushust.message:core:7.1.3")
 
 // .PROPERTIES source type
 implementation("me.yushust.message:sourcetype-properties:7.1.3")
 
 // .JSON source type
 implementation("me.yushust.message:sourcetype-gson-json:7.1.3")
 
 // Bukkit YAML source type and helpers
 implementation("me.yushust.message:sourcetype-bukkit-yml:7.1.3")
 
 // BungeeCord YAML source type and helpers
 implementation("me.yushust.message:sourcetype-bungee-yml:7.1.3")
}
</code></pre>
<h3>Maven</h3>
Add our repository
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
Add the necessary dependencies
<pre><code class="hljs language-xml">&#x3C;!-- Core API, necessary for everything -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>core&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>

&#x3C;!-- .PROPERTIES source type -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>sourcetype-properties&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>

&#x3C;!-- .JSON source type -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>sourcetype-gson-json&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>

&#x3C;!-- Bukkit YAML source type and helpers -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>sourcetype-bukkit-yml&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>

&#x3C;!-- BungeeCord YAML source type and helpers -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>sourcetype-bungee-yml&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>
</code></pre>

Installation

<h2>Linguist</h2>
It is responsible for obtaining the language of a specific entity
<h3>Definition</h3>
<pre><code class="hljs language-java">public interface Linguist&#x3C;E> {
 @Nullable
 String getLanguage(E entity);
}
</code></pre>
You must implement the interface and set it to the <code>MessageHandler</code> to use it.
If the <code>getLanguage</code> method returns null, the default language is used.
<h3>Implementation</h3>
This is an example of an imaginary class 'User'
<pre><code class="hljs language-java">public class UserLinguist implements Linguist&#x3C;User> {
 @Override
 @Nullable
 public String getLanguage(User entity) {
 // get the language of "entity" and return it
 }
}
</code></pre>
<h3>Configuring</h3>
<pre><code class="hljs language-java">MessageHandler handler = MessageHandler.of(
 source,
 config -> {

 // using setLinguist(Linguist)
 config.specify(User.class)
 .setLinguist(new UserLinguist());

 // you can specify multiple linguist for
 // specific entity types
 config.specify(SomeOtherEntity.class)
 .setLinguist(new SomeOtherEntityLinguist());

 // you can also use lambda method references for this
 config.specify(ExampleUsingLambdaEntity.class)
 .setLinguist(ExampleUsingLambdaEntity::getLanguage);
 }
);
</code></pre>

Linguist

<h1>Message Sender</h1>
It sends messages to a specific entity according to a mode
<h3>Definition</h3>
<pre><code class="hljs language-java">public interface MessageSender&#x3C;E> {
 
 default void send(E receiver, String mode, StringList messages) {
 send(receiver, mode, messages.join("\n"));
 }
 
 void send(E receiver, String mode, String message);

}
</code></pre>
The method provides the <code>receiver</code> (the entity that must receive the given <code>message</code>),
the <code>mode</code> (how to send the message, this will be explained later), and the sent <code>message</code>.
<h3>Implementation</h3>
<pre><code class="hljs language-java">public class UserMessageSender implements MessageSender&#x3C;User> {
 @Override
 public void send(User receiver, String mode, String message) {
 // you can also add "outputs" (ex. window message, console message, etc)
 switch (mode) {
 case "info":
 receiver.send(message);
 break;
 case "warn":
 receiver.warn(message);
 break;
 case "severe":
 receiver.severe(message);
 break;
 }
 }
}
</code></pre>
<h3>Configuring</h3>
Set the <code>Messenger</code> for a specific type while constructing <code>MessageHandler</code>
<pre><code class="hljs language-java">MessageHandler handler = MessageHandler.of(
 source,
 config -> {
 // set the message sender
 config.specify(User.class)
 .setMessageSender(new UserMessageSender())
 // it's a fluent API, you can also set the linguist here
 .setLinguist(new UserLinguist());
 }
);
</code></pre>

Message Sender

<h2>Placeholder Providers</h2>
It's responsible for getting a value using a specific 'variable' in messages
For example, if we set <code>{receiver_name}</code> in a message, we can replace it with
the receiver name using a <code>PlaceholderProvider</code>.
In that variable, the parts are identifier (<code>receiver</code>) and the parameters
(<code>name</code>), they are delimited by <code>_</code>. And we resolve that implementing a
<code>PlaceholderProvider</code>
<h3>Definition</h3>
<code>PlaceholderProvider</code> is
<pre><code class="hljs language-java">public interface PlaceholderProvider&#x3C;E> {
 
 @Nullable
 Object replace(ContextRepository ctx, E entity, String parameters);
 
}
</code></pre>
where 'E' is the used entity type. In the above example, we can use a named
class that can receive a message, for example, an <code>User</code>.
<h3>Implementing</h3>
Implementing the placeholder provider for the above example:
<pre><code class="hljs language-java">public class UserPlaceholderProvider implements PlaceholderProvider&#x3C;User> {

 @Override
 @Nullable
 public Object replace(ContextRepository ctx, User entity, String param) {
 switch (param.toLowerCase()) {
 case "name": {
 return entity.getName();
 }
 case "age": {
 return entity.getAge();
 }
 case "another_property": {
 return entity.getAnotherProperty();
 }
 default: return null; // null indicates an invalid parameter
 }
 }

}
</code></pre>
The method return type is <code>Object</code> for convenience. You can return numbers, strings,
booleans and they are converted to a string using <code>Object#toString</code>. Null indicates
that an invalid parameter was provided and the placeholder isn't replaced.
<h3>Registration</h3>
<pre><code class="hljs language-java">MessageHandler handler = MessageHandler.of(
 source,
 config -> {
 config.specify(User.class)
 .addProvider("user", new UserPlaceholderProvider())
 .addProvider("idk", new SomeOtherProvider());
 }
);
</code></pre>

Placeholder Providers

<h2>Placeholders</h2>
We can specify placeholder delimiters while creating the <code>MessageHandler</code>. Default
delimiters are <code>%</code> for start, and <code>%</code> for end (same characters)
<pre><code class="hljs language-java">MessageHandler handler = MessageHandler.of(
 source,
 config -> {
 // format is: "{{identifier_parameter}}"
 config.delimiting(
 "{{", // start
 "}}" // end
 );
 }
);
</code></pre>