Home

Overview

Welcome to the kommandant project wiki!

Here you may find useful information regarding how to use this library.

Kommandant is Lightweight

The core module of the library requires the bare minimum in terms of dependencies to make it as lightweight as possible. It requires only a SLF4J logger implementation and Kotlin v1.10 or higher (including kotlin-stdlib-jre8 and kotlin-reflect).

How it works

What constitutes a command?

A command is simply a container holding information about how it can be executed and what its execution function or method is. A command's execution function can either return no value, or possibly return a value once executed (generic type T).

Commands are processed for and activated by combining its prefix activator and a valid alias. For example, a command with prefix set as - and aliases [ help, h, hlp ] can be activated by providing the strings: -help, or -h, or -hlp. Extra arguments can be also passed to the command, for example -help 123 where 123 is an extra argument visible to the command.

Instead of extra arguments, commands can also have subcommands which when activated, perform different tasks than the main command. For example, if task was a subcommand of -help, calling -help task would execute task, but calling -task by itself would do nothing.

In terms of classes and interfaces:

• A command is represented by an abstract class ICommand implementing ICommandExecutable
  • An ICommand contains CommandProperties which hold information about the command, i.e. a command's activation prefix, its unique name identifier, its description, its usage instructions, and the aliases used to activate it.
  • ICommandExecutable is the interface representing a command's executable function or method. It contains a single method execute which takes in the following two parameters:
    1. CommandContext: A container class which holds information regarding the alias used to activate the command and any additional arguments passed to the command
    2. vararg optional: Any? (Kotlin) / Object... optional (Java): An optional usage parameter, useful if a command requires other objects or resources to use or modify in order to successfully complete execution. Evidently, after passing in an object's instance into the command, it requires casting. For commands requiring a lot of additional objects passed in as parameters, this can be simplified by creating a command class that extends the abstract ICommand class and implementing a new interface similar to ICommandExecutor with explicitly stated parameters.

The Kommandant class is the central system of the framework. It is an aggregation that links together the following 3 mechanisms:

1. A command bank / registry (ICommandBank interface), for registering commands to the system.
2. A command executor / activator (ICommandExecutor interface), for executing a command's main function.
3. A command parser (ICommandParser interface), for creating commands outside of the normal way (i.e. constructors, or builder classes), such as creating a command through annotation processing on runtime.

An ICommand can be created in one of three ways:

1. Through its constructor (least recommended as it's the most verbose)
2. Through the CommandBuilder class
3. Through the use of CommandAnn annotations in an external class targeting methods with the same signature as the execute method from the ICommandExecutor interface

Commands may be added to the registry using Kommandant#addCommand on a command or, if using annotations, using Kommandant#addAnnotatedCommands on a class or object instance containing said annotations.