EventUsageFormatter.java

package client.teavm.common.parameter.usage;

import com.beust.jcommander.*;
import com.beust.jcommander.internal.Lists;

import java.util.*;
import java.util.ResourceBundle;

/**
 * Change the usage message to represent web worker events. Each event is modeled as
 * a command. Returned event is treated like a main argument and event data as
 * options. The purpose is to give some useful documentation to the user.
 *
 * @author khaendel
 *
 */
public class EventUsageFormatter extends DefaultUsageFormatter {

    private final JCommander commander;
    private final boolean isExport;
    private final ResourceBundle bundle;

    public EventUsageFormatter(JCommander commander, boolean isExport) {
        super(commander);
        this.commander = commander;
        this.isExport = isExport;
        this.bundle = getBundle();
    }

    @Override
    public void appendMainLine(StringBuilder out, boolean hasOptions, boolean hasCommands, int indentCount,
                               String indent) {
        if (isExport && !hasCommands) {
            out.append("\n");
            out.append(indent).append("Usage: \n");
            if (commander.getFields().values().stream().filter(pd -> !pd.getParameter().hidden()).anyMatch(pd -> !pd.getParameter().isHelp())) {
                out.append(indent).append("  $ worker.postMessage({ eventType: \"");
                out.append(commander.getProgramDisplayName());
                out.append("\", eventData: { EventData } })");
            } else {
                out.append(indent).append("  $ worker.postMessage({ eventType: \"");
                out.append(commander.getProgramDisplayName());
                out.append("\" })");
            }
            out.append("\n");
        }

        if (commander.getMainParameter() != null && commander.getMainParameterValue() != null) {
            appendReturnedEvent(out, indentCount, indent);
        }
    }

    @Override
    public void appendAllParametersDetails(StringBuilder out, int indentCount, String indent,
                                           List<ParameterDescription> sortedParameters) {
        if (!sortedParameters.isEmpty()) {
            out.append("\n");
            out.append(indent).append("EventData:\n");
        }

        for (ParameterDescription pd : sortedParameters) {
            WrappedParameter parameter = pd.getParameter();

            if (pd.getParameter().hidden() || pd.getParameter().isHelp()) {
                continue;
            }
            String description = pd.getDescription();
            boolean hasDescription = !description.isEmpty();

            // First line, command name
            out.append(indent).append("  ").append(parameter.required() ? "* " : "  ")
                    .append(getEventDataParameterNames(pd.getNames())).append("\n");

            if (hasDescription) {
                wrapDescription(out, indentCount, s(indentCount) + description);
            }
            Object def = pd.getDefault();

            if (pd.isDynamicParameter()) {
                String syntax = "Syntax: " + parameter.names()[0] + "key" + parameter.getAssignment() + "value";

                if (hasDescription) {
                    out.append(newLineAndIndent(indentCount));
                } else {
                    out.append(s(indentCount));
                }
                out.append(syntax);
            }

            if (isExport && def != null && !pd.isHelp()) {
                String displayedDef = Strings.isStringEmpty(def.toString()) ? "<empty string>" : def.toString();
                String defaultText = "Default: " + (parameter.password() ? "********" : displayedDef);

                if (hasDescription) {
                    out.append(newLineAndIndent(indentCount));
                } else {
                    out.append(s(indentCount));
                }
                out.append(defaultText);
            }
            Class<?> type = pd.getParameterized().getType();

            if (type.isEnum()) {
                @SuppressWarnings({"unchecked", "rawtypes"})
                String valueList = EnumSet.allOf((Class<? extends Enum>) type).toString();
                String possibleValues = "Possible Values: " + valueList;

                // Prevent a duplicate values list, since it is set as 'Options: [values]' if the
                // description
                // of an enum field is empty in ParameterDescription#init(..)
                if (!description.contains("Options: " + valueList)) {
                    if (hasDescription) {
                        out.append(newLineAndIndent(indentCount));
                    } else {
                        out.append(s(indentCount));
                    }
                    out.append(possibleValues);
                }
            }
            out.append("\n");
        }
    }

