GH-392 Document messenger design classes

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/lexer/Lexer.java

@@ -19,6 +19,9 @@
 import org.panda_lang.framework.design.interpreter.source.Source;
 import org.panda_lang.framework.design.interpreter.token.Snippet;
 
+/**
+ * Converts source into the 
+ */
 public interface Lexer {
 
     Snippet convert(Source source);

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/messenger/FormatterFunction.java

@@ -18,6 +18,12 @@
 
 import java.util.function.BiFunction;
 
+/**
+ * Returns some value based on the given T value.
+ * Used to obtain placeholders values.
+ *
+ * @param <T> type of accepted value
+ */
 @FunctionalInterface
 public interface FormatterFunction<T> extends BiFunction<MessengerFormatter, T, Object> {
 

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/messenger/MessengerFormatter.java

@@ -20,6 +20,9 @@
 
 import java.util.Collection;
 
+/**
+ * Message formatter
+ */
 public interface MessengerFormatter {
 
     /**
@@ -32,7 +35,7 @@ public interface MessengerFormatter {
     String format(String message, Collection<Object> context);
 
     /**
-     * Register new placeholder
+     * Register a new placeholder
      *
      * @param placeholder the name of the placeholder
      * @param requiredData the required type of data to use that placeholder (if null, it means that placeholder does not require provided context)

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/messenger/MessengerInitializer.java

@@ -16,8 +16,16 @@
 
 package org.panda_lang.framework.design.interpreter.messenger;
 
+/**
+ * Messenger initializer called during the environment initialization
+ */
 public interface MessengerInitializer {
 
+    /**
+     * Process the given messenger
+     *
+     * @param messenger a new messenger
+     */
     void onInitialize(Messenger messenger);
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/messenger/MessengerLevel.java

@@ -16,13 +16,16 @@
 
 package org.panda_lang.framework.design.interpreter.messenger;
 
+/**
+ * Logging levels
+ */
 public enum MessengerLevel {
 
-    DEBUG,
     TRACE,
+    DEBUG,
     INFO,
     WARNING,
     ERROR,
-    FAILURE;
+    FAILURE
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/messenger/MessengerMessage.java

@@ -16,10 +16,23 @@
 
 package org.panda_lang.framework.design.interpreter.messenger;
 
+/**
+ * Message container
+ */
 public interface MessengerMessage {
 
-    String[] getContent();
+    /**
+     * Content of message
+     *
+     * @return the content
+     */
+    String getContent();
 
+    /**
+     * Get message level
+     *
+     * @return the level
+     */
     MessengerLevel getLevel();
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/messenger/MessengerMessageTranslator.java

@@ -16,10 +16,27 @@
 
 package org.panda_lang.framework.design.interpreter.messenger;
 
+/**
+ * Translates object of the specified type into the messages
+ *
+ * @param <T> type of accepted objects
+ */
 public interface MessengerMessageTranslator<T extends Object> {
 
-    boolean handle(Messenger messenger, T element);
+    /**
+     * Translate object into the messages
+     *
+     * @param messenger the messenger to use
+     * @param element the object to translate
+     * @return true if message interrupts current process (e.g. exceptions), otherwise false (e.g. warnings)
+     */
+    boolean translate(Messenger messenger, T element);
 
+    /**
+     * Get type of accepted values
+     *
+     * @return the type
+     */
     Class<T> getType();
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/messenger/MessengerOutputListener.java

@@ -16,8 +16,16 @@
 
 package org.panda_lang.framework.design.interpreter.messenger;
 
+/**
+ * Output listener
+ */
 public interface MessengerOutputListener {
 
+    /**
+     * Called when the messenger sends a message
+     *
+     * @param message the message to handle
+     */
     void onMessage(MessengerMessage message);
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/messenger/MessengerTypeFormatter.java

@@ -16,10 +16,28 @@
 
 package org.panda_lang.framework.design.interpreter.messenger;
 
+/**
+ * Utility class to register a couple of placeholders assigned to the same type
+ *
+ * @param <T> the generic type of formatter
+ * @see org.panda_lang.framework.design.interpreter.messenger.MessengerFormatter#register(String, Class, FormatterFunction)
+ */
 public interface MessengerTypeFormatter<T> {
 
+    /**
+     * Register a new placeholder
+     *
+     * @param placeholder the name of placeholder
+     * @param replacementFunction the value to replace with
+     * @return formatter instance
+     */
     MessengerTypeFormatter<T> register(String placeholder, FormatterFunction<T> replacementFunction);
 
+    /**
+     * Type of formatter
+     *
+     * @return the type
+     */
     Class<T> getType();
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/token/Snippet.java

@@ -28,7 +28,7 @@
 import java.util.List;
 
 /**
- * Snippet is one of the most basic elements used by Panda Framework and represents a portion of tokens.
+ * Snippet is one of the most basic elements used by Panda Framework and represents a sequence of tokens.
  * It may be compared to {@link String} and {@link org.panda_lang.framework.design.interpreter.token.TokenRepresentation} to characters.
  */
 public interface Snippet extends Snippetable, Iterable<TokenRepresentation> {

panda-framework/src/main/java/org/panda_lang/framework/language/interpreter/messenger/LoggerMessengerOutputListener.java

@@ -31,19 +31,19 @@ public LoggerMessengerOutputListener(Logger logger) {
 
     @Override
     public void onMessage(MessengerMessage message) {
-        for (String line : message.getContent()) {
+        for (String line : message.getContent().split(System.lineSeparator())) {
             this.log(message.getLevel(), line);
         }
     }
 
     private void log(MessengerLevel level, String message) {
         switch (level) {
-            case DEBUG:
-                logger.debug(message);
-                break;
             case TRACE:
                 logger.trace(message);
                 break;
+            case DEBUG:
+                logger.debug(message);
+                break;
             case INFO:
                 logger.info(message);
                 break;

panda-framework/src/main/java/org/panda_lang/framework/language/interpreter/messenger/PandaMessenger.java

@@ -64,7 +64,7 @@ public boolean send(Object message) {
             throw new PandaFrameworkException("Cannot translate a message - translator for " + message.getClass() + " not found");
         }
 
-        return translator.handle(this, message);
+        return translator.translate(this, message);
     }
 
     @Override

panda-framework/src/main/java/org/panda_lang/framework/language/interpreter/messenger/PandaMessengerMessage.java

@@ -22,15 +22,15 @@
 public class PandaMessengerMessage implements MessengerMessage {
 
     private final MessengerLevel level;
-    private final String[] message;
+    private final String message;
 
-    public PandaMessengerMessage(MessengerLevel level, String... message) {
+    public PandaMessengerMessage(MessengerLevel level, String message) {
         this.message = message;
         this.level = level;
     }
 
     @Override
-    public String[] getContent() {
+    public String getContent() {
         return message;
     }
 

panda/src/main/java/org/panda_lang/panda/language/interpreter/messenger/PandaTranslator.java

@@ -41,7 +41,7 @@ final class PandaTranslator<T> implements MessengerMessageTranslator<T> {
     }
 
     @Override
-    public boolean handle(Messenger messenger, T element) {
+    public boolean translate(Messenger messenger, T element) {
         Map<String, Object> data = new HashMap<>();
         data.put(null, element);
 
@@ -67,7 +67,7 @@ public boolean handle(Messenger messenger, T element) {
                 .build();
 
         MicroTemplate template = engine.load(request);
-        MessengerMessage message = new PandaMessengerMessage(scheme.getLevel(), template.toLines());
+        MessengerMessage message = new PandaMessengerMessage(scheme.getLevel(), template.getContent());
         messenger.sendMessage(message);
 
         return scheme.isInterrupting();

panda/src/main/java/org/panda_lang/panda/language/interpreter/messenger/template/MicroTemplate.java

@@ -16,8 +16,6 @@
 
 package org.panda_lang.panda.language.interpreter.messenger.template;
 
-import org.panda_lang.utilities.commons.StringUtils;
-
 public final class MicroTemplate {
 
     private final String content;
@@ -26,8 +24,8 @@ public final class MicroTemplate {
         this.content = content;
     }
 
-    public String[] toLines() {
-        return StringUtils.split(content, System.lineSeparator());
+    public String getContent() {
+        return content;
     }
 
 }