🐍 MambaScript

Linguagem de programação moçambicana — Rápida, poderosa e em português!

MambaScript é uma linguagem de programação criada em Moçambique, com sintaxe totalmente em português. Projetada para ser acessível, expressiva e poderosa, permite que programadores lusófonos escrevam código na sua língua materna.

📑 Índice

1. Instalação
2. Início Rápido
3. Tipos de Dados
4. Variáveis
5. Operadores
6. Entrada e Saída
7. Estruturas de Controle
8. Funções
9. Tratamento de Erros
10. Strings
11. Números
12. Arrays
13. Objectos
14. Sistema de Importação
15. Módulos Built-in
16. Funções Built-in
17. Servidor HTTP
18. Base de Dados MySQL
19. Sistema de Pacotes
20. Exemplos Completos
21. Contribuição
22. Licença

📦 Instalação

Pré-requisitos

• Node.js versão 14 ou superior

Via npm (recomendado)

npm install -g mambascript-mz

Verificar instalação

mambas --versao

Executar um programa

Crie um arquivo com a extensão .ms e execute com o comando mambas:

mambas meu_programa.ms

🚀 Início Rápido

Crie um arquivo chamado ola.ms:

# O meu primeiro programa em MambaScript!
escreva "Olá, Mundo! 🐍"

variavel nome = "Moçambique"
escreva "Bem-vindo ao MambaScript, " + nome + "!"

Execute:

mambas ola.ms

Saída:

Olá, Mundo! 🐍
Bem-vindo ao MambaScript, Moçambique!

📊 Tipos de Dados

MambaScript suporta os seguintes tipos de dados:

| Tipo | Exemplo | Descrição | |------|---------|-----------| | Número | 10, 3.14 | Inteiros e decimais | | String | "olá", 'mundo' | Texto entre aspas duplas ou simples | | Booleano | verdadeiro, falso | Valores lógicos | | Nulo | nulo | Ausência de valor | | Array | [1, 2, 3] | Lista ordenada de valores | | Objecto | {nome: "Ana"} | Coleção de pares chave-valor |

variavel inteiro = 42
variavel decimal = 3.14
variavel saudacao = "Olá!"
variavel ativo = verdadeiro
variavel vazio = nulo
variavel frutas = ["manga", "papaia", "coco"]
variavel pessoa = {nome: "Habibo", idade: 25}

📝 Variáveis

As variáveis são declaradas com a palavra-chave variavel:

variavel nome = "MambaScript"
variavel versao = 2
variavel ativo = verdadeiro

escreva nome
escreva versao
escreva ativo

As variáveis podem ser reatribuídas:

variavel contador = 0
contador = contador + 1
escreva contador

➕ Operadores

Operadores Aritméticos

MambaScript permite usar símbolos ou palavras-chave em português:

| Operação | Símbolo | Palavra-chave | Exemplo | |----------|---------|---------------|---------| | Adição | + | mais | 5 + 3 ou 5 mais 3 | | Subtração | - | menos | 10 - 4 ou 10 menos 4 | | Multiplicação | * | vezes | 6 * 7 ou 6 vezes 7 | | Divisão | / | dividido | 20 / 5 ou 20 dividido 5 |

escreva 10 + 5
escreva 10 mais 5
escreva 4 vezes 3
escreva 15 dividido 3

Operadores de Comparação

| Operação | Símbolo | Palavra-chave | |----------|---------|---------------| | Igual | == | igual | | Maior que | > | maior | | Menor que | < | menor | | Maior ou igual | >= | maiorIgual | | Menor ou igual | <= | menorIgual |

Operadores Lógicos

| Operador | Descrição | Exemplo | |----------|-----------|---------| | e | E lógico (AND) | verdadeiro e falso | | ou | OU lógico (OR) | verdadeiro ou falso | | nao | Negação (NOT) | nao verdadeiro |

variavel temIdade = verdadeiro
variavel temDocumento = verdadeiro

se temIdade e temDocumento:
    escreva "Aprovado!"
fim

📡 Entrada e Saída

Saída (escreva)

escreva "Olá, Mundo!"
escreva 42
escreva verdadeiro

Entrada (ler)

escreva "Qual é o teu nome?"
variavel nome = ler()
escreva "Olá, " + nome + "!"

🔀 Estruturas de Controle

Condicional (se / senao)

variavel idade = 18

se idade >= 18:
    escreva "É maior de idade."
senao:
    escreva "É menor de idade."
fim

Condicionais aninhadas:

variavel nota = 85

se nota >= 90:
    escreva "Excelente!"
