Merge pull request #2965 from idodeclare/feature/better_help

Improve configuration help

Author: tarzanek

opengrok-indexer/src/main/java/org/opengrok/indexer/analysis/AnalyzerGuruHelp.java

@@ -18,11 +18,13 @@
  */
 
 /*
- * Copyright (c) 2017-2018, Chris Fraire <[email protected]>.
+ * Copyright (c) 2017-2019, Chris Fraire <[email protected]>.
  */
 
 package org.opengrok.indexer.analysis;
 
+import org.opengrok.indexer.util.StringUtils;
+
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
@@ -141,7 +143,7 @@ private static String[] splitLines(String str, int width) {
         int llen = 0;
         int i = 0;
         while (i < str.length()) {
-            int wlen = nextTestWhitespaceLength(false, str, i);
+            int wlen = StringUtils.whitespaceOrControlLength(str, i, false);
             if (wlen > 0) {
                 String word = str.substring(i, i + wlen);
                 if (llen < 1) {
@@ -160,7 +162,7 @@ private static String[] splitLines(String str, int width) {
                 i += wlen;
             }
 
-            int slen = nextTestWhitespaceLength(true, str, i);
+            int slen = StringUtils.whitespaceOrControlLength(str, i, true);
             i += slen;
         }
         if (b.length() > 0) {
@@ -171,20 +173,6 @@ private static String[] splitLines(String str, int width) {
         return res.stream().toArray(String[]::new);
     }
 
-    private static int nextTestWhitespaceLength(boolean match, String str,
-        int off) {
-        int i = 0;
-        while (off + i < str.length()) {
-            int cp = Character.codePointAt(str, off + i);
-            if ((Character.isWhitespace(cp) || Character.isISOControl(cp)) !=
-                match) {
-                return i;
-            }
-            i += Character.charCount(cp);
-        }
-        return str.length() - off;
-    }
-
     private static List<MappedFactory> byKey(
         Map<String, AnalyzerFactory> mapped) {
 

opengrok-indexer/src/main/java/org/opengrok/indexer/configuration/ConfigurationHelp.java

@@ -18,7 +18,7 @@
  */
 
 /*
- * Copyright (c) 2018, Chris Fraire <[email protected]>.
+ * Copyright (c) 2018-2019, Chris Fraire <[email protected]>.
  */
 
 package org.opengrok.indexer.configuration;
@@ -41,13 +41,16 @@
 import org.opengrok.indexer.history.RepositoryInfo;
 import org.opengrok.indexer.index.Filter;
 import org.opengrok.indexer.index.IgnoredNames;
+import org.opengrok.indexer.util.StringUtils;
 
 /**
  * Represents a utility class to present some user-readable help regarding
  * {@link Configuration}.
  */
 public class ConfigurationHelp {
 
+    private static final String XML_COMMENT_START = "  <!-- ";
+
     private ConfigurationHelp() {
     }
 
@@ -64,6 +67,8 @@ public static String getSamples()
         Class klass = conf.getClass();
 
         StringBuilder b = new StringBuilder();
+        LinesBuilder h = new LinesBuilder();
+
         b.append("Configuration examples:\n");
         b.append("\n");
 
@@ -96,12 +101,16 @@ public static String getSamples()
                 "(?sx)^<\\?xml.*Configuration\\d*\">\\n", "");
             sample = sample.replaceFirst("</object>\\n</java>", "");
 
-            b.append("  <!-- Sample for ");
-            b.append(mthd.getName());
-            b.append(". Default is: ");
-            b.append(defaultValue);
-            b.append(" -->");
-            b.append("\n");
+            h.clear();
+            h.append(XML_COMMENT_START);
+            h.append("Sample for ");
+            h.append(mthd.getName());
+            h.append(". Default is ");
+            h.appendWords(defaultValue);
+            h.appendWords(" -->");
+            h.appendLine();
+
+            b.append(h);
             b.append(sample);
         }
         return b.toString();
@@ -119,10 +128,7 @@ private static List<Method> getSetters(Class klass) {
                 res.add(mth);
             }
         }
-        res.sort((o1, o2) -> {
-            int cmp = o1.getName().compareToIgnoreCase(o2.getName());
-            return cmp;
-        });
+        res.sort((o1, o2) -> o1.getName().compareToIgnoreCase(o2.getName()));
         return res;
     }
 
@@ -182,7 +188,7 @@ private static Object getSampleValue(Method setter, Object defaultValue) {
             }
             return null;
         } else if (paramType == SuggesterConfig.class) {
-            return new SuggesterConfig();
+            return SuggesterConfig.getForHelp();
         } else {
             throw new UnsupportedOperationException("getSampleValue() for " +
                 paramType + ", " + genType);
@@ -195,12 +201,11 @@ private static Object getSampleListValue(Type genType) {
         }
         ParameterizedType genParamType = (ParameterizedType) genType;
         Type actType = genParamType.getActualTypeArguments()[0];
-        Object res = null;
 
         if (actType != RepositoryInfo.class) {
             throw new UnsupportedOperationException("Not supported yet for " + actType);
         }
-        return res;
+        return null;
     }
 
     private static Object getSampleMapValue(Type genType) {
@@ -211,7 +216,7 @@ private static Object getSampleMapValue(Type genType) {
         Type[] actualTypeArguments = genParamType.getActualTypeArguments();
         Type actType0 = actualTypeArguments[0];
         Type actType1 = actualTypeArguments[1];
-        Object res = null;
+        Object res;
 
         if (actType0 == String.class) {
             if (actType1 == String.class) {
@@ -240,7 +245,7 @@ private static Object getSampleSetValue(Type genType) {
         }
         ParameterizedType genParamType = (ParameterizedType) genType;
         Type actType = genParamType.getActualTypeArguments()[0];
-        Object res = null;
+        Object res;
 
         if (actType == String.class) {
             Set<String> strset = new HashSet<>();
@@ -286,6 +291,19 @@ private static Object getDefaultValue(Class<?> klass, Method setter,
             }
         }
 
+        // Return a text override for some objects.
+        switch (gname) {
+            case "getSuggesterConfig":
+                return "as below but with Boolean opposites, non-zeroes decremented by 1, null " +
+                        "for allowed-projects, and also including \"full\" in allowed-fields";
+            case "getPluginStack":
+                return "an empty stack";
+            case "getIncludedNames":
+                return "an empty filter";
+            case "getIgnoredNames":
+                return "OpenGrok's standard set of ignored files and directories";
+        }
+
         try {
             return getter.invoke(cinst);
         } catch (IllegalAccessException | IllegalArgumentException | InvocationTargetException ex) {
@@ -301,4 +319,69 @@ private static boolean isDeprecated(Method mth) {
         }
         return false;
     }
+
+    private static class LinesBuilder {
+        static final int LINE_LENGTH = 80;
+
+        final StringBuilder b = new StringBuilder();
+        int length;
+
+        void clear() {
+            b.setLength(0);
+            length = 0;
+        }
+
+        void append(String value) {
+            b.append(value);
+            length += value.length();
+        }
+
+        void appendWords(Object value) {
+            if (value == null) {
+                appendWords("null");
+            } else {
+                appendWords(value.toString());
+            }
+        }
+
+        void appendWords(String value) {
+            if (length > LINE_LENGTH) {
+                appendLine();
+            }
+
+            int i = 0;
+            while (true) {
+                int spaceLen = StringUtils.whitespaceOrControlLength(value, i, true);
+                int wordLen = StringUtils.whitespaceOrControlLength(value, i + spaceLen, false);
+
+                if (wordLen < 1) {
+                    break;
+                }
+
+                String word = value.substring(i + spaceLen, i + spaceLen + wordLen);
+                if (length + spaceLen + wordLen > LINE_LENGTH) {
+                    appendLine();
+                    for (int j = 0; j < XML_COMMENT_START.length(); ++j) {
+                        append(" ");
+                    }
+                    append(word);
+                } else {
+                    append(value.substring(i, i + spaceLen));
+                    append(word);
+                }
+
+                i += spaceLen + wordLen;
+            }
+        }
+
+        void appendLine() {
+            b.append("\n");
+            length = 0;
+        }
+
+        @Override
+        public String toString() {
+            return b.toString();
+        }
+    }
 }

opengrok-indexer/src/main/java/org/opengrok/indexer/configuration/SuggesterConfig.java

@@ -19,6 +19,7 @@
 
 /*
  * Copyright (c) 2018 Oracle and/or its affiliates. All rights reserved.
+ * Portions Copyright (c) 2019, Chris Fraire <[email protected]>.
  */
 package org.opengrok.indexer.configuration;
 
@@ -41,7 +42,7 @@ public class SuggesterConfig {
     public static final boolean ENABLED_DEFAULT = true;
     public static final int MAX_RESULTS_DEFAULT = 10;
     public static final int MIN_CHARS_DEFAULT = 0;
-    public static final int MAX_PROJECTS_DEFAULT = Integer.MAX_VALUE;
+    public static final int MAX_PROJECTS_DEFAULT = Short.MAX_VALUE;
     public static final boolean ALLOW_COMPLEX_QUERIES_DEFAULT = true;
     public static final boolean ALLOW_MOST_POPULAR_DEFAULT = true;
     public static final boolean SHOW_SCORES_DEFAULT = false;
@@ -335,4 +336,33 @@ public int hashCode() {
                 buildTerminationTime, rebuildThreadPoolSizeInNcpuPercent);
     }
 
+    /**
+     * Gets an instance version suitable for helper documentation by shifting
+     * most default properties slightly.
+     */
+    static SuggesterConfig getForHelp() {
+        SuggesterConfig res = new SuggesterConfig();
+        res.setEnabled(!res.isEnabled());
+        res.setMaxResults(1 + res.getMaxResults());
+        res.setMinChars(1 + res.getMinChars());
+        res.setAllowedProjects(new HashSet<>(Arrays.asList("project-1", "project-2")));
+        res.setMaxProjects(1 + res.getMaxProjects());
+        res.setAllowedFields(getAllowedFieldsForHelp(res.getAllowedFields()));
+        res.setAllowComplexQueries(!res.isAllowComplexQueries());
+        res.setAllowMostPopular(!res.isAllowMostPopular());
+        res.setShowScores(!res.isShowScores());
+        res.setShowProjects(!res.isShowProjects());
+        res.setShowTime(!res.isShowTime());
+        res.setTimeThreshold(1 + res.getTimeThreshold());
+        res.setRebuildCronConfig("1 0 * * *");
+        res.setBuildTerminationTime(1 + res.getBuildTerminationTime());
+        res.setRebuildThreadPoolSizeInNcpuPercent(1 + res.getRebuildThreadPoolSizeInNcpuPercent());
+        return res;
+    }
+
+    private static HashSet<String> getAllowedFieldsForHelp(Set<String> allowedFields) {
+        HashSet<String> res = new HashSet<>(allowedFields);
+        res.remove(QueryBuilder.FULL);
+        return res;
+    }
 }

opengrok-indexer/src/main/java/org/opengrok/indexer/index/IgnoredNames.java

@@ -19,6 +19,7 @@
 
 /*
  * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Portions Copyright (c) 2019, Chris Fraire <[email protected]>.
  */
 package org.opengrok.indexer.index;
 
@@ -34,6 +35,8 @@
  */
 public class IgnoredNames implements Serializable {
     private static final long serialVersionUID = 1L;
+    private static final String FILE_PREFIX = "f:";
+    private static final String DIR_PREFIX = "d:";
 
     private IgnoredFiles ignoredFiles;
     private IgnoredDirs ignoredDirs;
@@ -58,10 +61,10 @@ public void setItems(List<String> item) {
     }
 
     public void add(String pattern) {
-        if (pattern.startsWith("f:")) {
-            ignoredFiles.add(pattern.substring(2));
-        } else if (pattern.startsWith("d:")) {
-            ignoredDirs.add(pattern.substring(2));
+        if (pattern.startsWith(FILE_PREFIX)) {
+            ignoredFiles.add(pattern.substring(FILE_PREFIX.length()));
+        } else if (pattern.startsWith(DIR_PREFIX)) {
+            ignoredDirs.add(pattern.substring(DIR_PREFIX.length()));
         } else {
             // backward compatibility
             ignoredFiles.add(pattern);

opengrok-indexer/src/main/java/org/opengrok/indexer/util/StringUtils.java

@@ -19,7 +19,7 @@
 
 /*
  * Copyright (c) 2008, 2018, Oracle and/or its affiliates. All rights reserved.
- * Portions Copyright (c) 2017-2018, Chris Fraire <[email protected]>.
+ * Portions Copyright (c) 2017-2019, Chris Fraire <[email protected]>.
  */
 
 package org.opengrok.indexer.util;
@@ -299,4 +299,27 @@ public static int countPushback(String capture, Pattern pat) {
         }
         return 0;
     }
+
+    /**
+     * Determine the length of the next whitespace- or ISO control
+     * character-related sequence within a string.
+     * @param str a defined instance
+     * @param off the starting offset within {@code str}
+     * @param shouldMatch a value indicating whether to match all contiguous
+     *                    whitespace or ISO control characters ({@code true}) or
+     *                    all contiguous non-whitespace and non-control
+     *                    characters ({@code false}) starting at {@code off}
+     * @return a length greater than or equal to zero
+     */
+    public static int whitespaceOrControlLength(String str, int off, boolean shouldMatch) {
+        int i = 0;
+        while (off + i < str.length()) {
+            int cp = Character.codePointAt(str, off + i);
+            if ((Character.isWhitespace(cp) || Character.isISOControl(cp)) != shouldMatch) {
+                return i;
+            }
+            i += Character.charCount(cp);
+        }
+        return str.length() - off;
+    }
 }