command line via annotations

src/main/kotlin/net/keinekekse/args/annotation/api.kt

@@ -0,0 +1,110 @@
+package net.keinekekse.args.annotation
+
+/**
+ * Annotation to define metadata for a command-line argument.
+ *
+ * This annotation can be applied to properties to specify their representation
+ * as command-line arguments. It provides options for defining the argument's
+ * name, shortened single-character alias, description, and whether it is mandatory.
+ *
+ * The property must be declared as mutable and nullable.
+ *
+ * @property name The full name of the command-line argument. Defaults to the name of the property.
+ * @property shortName The single-character alias for the argument. Defaults to [Char.MIN_VALUE],
+ *                     indicating no short name is defined.
+ * @property description A brief description of the argument's purpose. Defaults to an empty string.
+ * @property isMandatory Specifies if the argument is mandatory. Defaults to `false`.
+ */
+@Target(AnnotationTarget.PROPERTY)
+annotation class CmdLineArgument(
+    val name: String = "",
+    val shortName: Char = Char.MIN_VALUE,
+    val description: String = "",
+    val isMandatory: Boolean = false,
+)
+
+/**
+ * Annotation to define a subcommand for a command-line interface.
+ *
+ * This annotation can be applied to objects to designate them as subcommands
+ * for a command-line tool. It specifies the subcommand's name, a brief description,
+ * and optional aliases that can be used to invoke the subcommand.
+ *
+ * @property name The primary identifier for the subcommand. Defaults to the simple name of the class.
+ * @property description A short description of the subcommand's purpose. Defaults to an empty string.
+ * @property aliases Alternative names that can be used to invoke the subcommand. Defaults to an
+ *                   empty array.
+ */
+@Target(AnnotationTarget.CLASS)
+annotation class CmdLineSubCommand(
+    val name: String = "",
+    val description: String = "",
+    val aliases: Array<String> = [],
+)
+
+/**
+ * Represents a set of parameters associated globally with the program.
+ * This class adds additional properties and customization options to manage
+ * the behavior of the command line interpretation, such as allowing additional parameters,
+ * handling case sensitivity, and keeping track of command execution status.
+ *
+ * The parameters have to be annotated with the [CmdLineArgument] annotation.
+ * Subcommands can be defined using the [CmdLineSubCommand] annotation on objects,
+ * derived from the [SubCommand] class.
+ *
+ * @property programDescription A description of the program's purpose or functionality.
+ * @property additionalParametersAllowed Indicates whether the program allows additional,
+ *                                        unspecified parameters during execution.
+ * @property ignoreCase Determines if parameter matching should be case-insensitive.
+ */
+abstract class Parameters(
+    val programDescription: String = "",
+    val additionalParametersAllowed: Boolean = true,
+    val ignoreCase: Boolean = false,
+    var didRun: Boolean = false,
+) : SubCommand()
+
+/**
+ * Represents an abstract subcommand that can be executed with specific behavior and validation logic.
+ *
+ * Subclasses of this class are expected to provide implementation for validating their parameters
+ * and defining the execution logic of the subcommand. Each subcommand can also handle additional
+ * parameters.
+ *
+ * @property additionalParameters A list of additional command line parameters associated with this
+ *                                subcommand.
+ */
+abstract class SubCommand {
+    var additionalParameters: List<String> = emptyList()
+
+    abstract fun verifyParameters(): Boolean
+    abstract fun run(globals: Parameters)
+}
+
+/**
+ * Executes the program logic using the specified command-line arguments.
+ * This method internally invokes the `run` method of the `Parameters` class
+ * to parse, validate, and execute the input arguments.
+ *
+ * @param args A list of command-line arguments to be processed by the program.
+ */
+fun Parameters.runProgramWith(args: List<String>) {
+    run(args)
+}
+
+/**
+ * Exception thrown to indicate that there is an error related to verifying
+ * the validity of command-line parameters provided to the application.
+ *
+ * This exception is thrown by the [SubCommand.verifyParameters] method to indicate
+ * that the parameters provided to the subcommand are invalid.
+ *
+ * The exception is caught by the [Parameters.runProgramWith] method and the program
+ * execution will be terminated with an error message and the usage information.
+ *
+ * @constructor
+ * Constructs a new [VerifyParameterException] with the specified detail message.
+ *
+ * @param message The detail message describing the parameter verification error.
+ */
+class VerifyParameterException(message: String) : RuntimeException(message)