senao:
    se nota >= 70:
        escreva "Bom trabalho!"
    senao:
        escreva "Precisa melhorar."
    fim
fim

Ciclo Enquanto

variavel contador = 1

enquanto contador <= 5:
    escreva "Contagem: " + contador
    contador = contador + 1
fim

Ciclo Para

para i de 1 ate 10:
    escreva i
fim

Exemplo com cálculo:

# Tabuada do 7
para i de 1 ate 10:
    escreva "7 x " + i + " = " + (7 * i)
fim

🔧 Funções

Funções são declaradas com funcao e encerradas com fim:

funcao saudacao(nome):
    escreva "Olá, " + nome + "!"
fim

saudacao("Habibo")

Funções com retorno

funcao soma(a, b):
    retorna a + b
fim

variavel resultado = soma(10, 20)
escreva resultado

Funções como variáveis

As funções podem ser atribuídas a variáveis e passadas como argumentos:

variavel dobrar = funcao(x):
    retorna x * 2
fim

escreva dobrar(5)

Funções recursivas

funcao fatorial(n):
    se n <= 1:
        retorna 1
    fim
    retorna n * fatorial(n - 1)
fim

escreva fatorial(5)

🛡️ Tratamento de Erros

Use tentar e pegar para lidar com erros em tempo de execução:

tentar:
    variavel dados = json_ler("ficheiro.json")
    escreva dados.nome
pegar erro:
    escreva "Ocorreu um erro: " + erro
fim

🔤 Strings

Métodos de String

| Método | Descrição | Exemplo | |--------|-----------|---------| | .tamanho() | Comprimento da string | "olá".tamanho() → 3 | | .maiuscula() | Converte para maiúsculas | "olá".maiuscula() → "OLÁ" | | .minuscula() | Converte para minúsculas | "OLÁ".minuscula() → "olá" | | .paraNumero() | Converte string para número | "42".paraNumero() → 42 |

variavel texto = "mambascript"

escreva texto.tamanho()
escreva texto.maiuscula()
escreva texto.minuscula()

variavel numero = "123".paraNumero()
escreva numero + 7

🔢 Números

Métodos de Número

| Método | Descrição | Exemplo | |--------|-----------|---------| | .paraTexto() | Converte número para string | 42.paraTexto() → "42" |

variavel idade = 25
escreva "Idade: " + idade.paraTexto()

📚 Arrays

Criação e Acesso

variavel frutas = ["manga", "papaia", "banana", "coco"]

escreva frutas[0]
escreva frutas[2]

Métodos de Array

| Método | Descrição | |--------|-----------| | .tamanho() | Número de elementos | | .adicionar(item) | Adiciona ao final | | .remover(indice) | Remove pelo índice | | .pegar(indice) | Obtém pelo índice | | .contem(item) | Verifica se contém | | .juntar(separador) | Junta em string |

variavel numeros = [10, 20, 30]

numeros.adicionar(40)
escreva numeros.tamanho()
escreva numeros.contem(20)
escreva numeros.juntar(" - ")
numeros.remover(0)
escreva numeros.pegar(0)

Iterar sobre um Array

variavel cidades = ["Maputo", "Beira", "Nampula", "Quelimane"]

para i de 0 ate cidades.tamanho() - 1:
    escreva cidades[i]
fim

🏗️ Objectos

Criação e Acesso

variavel pessoa = {
    nome: "Habibo",
    idade: 25,
    cidade: "Maputo"
}

escreva pessoa.nome
escreva pessoa.idade

Modificação de Propriedades

pessoa.nome = "João"
pessoa.idade = 30
escreva pessoa.nome

Objectos com Arrays

variavel turma = {
    nome: "Turma A",
    alunos: ["Ana", "Carlos", "Maria"],
    nota_media: 15.5
}

escreva turma.nome
escreva turma.alunos[0]

📦 Sistema de Importação

Importar Módulos Locais

Crie um arquivo em modulos_mambas/:

# modulos_mambas/utils.ms
funcao dobro(n):
    retorna n * 2
fim

Importe no programa principal:

importar utils de "utils"
escreva utils.dobro(10)

Importar Módulos Built-in

importar matematica de "matematica"
importar fs de "fs"
importar caminho de "caminho"
importar http de "http"
importar bd de "mysql"

🔩 Módulos Built-in

📐 Módulo matematica

