karaf/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.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 docbook syntax
  38  */
  39 public class DocBookCommandHelpPrinter 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("<section>");
  74         out.println("  <title>" + command.scope() + ":" + command.name() + "</title>");
  75         out.println("  <section>");
  76         out.println("    <title>Description</title>");
  77         out.println("    <para>");
  78         out.println(command.description());
  79         out.println("    </para>");
  80         out.println("  </section>");
  81
  82         StringBuffer syntax = new StringBuffer();
  83         syntax.append(String.format("%s:%s", command.scope(), command.name()));
  84         if (options.size() > 0) {
  85             syntax.append(" [options]");
  86         }
  87         if (arguments.size() > 0) {
  88             syntax.append(' ');
  89             for (Argument argument : arguments) {
  90                 syntax.append(String.format(argument.required() ? "%s " : "[%s] ", argument.name()));
  91             }
  92         }
  93         out.println("  <section>");
  94         out.println("    <title>Syntax</title>");
  95         out.println("    <para>");
  96         out.println(syntax.toString());
  97         out.println("    </para>");
  98         out.println("  </section>");
  99
 100         if (arguments.size() > 0) {
 101             out.println("  <section>");
 102             out.println("    <title>Arguments</title>");
 103             out.println("    <informaltable>");
 104             for (Argument argument : arguments) {
 105                 out.println("    <tr>");
 106                 out.println("      <td>" + argument.name() + "</td>");
 107                 String description = argument.description();
 108                 if (!argument.required()) {
 109                     if (argument.valueToShowInHelp() != null && argument.valueToShowInHelp().length() != 0) {
 110                         if (Argument.DEFAULT_STRING.equals(argument.valueToShowInHelp())) {
 111                             Object o = getDefaultValue(action, argFields.get(argument));
 112                             String defaultValue = getDefaultValueString(o);
 113                             if (defaultValue != null) {
 114                                 description += " (defaults to " + o.toString() + ")";
 115                             }
 116                         }
 117                     }
 118                 }
 119                 out.println("      <td>" + description + "</td>");
 120                 out.println("    </tr>");
 121             }
 122
 123             out.println("    </informaltable>");
 124             out.println("  </section>");
 125         }
 126
 127         if (options.size() > 0) {
 128             out.println("  <section>");
 129             out.println("    <title>Options</title>");
 130             out.println("    <informaltable>");
 131
 132             for (Option option : options) {
 133                 String opt = option.name();
 134                 String description = option.description();
 135                 for (String alias : option.aliases()) {
 136                     opt += ", " + alias;
 137                 }
 138                 Object o = getDefaultValue(action, optFields.get(option));
 139                 String defaultValue = getDefaultValueString(o);
 140                 if (defaultValue != null) {
 141                     description += " (defaults to " + o.toString() + ")";
 142                 }
 143                 out.println("    <tr>");
 144                 out.println("      <td>" + opt + "</td>");
 145                 out.println("      <td>" + description + "</td>");
 146                 out.println("    </tr>");
 147             }
 148
 149             out.println("    </informaltable>");
 150             out.println("  </section>");
 151         }
 152
 153         if (command.detailedDescription().length() > 0) {
 154             out.println("  <section>");
 155             out.println("    <title>Details</title>");
 156             out.println("    <para>");
 157             out.println(command.detailedDescription());
 158             out.println("    </para>");
 159             out.println("  </section>");
 160         }
 161         out.println("</section>");
 162     }
 163
 164     @Override
 165     public void printOverview(Map<String, Set<String>> commands, PrintStream writer) {
 166         writer.println("<chapter id='commands' xmlns:xi=\"http://www.w3.org/2001/XInclude\">");
 167         writer.println("  <title>Commands</title>");
 168         writer.println("  <toc></toc>");
 169         for (String key : commands.keySet()) {
 170             writer.println("  <section id='commands-" + key + "'>");
 171             writer.println("    <title>" + key + "</title>");
 172             for (String cmd : commands.get(key)) {
 173                 writer.println("    <xi:include href='" + key + "-" + cmd + ".xml' parse='xml'/>");
 174             }
 175             writer.println("  </section>");
 176         }
 177         writer.println("</chapter>");
 178     }
 179
 180 }