portulong.ptg 1.0.2

Uma linguagem de programação em português para criar bots do Discord baseada em Python

🐉 Linguagem Portulong (.ptg) — Documentação Oficial

Bem-vindo à Documentação Oficial da Portulong! 🚀 A Portulong é uma linguagem de programação moderna desenvolvida em português, transpilada com precisão matemática para o robusto ecossistema do Python. A nossa missão é democratizar a aprendizagem de programação e facilitar a criação de ferramentas incríveis (como robôs para o Discord) sem a barreira do idioma inglês.

Se és um iniciante absoluto ou um programador experiente que quer construir robôs para o Discord em português nativo, este guia completo contém tudo o que precisas para te tornares um mestre no Portulong! 🎨

---

🧭 Menu de Navegação Rápida

1. Introdução e Instalação
2. O Básico da Programação (Python em PT)
3. Funções (Criar os Seus Próprios Comandos)
4. Criação de Bots para o Discord (O Prato Principal)
5. Dicas e Boas Práticas

---

1. Introdução e Instalação

O que é o Portulong e a sua Missão? 🐉

A programar, muitas vezes somos forçados a aprender inglês ao mesmo tempo que tentamos entender a lógica de programação. O Portulong nasceu para quebrar esta barreira de formato amigável, nativo e direto!

A linguagem oferece uma sintaxe limpa, estruturada e de tipagem amigável com base em termos luso-brasileiros tradicionais. O motor por trás do Portulong realiza uma análise léxica símbolo a símbolo (Tokenization) de altíssima fidelidade. Isso significa que ele lê o seu arquivo .ptg caractere por caractere, garantindo que textos dentro de strings ou comentários nunca sejam afetados e gerando código Python perfeitamente otimizado pronto para execução.

Como instalar no terminal? 💻

⚡ Método 1: Instalação Automática Completa (Recomendado 🌟)

Se queres obter a experiência completa da linguagem, instalar o compilador oficial E ao mesmo tempo configurar de forma 100% automática a Extensão Oficial do VS Code (com destaques completos de cores, ícones para ficheiros .ptg, preenchimento automático e o botão de Play/Executar de 1 clique integrado no topo do editor), podes correr o comando abaixo direto no teu terminal:

No Linux / macOS / Git Bash / terminal integrado:

curl -fsSL https://portulong.vercel.app/api/instalar -o instalar.py && python instalar.py

No Windows (PowerShell):

Invoke-WebRequest -Uri "https://portulong.vercel.app/api/instalar" -OutFile "instalar.py"; python instalar.py

Nota: Esse instalador inteligente baixa todas as configurações visuais pré-definidas de cores, temas, mapeia o compilador no sistema, configura o botão "Play" de atalho e assegura que você tenha tudo funcionando "sertinho" em menos de 10 segundos.

---

🔹 Método 2: Instalar Apenas o Compilador (via pip)

Caso queiras instalar apenas o compilador básico via CLI sem as extensões visuais e suporte gráfico do editor VS Code, execute:

pip install portulong.ptg

🔹 Atualizar o Compilador (Upgrade)

Caso já tenhas a linguagem e queiras atualizar para a versão mais recente com novas palavras-chave e recursos:

pip install --upgrade portulong.ptg

🔹 Desinstalar o Compilador

Se desejares remover completamente o pacote do compilador do seu sistema:

pip uninstall -y portulong.ptg

Como executar um ficheiro? 🚀

Depois de instalado globalmente no sistema, você pode executar os seus ficheiros com a extensão .ptg através do comando executar de forma direta e rápida:

portulong executar arquivo.ptg

Você também pode iniciar de forma interativa a estrutura básica do projeto rodando:

portulong iniciar

Este comando criará automaticamente os arquivos iniciais main.ptg e .env prontos para edição!

---

2. O Básico da Programação (Poder do Python em PT)

A sintaxe do Portulong foi desenhada para ser intuitiva e limpa. Veja abaixo como realizar as primeiras operações essenciais que servem para construir qualquer tipo de programa!