| Função / Constante | Descrição | |---------------------|-----------| | PI | Valor de π | | raiz(n) | Raiz quadrada | | potencia(base, exp) | Potenciação | | absoluto(n) | Valor absoluto | | arredondar(n) | Arredondamento | | teto(n) | Arredondamento para cima | | chao(n) | Arredondamento para baixo | | aleatorio() | Número aleatório entre 0 e 1 | | seno(n) | Seno | | cosseno(n) | Cosseno |

importar matematica de "matematica"

escreva matematica.PI
escreva matematica.raiz(144)
escreva matematica.potencia(2, 10)
escreva matematica.arredondar(3.7)
escreva matematica.aleatorio()

📁 Módulo fs

| Função | Descrição | |--------|-----------| | ler(arquivo) | Lê o conteúdo de um arquivo | | escrever(arquivo, conteudo) | Escreve num arquivo | | existe(arquivo) | Verifica se o arquivo existe | | apagar(arquivo) | Apaga um arquivo |

importar fs de "fs"

fs.escrever("dados.txt", "Olá, MambaScript!")
escreva fs.existe("dados.txt")
variavel conteudo = fs.ler("dados.txt")
escreva conteudo
fs.apagar("dados.txt")

📂 Módulo caminho

| Função | Descrição | |--------|-----------| | juntar(...partes) | Junta partes de um caminho | | diretorio(caminho) | Retorna o diretório | | arquivo(caminho) | Retorna o nome do arquivo | | extensao(caminho) | Retorna a extensão | | absoluto(caminho) | Retorna o caminho absoluto |

importar caminho de "caminho"

escreva caminho.juntar("pasta", "arquivo.ms")
escreva caminho.extensao("programa.ms")
escreva caminho.absoluto("programa.ms")

🌐 Módulo http — Cliente

O módulo http permite fazer requisições HTTP a APIs externas:

| Função | Descrição | |--------|-----------| | get(url, cabecalhos?) | Requisição GET | | post(url, corpo, cabecalhos?) | Requisição POST | | put(url, corpo, cabecalhos?) | Requisição PUT | | apagar(url, cabecalhos?) | Requisição DELETE |

Cada função retorna um objecto com:

| Propriedade | Descrição | |-------------|-----------| | status | Código HTTP da resposta | | corpo | Corpo da resposta (JSON ou texto) | | texto | Corpo como texto puro | | ok | verdadeiro se status entre 200 e 299 |

importar http de "http"

variavel resposta = http.get("https://api.exemplo.com/dados")

se resposta.ok:
    escreva resposta.corpo
senao:
    escreva "Erro: " + resposta.status
fim

# POST com corpo JSON
variavel resultado = http.post("https://api.exemplo.com/usuarios", {
    "nome": "Habibo",
    "email": "[email protected]"
})
escreva resultado.status

🖥️ Servidor HTTP

O módulo http também permite criar servidores HTTP nativamente em MambaScript.

Criar um Servidor

importar http de "http"

variavel minhaFuncao = funcao(requisicao, resposta):
    se requisicao.url == "/":
        resposta.json(200, {"mensagem": "Bem-vindo!"})
    senao:
        resposta.json(404, {"erro": "Rota não encontrada"})
    fim
fim

variavel servidor = http.criarServidor()
servidor.aoReceber(minhaFuncao)
servidor.escutar(3000)
escreva "Servidor rodando na porta 3000!"

Objecto requisicao

| Propriedade | Descrição | |-------------|-----------| | url | Caminho da rota (ex: /api/usuarios) | | metodo | Método HTTP (GET, POST, etc.) | | corpo | Corpo da requisição (JSON ou texto) | | params | Query parameters (?id=1&nome=Elio) | | cabecalhos | Headers da requisição |

Objecto resposta

| Método | Descrição | |--------|-----------| | enviar(status, conteudo) | Envia texto ou JSON automaticamente | | json(status, conteudo) | Envia resposta JSON explícita | | cabecalho(chave, valor) | Define um header na resposta | | redirecionar(url) | Redireciona para outra URL |

Exemplo Completo de API

importar http de "http"

variavel handler = funcao(requisicao, resposta):
    variavel rota = requisicao.url

    resposta.cabecalho("X-Powered-By", "MambaScript")
    resposta.cabecalho("Access-Control-Allow-Origin", "*")

    se rota == "/":
        resposta.json(200, {
            "mensagem": "API MambaScript",
            "versao": "1.0",
            "status": "online"
        })
    senao:
        se rota == "/api/usuario":
            variavel nome = requisicao.params.nome
            resposta.json(200, {
                "nome": nome,
                "linguagem": "MambaScript"
            })
        senao:
            resposta.json(404, {
                "erro": "Rota não encontrada",
                "rota": rota
            })
        fim
    fim
fim

