⚙️ Sistema de Comandos - RafaPear/CLILib GitHub Wiki

O CLILib foi desenhado com um sistema de comandos modular e extensível. Cada comando é um objeto que implementa a interface Command, permitindo:

• Definir aliases e número de argumentos esperados
• Executar lógica customizada ao correr o comando
• Validar se argumentos são ficheiros, e se têm a extensão correta

Todos os comandos devem implementar a interface Command. Esta interface define:

interface Command {
    val description: String
    val longDescription: String
        get() = description
    val usage: String
    val aliases: List<String>
    val minArgs: Int
        get() = 0
    val maxArgs: Int
        get() = 0
    val requiresFile: Boolean
        get() = false
    val fileExtension: String
        get() = ""
    fun run(args: List<String>): Boolean
}

• aliases: nomes alternativos para o comando (ex: print, p, echo)
• minArgs, maxArgs: número de argumentos obrigatórios/opcionais
• requiresFile, fileExtension: validação de ficheiros como argumentos
• run(...): função executada quando o comando é chamado

Para que um comando esteja disponível, tem de ser registado via CmdRegister:

CmdRegister.register(MyCustomCommand)

Ou em lote:

```kotlin
CmdRegister.registerAll(listOf(Cmd1, Cmd2, Cmd3))

Para o CLI reconhecer comandos, a função registerDefaultCommands() do App já trata disso:

val app = App()
app.registerDefaultCommands()

Quando o utilizador insere texto no terminal, esse texto é analisado e executado por cmdParser(...), que:

• Divide comandos pelo |

• Substitui variáveis e argumentos ($var, arg[0], etc.)

• Procura o comando via CmdRegister.find(...)

• Executa a função run(args) correspondente

object MyHelloCmd : Command {
    override val description = "Diz olá ao utilizador"
    override val usage = "hello <nome>"
    override val aliases = listOf("hello", "hi")
    override val minArgs = 1
    override val maxArgs = 1

    override fun run(args: List<String>): Boolean {
        println("Olá, ${args[0]}!")
        return true
    }
}

Depois de definido:

CmdRegister.register(MyHelloCmd)

O CLILib inclui vários comandos prontos a usar que cobrem funcionalidades básicas de CLI, manipulação de diretórios, ficheiros, scripting, variáveis e controlo de fluxo. Todos estes comandos são registados automaticamente ao iniciar a aplicação com os comandos por defeito.

• clr — limpa o ecrã do terminal
• exit, e — termina a aplicação
• help, h — mostra todos os comandos e as respetivas descrições
• version — mostra a versão e créditos do projeto
• print — imprime texto no terminal
• wait, w — pausa a execução por um número de milissegundos
• waitforuser, wfu — espera que o utilizador pressione Enter
• mkcmd — cria comandos simples a partir de ficheiros .json
• mkcmdtemplate, mkcmdtpl — gera um template JSON para comandos personalizados

• cd <diretório> — muda o diretório atual
• ls [diretório] — lista ficheiros/pastas num diretório
• mkdir <nome> — cria um novo diretório
• deldir, rmdir <diretório> — apaga um diretório e respetivo conteúdo
• mkfile <nome> — cria um ficheiro vazio com o nome especificado
• delfile, rmfile <ficheiro> — apaga um ficheiro
• edit <ficheiro> — abre um ficheiro no editor de texto por defeito do sistema

• loadscript, lscript <ficheiro.ppc> — executa um script .ppc linha a linha
• measure, m, time <comando> — mede o tempo de execução de um comando

• var <nome> [valor|opções] — cria, modifica, lista ou apaga variáveis
  • Se forneceres <valor>, a variável é criada ou atualizada com esse valor
  • Se não forneceres <valor>, será usado o resultado do último comando (lastCmdDump)
  • Opções disponíveis:
    • -l, --list — lista todas as variáveis
    • -d, --delete — apaga uma variável
    • -h, --help — mostra ajuda sobre o comando
• add <var1> <var2> [resultado] — soma duas variáveis e guarda o resultado
• sub <var1> <var2> [resultado] — subtrai uma variável da outra
• mult <var1> <var2> [resultado] — multiplica duas variáveis
• div <var1> <var2> [resultado] — divide uma variável pela outra
• expr <expressão> — avalia uma expressão matemática e armazena o resultado

Mais comandos serão adicionados conforme o projeto evolui.