karaf/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.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 org.apache.karaf.shell.api.action.Action;
  22 import org.apache.karaf.shell.api.action.Argument;
  23 import org.apache.karaf.shell.api.action.Command;
  24 import org.apache.karaf.shell.api.action.Option;
  25 import org.apache.karaf.shell.impl.action.command.HelpOption;
  26
  27 import java.io.PrintStream;
  28 import java.lang.reflect.Field;
  29 import java.util.*;
  30
  31 /**
  32  * Prints documentation in asciidoc syntax
  33  */
  34 public class AsciiDoctorCommandHelpPrinter extends AbstractCommandHelpPrinter {
  35
  36     @Override
  37     public void printHelp(Action action, PrintStream out, boolean includeHelpOption) {
  38         Command command = action.getClass().getAnnotation(Command.class);
  39         Set<Option> options = new HashSet<>();
  40         List<Argument> arguments = new ArrayList<Argument>();
  41         Map<Argument, Field> argFields = new HashMap<>();
  42         Map<Option, Field> optFields = new HashMap<>();
  43         for (Class<?> type = action.getClass(); type != null; type = type.getSuperclass()) {
  44             for (Field field : type.getDeclaredFields()) {
  45                 Option option = field.getAnnotation(Option.class);
  46                 if (option != null) {
  47                     options.add(option);
  48                 }
  49
  50                 Argument argument = field.getAnnotation(Argument.class);
  51                 if (argument != null) {
  52                     argument = replaceDefaultArgument(field, argument);
  53                     argFields.put(argument, field);
  54                     int index = argument.index();
  55                     while (arguments.size() <= index) {
  56                         arguments.add(null);
  57                     }
  58                     if (arguments.get(index) != null) {
  59                         throw new IllegalArgumentException("Duplicate argument index: " + index + " on Action " + action.getClass().getName());
  60                     }
  61                     arguments.set(index, argument);
  62                 }
  63             }
  64         }
  65         if (includeHelpOption)
  66             options.add(HelpOption.HELP);
  67
  68         out.println("= " + command.scope() + ":" + command.name());
  69         out.println();
  70
  71         out.println("== Description");
  72         out.println();
  73         out.println(command.description());
  74         out.println();
  75
  76         StringBuffer syntax = new StringBuffer();
  77         syntax.append(String.format("%s:%s", command.scope(), command.name()));
  78         if (options.size() > 0) {
  79             syntax.append(" [options]");
  80         }
  81         if (arguments.size() > 0) {
  82             syntax.append(' ');
  83             for (Argument argument : arguments) {
  84                 syntax.append(String.format(argument.required() ? "%s " : "[%s] ", argument.name()));
  85             }
  86         }
  87         out.println("== Syntax");
  88         out.println();
  89         out.println(syntax.toString());
  90         out.println();
  91
  92         if (arguments.size() > 0) {
  93             out.println("== Arguments");
  94             out.println();
  95             out.println("|===");
  96             out.println("|Name |Description");
  97             for (Argument argument : arguments) {
  98                 String description = argument.description();
  99                 if (!argument.required()) {
 100                     Object o = getDefaultValue(action, argFields.get(argument));
 101                     String defaultValue = getDefaultValueString(o);
 102                     if (defaultValue != null) {
 103                         description += " (defaults to " + o.toString() + ")";
 104                     }
 105                 }
 106                 out.println();
 107                 out.println("| " + argument.name());
 108                 out.println("| " + description);
 109             }
 110             out.println("|===");
 111             out.println();
 112         }
 113         if (options.size() > 0) {
 114             out.println("== Options");
 115             out.println();
 116             out.println("|===");
 117             out.println("|Name |Description");
 118             for (Option option : options) {
 119                 String opt = option.name();
 120                 String desc = option.description();
 121                 for (String alias : option.aliases()) {
 122                     opt += ", " + alias;
 123                 }
 124                 Object o = getDefaultValue(action, optFields.get(option));
 125                 String defaultValue = getDefaultValueString(o);
 126                 if (defaultValue != null) {
 127                     desc += " (defaults to " + defaultValue + ")";
 128                 }
 129                 out.println();
 130                 out.println("|" + opt);
 131                 out.println("|" + desc);
 132             }
 133             out.println("|===");
 134             out.println();
 135         }
 136         if (command.detailedDescription().length() > 0) {
 137             out.println("== Details");
 138             out.println();
 139             out.println(command.detailedDescription());
 140         }
 141         out.println();
 142     }
 143
 144     @Override
 145     public void printOverview(Map<String, Set<String>> commands, PrintStream writer) {
 146         writer.println("= Commands");
 147         writer.println();
 148         for (String key : commands.keySet()) {
 149             writer.println("== " + key);
 150             writer.println();
 151             for (String cmd : commands.get(key)) {
 152                 writer.println("* [" + key + ":" + cmd + "|" + key + "-" + cmd + "]");
 153             }
 154             writer.println();
 155         }
 156     }
 157
 158 }