🔖 Framework de Comandos para o PerfectDreams 🔖

^{Desenho feito por 💀Hiro🐦#3360}

Apenas mais outra framework bacana e incrível para facilitar a criação e despacho de comandos! Genericamente utilizável em múltiplas plataformas diferentes, mas ao mesmo tempo incrivelmente customizável para implementar funcionalidades específicas para cada plataforma.

Ela foi criada para a Loritta e para o SparklyPower, e foi planejada com as seguintes ideias:

• Comandos devem ser criados de uma forma simples e intuitiva.
• Mesmo sendo simples, precisa permitir customizar como os comandos para implementar funcionalidades específicas para cada plataforma.
• Precisa suportar as funcionalidades que o Kotlin oferece. (Não precisar ficar colocando @Optional em parâmetros, suportar argumentos padrões, suportar criação de comandos usando DSL, etc)
• Precisa ser genérica, para que seja possível implementar a framework em plataformas diversas para ter um único sistema unificado para comandos.
• Precisa suportar sub sub sub ... argumentos.
• Suportar contextos personalizados para comandos, como, por exemplo, retornar a instância de um Player ao digitar Loritta!
• Suportar Kotlin Coroutines.
• Não ser "mágico", como registrar comandos magicamente ao declarar eles.

Ela foi inspirada em várias frameworks diferentes: Annotation Command Framework, Plugin Annotations e KotlinBukkitAPI, essas frameworks são excelentes, mas cada uma tem algum problema diferente que não se "encaixa" no que a gente precisa, por exemplo:

1. Não são feitas em Kotlin, ou seja, existem coisas redudantes que não seriam necessárias (como @Optional) (Annotation Command Framework, Plugin Annotations)
2. Dependem de plataformas para funcionar, em vez de serem "genéricas" para usar em qualquer tipo de sistema (Plugin Annotations, KotlinBukkitAPI)
3. Apenas suporta DSL (KotlinBukkitAPI)

        <repository>
            <id>perfectdreams-repo</id>
            <url>https://repo.perfectdreams.net/</url>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>always</updatePolicy>
            </snapshots>
        </repository>

... coisas coisas coisas ...

        <dependency>
            <groupId>net.perfectdreams.commands</groupId>
            <artifactId>command-framework-core</artifactId>
            <version>0.0.2-SNAPSHOT</version> <!-- Veja a última versão no pom.xml! -->
        </dependency>

🤔 Tá fera, mas cadê os exemplos?

Nestes exemplos, estamos usando a nossa implementação que fizemos para unit tests, como você terá que implementar algumas coisas você mesmo, talvez existam algumas diferenças. (Mas nada tããããão diferente, não se preocupe!)

class HelloWorldCommand : DreamCommand("hello", "olá") {
	@Subcommand
	fun helloWorld(sender: Sender) {
		// Isto será executado se o usuário escrever
		// "hello"
		// "olá"
		// "hello algo_aqui_blah"
		// "olá qdhd qdqgdyqwd dhqudquhd"
		sender.sendMessage("Olá, mundo!")
	}
}

fun main() {
	val commandManager = ConsoleCommandManager() // Criar o nosso CommandManager

	commandManager.registerCommand(HelloWorldCommand()) // Registrar o nosso lindo comando

	while (true) {
		val line = readLine()!!
		commandManager.dispatchBlocking( // Caso você esteja usando coroutines, use apenas "dispatch"
			ConsoleSender(),
			line
		)
	}
}

E é isto!

"Que nada, cadê as implementações que você falou??"

Verdade, elas estão aqui:

Implementações Marotas

Não se preocupe, tem coisas aqui que você não precisará implementar (como o Sender), ele só está aqui para demonstrar o exemplo acima!

Senders:

interface Sender {    
   fun sendMessage(message: String)  
}

class ConsoleSender(val senderName: String) : Sender {  
   override fun sendMessage(message: String) {  
      println(message)  
   }  
}

Declarações de Comandos:

open class DreamCommand(override vararg val labels: String) : BaseCommand {  
   override val subcommands: MutableList<BaseCommand> = mutableListOf()  
  
   init {  
      registerSubcommands()  
   }  
}

open class DreamDSLCommand(vararg labels: String, override val executors: List<DreamDSLExecutorWrapper>, dslSubcommands: List<BaseDSLCommand>) : DreamCommand(*labels), BaseDSLCommand {  
   init {  
      // lol nope, vamos ignorar todos os subcomandos registrados pela classe principal, elas são chatas!  
  subcommands.clear()  
  
      // E colocar todos os subcomandos de DSL após iniciar  
  subcommands.addAll(dslSubcommands)  
  
      // Deste jeito ainda é possível usar o "subcommands" para adicionar subcomandos de outras classes! Yay!  
  }  
}

Command Manager:

class ConsoleCommandManager : DispatchableCommandManager<Sender, DreamCommand, DreamDSLCommand>() {  
   private val commands = mutableListOf<DreamCommand>()  
 
   override fun registerCommand(command: DreamCommand) {  
   	commands.add(command)  
   }  
 
   override fun unregisterCommand(command: DreamCommand) {  
   	commands.remove(command)  
   }  
 
   override fun getRegisteredCommands(): List<DreamCommand> {  
   	return commands  
   }  
 
   override suspend fun dispatch(sender: Sender, command: DreamCommand, label: String, arguments: Array<String>): Boolean {
   	if (!command.labels.contains(label))
   		return false

   	for (subCommand in command.subcommands) {
   		if (dispatch(sender, subCommand as DreamCommand, arguments.drop(0).firstOrNull() ?: "", arguments.drop(1).toTypedArray()))
   			return true
   	}
   	return execute(sender, command, arguments)
   }  
}

E é claro, é possível criar exemplos mais complexos, por exemplo:

class RoleplayCommand : DreamCommand("undertale") {
	@Subcommand
	fun root(sender: Sender) {
		sender.sendMessage("Para começar o roleplay, use \"undertale roleplay personagem\"")
	}

	inner class RoleplaySubCommand : DreamCommand("roleplay") {
		@Subcommand
		fun showCharacters(sender: Sender) {
			Character.values().forEach { sender.sendMessage(it.name) }
		}

		@Subcommand
		fun chooseCharacter(sender: Sender, @InjectArgument(ArgumentType.PEEK_STRING) characterName: String, character: Character?) {
			if (character == null) {
				sender.sendMessage("O personagem $characterName não existe, bobinho!")
				return
			}

			sender.sendMessage("Você escolheu $character!")
		}
	}

	enum class Character {
		ASRIEL,
		TORIEL,
		FRISK,
		CHARA
	}
}

Você pode até usar DSLs para criar comandos!

class DomainSpecificLanguageCommand {
	fun generateCommand() = command("dslexample") {
		command("easter") {
			whenever<Sender, String?> { sender, input ->
				if (input == null) {
					sender.sendMessage("Apenas os fortes que possuem a senha poderão ver o easter egg.")
					return@whenever
				}

				if (input != "lorotajubinha") {
					sender.sendMessage("Errou! $input não é a senha, tente novamente, mas agora com mais confiança!")
					return@whenever
				}

				sender.sendMessage("Parabéns, você encotrou o easter egg! Guarde ele com muito carinho ^-^ https://bit.ly/segredolori")
			}
		}

		whenever<Sender> {
			it.sendMessage("i love u :3")
		}
	}
}

E é isto, have fun!

💫 Agradecimentos especiais para...

YourKit, criadores do YourKit Java Profiler, suportam projetos open source de todos os tipos com o excelente profiler de aplicações Java e .NET. Nós agradecemos por darem uma licença open source para conseguir deixar nossos projetos mais incríveis e maravilhosos para todos os nossos usuários!

📄 Licença

O código-fonte da Loritta está licenciado sob a GNU Affero General Public License v3.0

---