variavel servidor = http.criarServidor()
servidor.aoReceber(handler)
servidor.escutar(3000)
escreva "API rodando na porta 3000!"

🗄️ Base de Dados MySQL

MambaScript tem suporte nativo a MySQL através do módulo mysql.

Pré-requisito

O mysql2 deve estar instalado no runtime do MambaScript:

npm install mysql2

Funções do Módulo mysql

| Função | Descrição | |--------|-----------| | conectar(host, usuario, senha, base) | Conecta ao banco de dados | | consultar(sql, parametros?) | Executa SELECT, retorna array | | executar(sql, parametros?) | Executa INSERT/UPDATE/DELETE | | fechar() | Fecha a conexão |

O método executar retorna:

| Propriedade | Descrição | |-------------|-----------| | afetadas | Número de linhas afetadas | | inseridoId | ID do último registo inserido | | ok | verdadeiro se afetou alguma linha |

Exemplo de Uso

importar bd de "mysql"

bd.conectar("localhost", "root", "senha", "minha_base")

# SELECT
variavel usuarios = bd.consultar("SELECT * FROM usuarios")
escreva usuarios

# SELECT com parâmetros
variavel user = bd.consultar("SELECT * FROM usuarios WHERE id = ?", [1])
escreva user

# INSERT
variavel resultado = bd.executar(
    "INSERT INTO usuarios (nome, email) VALUES (?, ?)",
    ["Habibo", "[email protected]"]
)
escreva "ID inserido: " + resultado.inseridoId

# UPDATE
bd.executar("UPDATE usuarios SET nome = ? WHERE id = ?", ["Elio", 1])

# DELETE
bd.executar("DELETE FROM usuarios WHERE id = ?", [1])

bd.fechar()

API com MySQL

importar http de "http"
importar bd de "mysql"

bd.conectar("localhost", "root", "senha", "app_db")

variavel handler = funcao(requisicao, resposta):
    se requisicao.url == "/api/usuarios":
        variavel usuarios = bd.consultar("SELECT * FROM usuarios")
        resposta.json(200, {"usuarios": usuarios})
    senao:
        resposta.json(404, {"erro": "Rota não encontrada"})
    fim
fim

variavel servidor = http.criarServidor()
servidor.aoReceber(handler)
servidor.escutar(3000)
escreva "API com MySQL rodando na porta 3000!"

📦 Sistema de Pacotes

Estrutura de um Pacote

meu-pacote/
├── index.ms       ← código da biblioteca
└── pacote.json    ← metadados

Ficheiro pacote.json

{
  "nome": "meu-pacote",
  "versao": "1.0.0",
  "descricao": "Descrição do que o pacote faz",
  "autor": "teu-nome"
}

Ficheiro index.ms

funcao saudacao(nome):
    retorna "Olá, " + nome + "!"
fim

funcao despedida(nome):
    retorna "Até logo, " + nome + "!"
fim

Usar Localmente

Coloque a pasta dentro de modulos_mambas/ do seu projeto:

meu-projeto/
├── main.ms
└── modulos_mambas/
    └── meu-pacote/
        ├── index.ms
        └── pacote.json

importar meuPacote de "meu-pacote"

escreva meuPacote.saudacao("Mundo")
escreva meuPacote.despedida("Mundo")

Gestor de Pacotes

# Instalar um pacote
mambas instalar nome-do-pacote

# Remover um pacote
mambas remover nome-do-pacote

# Listar pacotes instalados
mambas listar

# Procurar pacotes
mambas procurar

Partilhar com a Comunidade

1. Garanta que tem index.ms e pacote.json
2. Teste localmente em modulos_mambas/
3. Abra uma Issue em: github.com/Eliobros/mambascript-pacotes
4. Use o título: [Pacote] nome-do-pacote
5. Cole o código do index.ms e pacote.json
6. Aguarda aprovação!

⚡ Funções Built-in

📅 hoje()

Retorna um objecto com a data e hora actuais:

| Método | Descrição | |--------|-----------| | mostrarData() | Data formatada | | mostrarHora() | Hora formatada | | ano() | Ano actual | | dia() | Dia do mês | | horas() | Horas | | minutos() | Minutos | | segundos() | Segundos | | mes() | Objecto com numero e nome | | semana() | Objecto com numero e nome | | timestamp() | Timestamp Unix | | formatado() | Data no formato DD/MM/AAAA | | horaFormatada() | Hora no formato HH:MM:SS |

variavel data = hoje()
escreva data.mostrarData()
escreva data.mostrarHora()
escreva data.ano()
escreva data.mes().nome
escreva data.formatado()