Escrever no Ecrã (Output de Dados)

Para mostrar qualquer informação para o utilizador no ecrã ou consola de comandos, utilize a função interna escrever():

escrever("Olá, Mundo! Bem-vindo ao maravilhoso universo do Portulong! 🐉")

Variáveis e Tipos de Dados

As variáveis funcionam como caixas para armazenar informações. Em Portulong, os tipos de dados são representados em português e de forma limpa:

# Guardar uma cadeia de caracteres (String)
nome_do_usuario = "Sílvia"

# Guardar um número inteiro (Int)
idade = 26

# Guardar um número decimal / real (Float)
saldo_da_carteira = 150.50

# Guardar valores lógicos / booleanos (Bool)
usuario_activo = Verdadeiro
bot_ligado = Falso

# Guardar uma ausência de valor (None)
dados_do_perfil = Nulo

Matemática Básica e Operadores

Pode realizar todas as operações aritméticas tradicionais diretamente:

soma = 10 + 5            # 15
subtracao = 20 - 4       # 16
multiplicacao = 3 * 3    # 9
divisao = 10 / 2         # 5.0
resto_da_divisao = 7 % 2 # 1

Estruturas de Decisão: se, senaose, senao

Para testar condições e tomar caminhos diferentes no código, utilize a estrutura condicional nativa em português:

pontuacao = 85

se pontuacao >= 90:
    escrever("Excelente! Ganhaste uma medalha de ouro! 🥇")
senaose pontuacao >= 70:
    escrever("Muito bom! Passaste na prova de nível! 🥈")
senao:
    escrever("Força, continua a estudar para a próxima! 🥉")

Laços de Repetição (Loops): para e enquanto

Os laços de repetição servem para executar uma mesma instrução várias vezes de forma controlada.

O Loop para com intervalo

# Repetir o código 5 vezes (de 0 até 4)
para numero em intervalo(5):
    escrever(f"Contagem do loop: {numero}")

O Loop enquanto

tentativas = 1

enquanto tentativas <= 3:
    escrever(f"A realizar tentativa número: {tentativas}")
    tentativas = tentativas + 1

---

3. Funções (Criar os Próprios Comandos)

As funções funcionam como mini-programas que realizam uma tarefa específica e retornam um resultado que pode ser reaproveitado em outras partes do seu código.

Como declarar e utilizar uma função com definir e retornar

# Definir uma função de somar dois números
definir somar_valores(valor_a, valor_b):
    escrever(f"A processar a soma de {valor_a} e {valor_b}...")
    resultado = valor_a + valor_b
    retornar resultado

# Chamar a função e guardar o resultado numa variável
total = somar_valores(12, 18)
escrever(f"O resultado final da soma é: {total}") # Imprime 30

---

4. Criação de Bots para o Discord (O Prato Principal)

A grande especialidade do Portulong é permitir a criação de Bots (Robôs) profissionais para o Discord de forma simples e usando lógica limpa em português através do wrapper nativo portulong.discord_pt! 🤖

A Estrutura Base do Bot

Aqui está o esqueleto fundamental que deves usar para iniciar qualquer Bot. Importamos o wrapper, ligamos as permissões necessárias e ligamos o nosso robô:

# 1. Importar o wrapper oficial do discord em português
importar portulong.discord_pt como discord

# 2. Criar a instância do Robô com o prefixo para os comandos
robo = discord.Robo(prefixo="!")

# 3. Lógica para manter o robô ativo (Executado no final do código)
# Nota: No seu ficheiro '.env', guarde a sua chave secreta como TOKEN=seu_token_aqui
# O motor Portulong lê automaticamente o seu token confidencial com toda a segurança!

Ouvir e Responder a Eventos

Os eventos são ações que acontecem de forma assíncrona no Discord (por exemplo, quando o seu robô é ligado, ou quando alguém entra no servidor):