    public void usage(StringBuilder out, String indent) {
        if (commander.getDescriptions() == null) {
            commander.createDescriptions();
        }
        boolean hasCommands = !commander.getCommands().isEmpty();
        boolean hasOptions = !commander.getDescriptions().isEmpty();

        // Indentation constants
        final int descriptionIndent = 6;
        final int indentCount = indent.length() + descriptionIndent;

        // Append the first line (aka main line) of the usage
        appendMainLine(out, hasOptions, hasCommands, indentCount, indent);

        // Align the descriptions at the "longestName" column
        int longestName = 0;
        List<ParameterDescription> sortedParameters = Lists.newArrayList();

        for (ParameterDescription pd : commander.getFields().values()) {
            if (!pd.getParameter().hidden() && !pd.getParameter().isHelp()) {
                sortedParameters.add(pd);
                // + to have an extra space between the name and the description
                int length = pd.getNames().length() + 2;

                if (length > longestName) {
                    longestName = length;
                }
            }
        }

        // Sort the options
        sortedParameters.sort(commander.getParameterDescriptionComparator());

        // Append all the parameter names and descriptions
        appendAllParametersDetails(out, indentCount, indent, sortedParameters);

        // Append commands if they were specified
        if (hasCommands) {
            appendCommands(out, indentCount, descriptionIndent, indent);
        }
    }

    public void appendCommands(StringBuilder out, int indentCount, int descriptionIndent, String indent) {
        boolean hasOnlyHiddenCommands = true;
        for (Map.Entry<JCommander.ProgramName, JCommander> commands : commander.getRawCommands().entrySet()) {
            Object arg = commands.getValue().getObjects().get(0);
            Parameters p = arg.getClass().getAnnotation(Parameters.class);

            if (p == null || !p.hidden()) {
                hasOnlyHiddenCommands = false;
                break;
            }
        }

        if (hasOnlyHiddenCommands)
            return;

        out.append("\n");
        out.append("\n");
        out.append(bundle.getString("USAGE_DESCRIPTION"));
        out.append("\n");

        // Magic value 3 is the number of spaces between the name of the option and
        // its description
        for (Map.Entry<JCommander.ProgramName, JCommander> commands : commander.getRawCommands().entrySet()) {
            Object arg = commands.getValue().getObjects().get(0);
            Parameters p = arg.getClass().getAnnotation(Parameters.class);

            if (p == null || !p.hidden()) {
                JCommander.ProgramName progName = commands.getKey();
                String dispName = progName.getDisplayName();
                String description = indent + s(4) + dispName + s(6) + getCommandDescription(progName.getName());
                wrapDescription(out, indentCount + descriptionIndent, description);
                out.append("\n");

                // Options for this command
                JCommander jc = commander.findCommandByAlias(progName.getName());
                jc.setUsageFormatter(new EventUsageFormatter(jc, isExport));
                jc.getUsageFormatter().usage(out, indent + s(6));
                out.append("\n");
            }
        }
    }

    private void appendReturnedEvent(StringBuilder out, int indentCount, String indent) {
        out.append(indent).append("  Fires Event: ");
        out.append(commander.getMainParameterValue().getDescription());
        out.append("\n");
    }

    private ResourceBundle getBundle() {
        Object firstParameterObject = commander.getObjects().get(0);
        Parameters parameters = firstParameterObject.getClass().getAnnotation(Parameters.class);
        return ResourceBundle.getBundle(parameters.resourceBundle(), Locale.getDefault());
    }

    private String getEventDataParameterNames(String names) {
        return String.join(", ", names.split(", "));
    }

    /**
     * Returns a new line followed by indent-many spaces.
     *
     * @return new line followed by indent-many spaces
     */
    private static String newLineAndIndent(int indent) {
        return "\n" + s(indent);
    }

}