1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.cli.processor.command;
7   
8   import dev.metaschema.cli.processor.command.impl.DefaultExtraArgument;
9   import edu.umd.cs.findbugs.annotations.NonNull;
10  import edu.umd.cs.findbugs.annotations.Nullable;
11  
12  /**
13   * A representation of an extra, non-option command line argument.
14   */
15  public interface ExtraArgument {
16    /**
17     * Create a new extra argument instance.
18     *
19     * @param name
20     *          the argument name
21     * @param required
22     *          {@code true} if the argument is required, or {@code false} otherwise
23     * @return the instance
24     */
25    @NonNull
26    static ExtraArgument newInstance(@NonNull String name, boolean required) {
27      if (name.isBlank()) {
28        throw new IllegalArgumentException("name cannot be empty or blank");
29      }
30      return new DefaultExtraArgument(name, required);
31    }
32  
33    /**
34     * Create a new extra argument instance with type information for shell
35     * completion.
36     *
37     * @param name
38     *          the argument name
39     * @param required
40     *          {@code true} if the argument is required, or {@code false} otherwise
41     * @param type
42     *          the type class for completion lookup, or {@code null} for freeform
43     *          input
44     * @return the instance
45     */
46    @NonNull
47    static ExtraArgument newInstance(@NonNull String name, boolean required, @Nullable Class<?> type) {
48      if (name.isBlank()) {
49        throw new IllegalArgumentException("name cannot be empty or blank");
50      }
51      return new DefaultExtraArgument(name, required, type);
52    }
53  
54    /**
55     * Get the argument name.
56     *
57     * @return the name
58     */
59    String getName();
60  
61    /**
62     * Get if the argument is required.
63     *
64     * @return {@code true} if the argument is required, or {@code false} otherwise
65     */
66    boolean isRequired();
67  
68    /**
69     * Get the allow number of arguments of this type.
70     *
71     * @return the allowed number of arguments as a positive number or {@code -1}
72     *         for unlimited
73     */
74    default int getNumber() {
75      return 1;
76    }
77  
78    /**
79     * Get the type for shell completion purposes.
80     * <p>
81     * The type is used by
82     * {@link dev.metaschema.cli.processor.completion.CompletionTypeRegistry} to
83     * lookup the appropriate completion behavior for this argument.
84     *
85     * @return the type class used to determine shell completion behavior, or
86     *         {@code null} for freeform input
87     */
88    @Nullable
89    default Class<?> getType() {
90      return null;
91    }
92  }