karaf/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java

   1 /**
   2  * Licensed to the Apache Software Foundation (ASF) under one
   3  * or more contributor license agreements. See the NOTICE file
   4  * distributed with this work for additional information
   5  * regarding copyright ownership. The ASF licenses this file
   6  * to you under the Apache License, Version 2.0 (the
   7  * "License"); you may not use this file except in compliance
   8  * with the License. You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing,
  13  * software distributed under the License is distributed on an
  14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15  * KIND, either express or implied. See the License for the
  16  * specific language governing permissions and limitations
  17  * under the License.
  18  */
  19 package org.apache.karaf.tooling.commands;
  20
  21 import java.io.PrintStream;
  22 import java.lang.reflect.Field;
  23 import java.util.ArrayList;
  24 import java.util.HashMap;
  25 import java.util.HashSet;
  26 import java.util.List;
  27 import java.util.Map;
  28 import java.util.Set;
  29
  30 import org.apache.karaf.shell.api.action.Action;
  31 import org.apache.karaf.shell.api.action.Argument;
  32 import org.apache.karaf.shell.api.action.Command;
  33 import org.apache.karaf.shell.api.action.Option;
  34 import org.apache.karaf.shell.impl.action.command.HelpOption;
  35
  36 /**
  37  * Prints documentation in wiki syntax
  38  */
  39 public class UserConfCommandHelpPrinter extends AbstractCommandHelpPrinter {
  40
  41     @Override
  42     public void printHelp(Action action, PrintStream out, boolean includeHelpOption) {
  43         Command command = action.getClass().getAnnotation(Command.class);
  44         Set<Option> options = new HashSet<>();
  45         List<Argument> arguments = new ArrayList<Argument>();
  46         Map<Argument, Field> argFields = new HashMap<>();
  47         Map<Option, Field> optFields = new HashMap<>();
  48         for (Class<?> type = action.getClass(); type != null; type = type.getSuperclass()) {
  49             for (Field field : type.getDeclaredFields()) {
  50                 Option option = field.getAnnotation(Option.class);
  51                 if (option != null) {
  52                     options.add(option);
  53                 }
  54
  55                 Argument argument = field.getAnnotation(Argument.class);
  56                 if (argument != null) {
  57                     argument = replaceDefaultArgument(field, argument);
  58                     argFields.put(argument, field);
  59                     int index = argument.index();
  60                     while (arguments.size() <= index) {
  61                         arguments.add(null);
  62                     }
  63                     if (arguments.get(index) != null) {
  64                         throw new IllegalArgumentException("Duplicate argument index: " + index + " on Action " + action.getClass().getName());
  65                     }
  66                     arguments.set(index, argument);
  67                 }
  68             }
  69         }
  70         if (includeHelpOption)
  71             options.add(HelpOption.HELP);
  72
  73         out.println("h1. " + command.scope() + ":" + command.name());
  74         out.println();
  75
  76         out.println("h2. Description");
  77         out.println(command.description());
  78         out.println();
  79
  80         StringBuffer syntax = new StringBuffer();
  81         syntax.append(String.format("%s:%s", command.scope(), command.name()));
  82         if (options.size() > 0) {
  83             syntax.append(" \\[options\\]");
  84         }
  85         if (arguments.size() > 0) {
  86             syntax.append(' ');
  87             for (Argument argument : arguments) {
  88                 syntax.append(String.format(argument.required() ? "%s " : "\\[%s\\] ", argument.name()));
  89             }
  90         }
  91         out.println("h2. Syntax");
  92         out.println(syntax.toString());
  93         out.println();
  94
  95         if (arguments.size() > 0) {
  96             out.println("h2. Arguments");
  97             out.println("|| Name || Description ||");
  98             for (Argument argument : arguments) {
  99                 String description = argument.description();
 100                 if (!argument.required()) {
 101                     Object o = getDefaultValue(action, argFields.get(argument));
 102                     String defaultValue = getDefaultValueString(o);
 103                     if (defaultValue != null) {
 104                         description += " (defaults to " + o.toString() + ")";
 105                     }
 106                 }
 107                 out.println("| " + argument.name() + " | " + description + " |");
 108             }
 109             out.println();
 110         }
 111         if (options.size() > 0) {
 112             out.println("h2. Options");
 113             out.println("|| Name || Description ||");
 114             for (Option option : options) {
 115                 String opt = option.name();
 116                 String desc = option.description();
 117                 for (String alias : option.aliases()) {
 118                     opt += ", " + alias;
 119                 }
 120                 Object o = getDefaultValue(action, optFields.get(option));
 121                 String defaultValue = getDefaultValueString(o);
 122                 if (defaultValue != null) {
 123                     desc += " (defaults to " + defaultValue + ")";
 124                 }
 125                 out.println("| " + opt + " | " + desc + " |");
 126             }
 127             out.println();
 128         }
 129         if (command.detailedDescription().length() > 0) {
 130             out.println("h2. Details");
 131             out.println(command.detailedDescription());
 132         }
 133         out.println();
 134     }
 135
 136     @Override
 137     public void printOverview(Map<String, Set<String>> commands, PrintStream writer) {
 138         writer.println("h1. Commands");
 139         writer.println();
 140         for (String key : commands.keySet()) {
 141             writer.println("h2. " + key);
 142             writer.println();
 143             for (String cmd : commands.get(key)) {
 144                 writer.println("* [" + key + ":" + cmd + "|" + key + "-" + cmd + "]");
 145             }
 146             writer.println();
 147         }
 148     }
 149
 150 }