# Com fuso horário
variavel dataMZ = hoje("Africa/Maputo")
escreva dataMZ.horaFormatada()

📄 Funções JSON

| Função | Descrição | |--------|-----------| | json_ler(arquivo) | Lê e analisa um arquivo JSON | | json_texto(string) | Analisa uma string JSON | | json_escrever(arquivo, dados) | Escreve dados num arquivo JSON |

# Ler arquivo JSON
variavel config = json_ler("config.json")
escreva config.nome

# Analisar string JSON
variavel dados = json_texto('{"nome": "Mamba", "versao": 2}')
escreva dados.nome

# Escrever arquivo JSON
variavel info = {nome: "MambaScript", versao: 2}
json_escrever("saida.json", info)

💡 Exemplos Completos

Exemplo 1: Calculadora Simples

funcao calculadora(a, operacao, b):
    se operacao == "+":
        retorna a + b
    fim
    se operacao == "-":
        retorna a - b
    fim
    se operacao == "*":
        retorna a * b
    fim
    se operacao == "/":
        se b == 0:
            escreva "Erro: Divisão por zero!"
            retorna nulo
        fim
        retorna a / b
    fim
    retorna nulo
fim

escreva "5 + 3 = " + calculadora(5, "+", 3)
escreva "10 - 4 = " + calculadora(10, "-", 4)
escreva "6 * 7 = " + calculadora(6, "*", 7)
escreva "20 / 4 = " + calculadora(20, "/", 4)

Exemplo 2: Gestão de Alunos

variavel alunos = []

funcao adicionarAluno(nome, nota):
    alunos.adicionar({nome: nome, nota: nota})
    escreva "Aluno " + nome + " adicionado!"
fim

funcao mostrarResultados():
    para i de 0 ate alunos.tamanho() - 1:
        variavel status = "Reprovado"
        se alunos[i].nota >= 10:
            status = "Aprovado"
        fim
        escreva alunos[i].nome + ": " + alunos[i].nota + " - " + status
    fim
fim

adicionarAluno("Ana", 18)
adicionarAluno("Carlos", 8)
adicionarAluno("Maria", 15)
mostrarResultados()

Exemplo 3: API REST Completa

importar http de "http"
importar bd de "mysql"

bd.conectar("localhost", "root", "senha", "escola_db")

variavel handler = funcao(requisicao, resposta):
    variavel rota = requisicao.url

    resposta.cabecalho("Access-Control-Allow-Origin", "*")
    resposta.cabecalho("X-Powered-By", "MambaScript")

    se rota == "/":
        resposta.json(200, {
            "api": "Escola MambaScript",
            "versao": "1.0",
            "rotas": ["/alunos", "/alunos/adicionar"]
        })
    senao:
        se rota == "/alunos":
            variavel alunos = bd.consultar("SELECT * FROM alunos")
            resposta.json(200, {"alunos": alunos})
        senao:
            resposta.json(404, {"erro": "Rota não encontrada"})
        fim
    fim
fim

variavel servidor = http.criarServidor()
servidor.aoReceber(handler)
servidor.escutar(3000)
escreva "API Escola rodando na porta 3000!"

Exemplo 4: Trabalhando com Ficheiros e Módulos

importar matematica de "matematica"
importar fs de "fs"

funcao gerarRelatorio():
    variavel relatorio = "=== Relatório Matemático ===\n"
    relatorio = relatorio + "PI: " + matematica.PI + "\n"
    relatorio = relatorio + "Raiz de 256: " + matematica.raiz(256) + "\n"
    relatorio = relatorio + "2^8: " + matematica.potencia(2, 8) + "\n"
    para i de 1 ate 10:
        relatorio = relatorio + "5 x " + i + " = " + (5 * i) + "\n"
    fim
    retorna relatorio
fim

variavel texto = gerarRelatorio()
escreva texto
fs.escrever("relatorio.txt", texto)
escreva "Relatório salvo!"

variavel agora = hoje()
escreva "Gerado em: " + agora.formatado() + " às " + agora.horaFormatada()

🤝 Contribuição

Contribuições são bem-vindas! Para contribuir:

1. Faça um fork do repositório
2. Crie uma branch para a sua feature (git checkout -b minha-feature)
3. Faça commit das suas mudanças (git commit -m 'Adiciona nova feature')
4. Faça push para a branch (git push origin minha-feature)
5. Abra um Pull Request

Reportar Problemas

Encontrou um bug? Abra uma issue no GitHub.

📜 Licença

MambaScript é distribuído sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.