Add links to flux-commands.md (#488)

The tsv to enrich the flux-commands.md is taken from the repo
metafacture/metafacture-documentation.

Author: dr0i

metafacture-flux/src/main/java/org/metafacture/flux/HelpPrinter.java

@@ -26,24 +26,34 @@
 import org.metafacture.framework.annotations.Out;
 import org.metafacture.framework.annotations.ReturnsAvailableArguments;
 
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.FileReader;
 import java.io.IOException;
 import java.io.PrintStream;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
+import java.nio.file.Files;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
 
 /**
- * Prints Flux help for a given {@link ObjectFactory}
+ * Prints Flux help for a given {@link ObjectFactory}.
+ * If the file at {@value #PATH_TO_EXAMPLES} exists it's taken to insert links to examples and to the source code.
  *
  * @author Markus Michael Geipel
  */
 public final class HelpPrinter {
+    private static final String PATH_TO_EXAMPLES = "../metafacture-documentation/linksAndExamples.tsv";
+    private static final Map<String, String[]> EXAMPLES_MAP = new HashMap<>();
+    private static final int COLUMN_TO_PG_EXAMPLE = 3;
+    private static final int REQUIRED_COLUMNS_OF_EXAMPLE = 2;
 
     private HelpPrinter() {
         // no instances
@@ -55,8 +65,9 @@ private HelpPrinter() {
      * @param args unused
      *
      * @see #print
+     * @throws IOException when an I/O error occurs
      */
-    public static void main(final String[] args) {
+    public static void main(final String[] args) throws IOException {
         FluxProgramm.printHelp(System.out);
     }
 
@@ -66,9 +77,10 @@ public static void main(final String[] args) {
      *
      * @param factory the ObjectFactory
      * @param out     the PrintStream to print to
+     * @throws IOException when an I/O error occurs
      */
     public static void print(final ObjectFactory<?> factory,
-            final PrintStream out) {
+            final PrintStream out) throws IOException {
         out.println("Welcome to Metafacture");
         out.println("======================");
         out.println();
@@ -77,9 +89,9 @@ public static void print(final ObjectFactory<?> factory,
         out.println("\nUsage:\tflux FLOW_FILE [VARNAME=VALUE ...]\n");
         out.println("Available flux commands:\n");
 
-        final List<String> keyWords = new ArrayList<String>();
-        keyWords.addAll(factory.keySet());
+        final List<String> keyWords = new ArrayList<>(factory.keySet());
         Collections.sort(keyWords);
+        loadExamples();
         for (final String name : keyWords) {
             describe(name, factory, out);
         }
@@ -111,8 +123,42 @@ private static <T> void describe(final String name, final ObjectFactory<T> facto
             out.println("- arguments:\t" + arguments);
         }
 
-        final Map<String, Method> attributes = configurableClass.getSetters();
+        printAttributes(out, configurableClass, configurableClass.getSetters());
+        printSignature(out, moduleClass);
 
+        final String[] examplesEntry = EXAMPLES_MAP.get(name);
+        if (!EXAMPLES_MAP.isEmpty() && (examplesEntry == null || examplesEntry.length < REQUIRED_COLUMNS_OF_EXAMPLE)) {
+            throw new MetafactureException(
+                    "Failed to load build infos: tsv with links hasn't at least " + REQUIRED_COLUMNS_OF_EXAMPLE +
+                            " for the entry '" + name + "'");
+        }
+        if (examplesEntry != null && examplesEntry.length == COLUMN_TO_PG_EXAMPLE) {
+            out.println("- [example in Playground]" + "(" + examplesEntry[COLUMN_TO_PG_EXAMPLE - 1] + ")");
+        }
+        if (examplesEntry != null) {
+            out.println("- java class:\t[" + moduleClass.getCanonicalName() + "](" + examplesEntry[1] + ")");
+        }
+        else {
+            out.println("- java class:\t" + moduleClass.getCanonicalName());
+        }
+        out.println();
+    }
+
+    private static <T> void printSignature(final PrintStream out, final Class<? extends T> moduleClass) {
+        String inString = "<unknown>";
+        String outString = "";
+        final In inClass = moduleClass.getAnnotation(In.class);
+        if (inClass != null) {
+            inString = inClass.value().getSimpleName();
+        }
+        final Out outClass = moduleClass.getAnnotation(Out.class);
+        if (outClass != null) {
+            outString = outClass.value().getSimpleName();
+        }
+        out.println("- signature:\t" + inString + " -> " + outString);
+    }
+
+    private static <T> void printAttributes(final PrintStream out, final ConfigurableClass<? extends T> configurableClass, final Map<String, Method> attributes) {
         if (!attributes.isEmpty()) {
             out.print("- options:\t");
             final StringBuilder builder = new StringBuilder();
@@ -140,20 +186,6 @@ private static <T> void describe(final String name, final ObjectFactory<T> facto
             }
             out.println(builder.substring(0, builder.length() - 2));
         }
-
-        String inString = "<unknown>";
-        String outString = "";
-        final In inClass = moduleClass.getAnnotation(In.class);
-        if (inClass != null) {
-            inString = inClass.value().getSimpleName();
-        }
-        final Out outClass = moduleClass.getAnnotation(Out.class);
-        if (outClass != null) {
-            outString = outClass.value().getSimpleName();
-        }
-        out.println("- signature:\t" + inString + " -> " + outString);
-        out.println("- java class:\t" + moduleClass.getCanonicalName());
-        out.println();
     }
 
     @SuppressWarnings("unchecked")
@@ -171,4 +203,16 @@ private static Collection<String> getAvailableArguments(final Class<?> moduleCla
         return Collections.emptyList();
     }
 
+    private static void loadExamples() throws IOException {
+        final File f = new File(PATH_TO_EXAMPLES);
+        if (Files.exists(f.toPath())) {
+            final BufferedReader bufferedReader = new BufferedReader(new FileReader(f));
+            String line;
+            while ((line = bufferedReader.readLine()) != null) {
+                final String[] tsv = line.split("\t");
+                EXAMPLES_MAP.put(tsv[0], tsv);
+            }
+        }
+    }
+
 }

metafacture-flux/src/main/java/org/metafacture/flux/parser/FluxProgramm.java

@@ -178,9 +178,10 @@ public void start() {
     /**
      * Prints the help to the given PrintStream.
      *
-     * @param out the PrintStream to orint to
+     * @param out the PrintStream to print to
+     * @throws IOException when an I/O error occurs
      */
-    public static void printHelp(final PrintStream out) {
+    public static void printHelp(final PrintStream out) throws IOException {
         HelpPrinter.print(COMMAND_FACTORY, out);
     }
 

metafacture-flux/src/test/java/org/metafacture/flux/FluxProgrammTest.java

@@ -16,13 +16,13 @@
 
 package org.metafacture.flux;
 
+import org.junit.Test;
+import org.metafacture.flux.parser.FluxProgramm;
+
 import java.io.IOException;
 import java.io.OutputStream;
 import java.io.PrintStream;
 
-import org.junit.Test;
-import org.metafacture.flux.parser.FluxProgramm;
-
 /**
  * Tests {@link FluxProgramm}
  *
@@ -33,7 +33,7 @@
 public final class FluxProgrammTest {
 
     @Test
-    public void testCommandRegistration() {
+    public void testCommandRegistration() throws IOException {
         // all commands must properly load to print the help
         FluxProgramm.printHelp(discardOutput());