@robo.evento
definir assincrono ao_iniciar():
    escrever(f"O Robo {robo.usuario} acabou de acordar e está online! ⚡")

Atenção à Regra de Inversão Estrutural: No Portulong, podes escrever tanto definir assincrono como assincrono definir. O compilador inteligente reordena matematicamente a ordem dos tokens na saída para que o Python processe de forma impecável no formato async def sem qualquer erro de sintaxe!

Criar Comandos Básicos

Para interagir com os membros do servidor através de comandos com prefixo (por exemplo, o comando !ping):

@robo.comando(nome="ping")
definir assincrono responder_ping(contexto):
    # O comando aguardar faz o papel do 'await' em Python
    aguardar contexto.enviar("🏓 Pong! O bot respondeu 100% em Portulong!")

Comandos Avançados (Lendo Argumentos do Utilizador)

Podes receber parâmetros adicionais que o utilizador escreve logo após o nome do comando no Discord:

# Exemplo de comando: !saludar Silvio
@robo.comando(nome="saludar")
definir assincrono saudar_membro(contexto, nome_do_membro):
    mensagem_personalizada = f"Olá {nome_do_membro}! É um grande prazer ver-te por aqui! 🎉"
    aguardar contexto.enviar(mensagem_personalizada)

Gestão e Moderação do Servidor (Uso Prático)

Com o Portulong, podes automatizar tarefas de moderação avançadas no teu servidor de forma direta e eficaz:

# Comando para limpar mensagens de um canal (!limpar 10)
@robo.comando(nome="limpar")
definir assincrono limpar_chat(contexto, quantidade: inteiro):
    # Limpa as últimas mensagens do canal de forma automática
    aguardar contexto.canal.limpar(limite=quantidade)
    aguardar contexto.enviar(f"🧹 O canal foi limpo por {contexto.autor}! {quantidade} mensagens removidas.")

# Comando para expulsar um utilizador indesejado (!expulsar @membro)
@robo.comando(nome="expulsar")
definir assincrono expulsar_membro(contexto, membro: discord.Membro, motivo=Nulo):
    se motivo == Nulo:
        motivo = "Comportamento inadequado"
        
    # Executa a expulsão usando o método nativo traduzido
    aguardar membro.expulsar(motivo=motivo)
    aguardar contexto.enviar(f"🚨 O membro {membro.nome} foi expulso com sucesso! Motivo: {motivo}")

---

5. Dicas e Boas Práticas

Para escreveres códigos limpos, legíveis e fáceis de dar suporte em Portulong:

1. Indentação é Lei! 📐

Assim como no Python, a indentação (o espaçamento no início de cada linha de código dentro de um bloco) é fundamental para determinar onde começam e terminam as regras de uma tomada de decisão (se) ou de uma função (definir). Utilize sempre 4 espaços (ou uma tecla Tab) para identificar sub-blocos.

# CORRETO:
se Verdadeiro:
    escrever("Este código está correctamente indentado!")

# INCORRETO (Causará um IdentationError):
se Verdadeiro:
escrever("Este código vai quebrar!")

2. Comentários para Organização e Notas 📝

Use a cerquilha (#) no início de uma linha ou após uma declaração para documentar o que o seu código faz. O analisador léxico do Portulong irá ler e ignorar os comentários de forma cirúrgica na transpilação matemática, sem que exista nenhum impacto no desempenho da execução:

# Esta linha inteira é um comentário e serve apenas para documentação
escrever("Instrução executada!") # Comentário ao lado do código

3. Escreva Nomes Claros para Variáveis 🏷️

Evite dar nomes confusos de apenas uma letra para as suas variáveis. Prefira nomes explicativos que facilitem a leitura do código daqui a algumas semanas:

# Prática Recomendada:
tempo_de_espera_segundos = 10

# Prática Não Recomendada:
t = 10

---

Divirta-se programando na linguagem mais amigável do mundo lusófono! Se tiver alguma dúvida, consulte esta documentação para manter os seus robôs e comandos sempre otimizados e seguros! 🐉✨