001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.cli.processor.command;
007
008import dev.metaschema.cli.processor.command.impl.DefaultExtraArgument;
009import edu.umd.cs.findbugs.annotations.NonNull;
010import edu.umd.cs.findbugs.annotations.Nullable;
011
012/**
013 * A representation of an extra, non-option command line argument.
014 */
015public interface ExtraArgument {
016  /**
017   * Create a new extra argument instance.
018   *
019   * @param name
020   *          the argument name
021   * @param required
022   *          {@code true} if the argument is required, or {@code false} otherwise
023   * @return the instance
024   */
025  @NonNull
026  static ExtraArgument newInstance(@NonNull String name, boolean required) {
027    if (name.isBlank()) {
028      throw new IllegalArgumentException("name cannot be empty or blank");
029    }
030    return new DefaultExtraArgument(name, required);
031  }
032
033  /**
034   * Create a new extra argument instance with type information for shell
035   * completion.
036   *
037   * @param name
038   *          the argument name
039   * @param required
040   *          {@code true} if the argument is required, or {@code false} otherwise
041   * @param type
042   *          the type class for completion lookup, or {@code null} for freeform
043   *          input
044   * @return the instance
045   */
046  @NonNull
047  static ExtraArgument newInstance(@NonNull String name, boolean required, @Nullable Class<?> type) {
048    if (name.isBlank()) {
049      throw new IllegalArgumentException("name cannot be empty or blank");
050    }
051    return new DefaultExtraArgument(name, required, type);
052  }
053
054  /**
055   * Get the argument name.
056   *
057   * @return the name
058   */
059  String getName();
060
061  /**
062   * Get if the argument is required.
063   *
064   * @return {@code true} if the argument is required, or {@code false} otherwise
065   */
066  boolean isRequired();
067
068  /**
069   * Get the allow number of arguments of this type.
070   *
071   * @return the allowed number of arguments as a positive number or {@code -1}
072   *         for unlimited
073   */
074  default int getNumber() {
075    return 1;
076  }
077
078  /**
079   * Get the type for shell completion purposes.
080   * <p>
081   * The type is used by
082   * {@link dev.metaschema.cli.processor.completion.CompletionTypeRegistry} to
083   * lookup the appropriate completion behavior for this argument.
084   *
085   * @return the type class used to determine shell completion behavior, or
086   *         {@code null} for freeform input
087   */
088  @Nullable
089  default Class<?> getType() {
090    return null;
091  }
092}