Skip to content
BranchesTags

Repository files navigation

🦋 Butterfly.f — Documentação Oficial da Linguagem

Versão 2 — Python Edition

Python License Status

"A borboleta bateu as asas no passado. O furacão começou no presente."

Quick Start

# 1. Transpilar
python butterfly_compiler.py hello_world.bfy

# 2. Executar
python hello_world.py

Sumário

  1. Visão Geral
  2. Conceito e Filosofia
  3. Arquivos e Toolchain
  4. Estrutura Obrigatória do Programa
  5. Variáveis
  6. Tipos Suportados
  7. Comandos — Referência Completa
  8. Operadores de Comparação (WHEN)
  9. Mecânicas Temporais
  10. Tabela Rápida de Comandos
  11. Programas de Exemplo
  12. Passo a Passo — Executando os Programas

1. Visão Geral

Butterfly.f é uma linguagem de programação esotérica de propósito geral que modela a execução de um programa como uma viagem no tempo: o código é dividido em passado e presente, e qualquer mudança feita no passado contamina caoticamente as leituras realizadas no presente.

Atributo Valor
Paradigma Imperativo / Esotérico
Extensão de arquivo .bfy
Traduz para Python (código gerado executável direto com python)
Compilador butterfly_compiler.py — Python puro, sem dependências
Versão v2 — Extended

2. Conceito e Filosofia

Butterfly.f é baseada na Teoria do Caos e no clássico Efeito Borboleta:

Uma pequena mudança nas condições iniciais produz diferenças enormes no futuro.

As duas leis da linguagem

Lei do Tempo: todo programa tem exatamente dois momentos — o PAST (passado) e o PRESENT (presente). O passado define as condições iniciais. O presente colhe as consequências — mas distorcidas pelo caos.

Lei do Destino: o programa deve alterar o estado do universo. Se nada mudar, o destino não foi alterado e a execução falha. Se mudar demais, cria-se um paradoxo e o universo colapsa.

O Efeito Borboleta no código

Toda variável escrita no PAST contamina as leituras do PRESENT via XOR:

chaos_mask = var1_past ^ var2_past ^ var3_past ^ ...

No PRESENT:  ler X  →  lê (X ^ chaos_mask)

O que você vê no presente pode não ser a realidade.

3. Arquivos e Toolchain

Estrutura de arquivos

projeto/
  ├── butterfly_compiler.py   ← compilador (Python puro)
  ├── hello_world.bfy         ← código-fonte Butterfly.f
  └── hello_world.py          ← gerado pelo compilador (executável direto)

Pipeline completo

arquivo.bfy
    │
    │  python butterfly_compiler.py arquivo.bfy
    ▼
arquivo.py   (Python gerado automaticamente)
    │
    │  python arquivo.py
    ▼
saída no terminal

Requisitos

Ferramenta Versão mínima Instalação
Python 3.7+ python.org ou gerenciador de pacotes

Nenhuma biblioteca externa necessária. O compilador usa apenas a biblioteca padrão do Python.

4. Estrutura Obrigatória do Programa

Todo arquivo .bfy obrigatoriamente contém dois blocos, sempre nesta ordem:

PAST_BEGIN
    # código do passado
PAST_END

PRESENT_BEGIN
    # código do presente
PRESENT_END

Regras estruturais

Regra Descrição
Dois blocos obrigatórios Faltando um → erro de compilação
Ordem fixa PAST sempre antes de PRESENT
Blocos podem estar vazios Mas a Validação Temporal pode rejeitar
Comentários Linhas que começam com # são ignoradas
Sensível a maiúsculas PAST_BEGIN ≠ past_begin

5. Variáveis

  • Todas as variáveis são inteiras (inteiros Python — sem limite de tamanho)
  • Todas têm escopo global (visíveis em ambos os blocos)
  • Todas são inicializadas com 0 automaticamente
  • Não é necessário declarar: basta usar
  • JESSIE é uma variável de sistema reservada com comportamento especial

6. Tipos Suportados

Butterfly.f possui um único tipo de dado:

Tipo Descrição Intervalo Padrão
Inteiro Números inteiros ilimitado (Python int) 0

Strings existem apenas como literais de saída nos comandos ECHO e ECHO_VAR. Não são armazenadas em variáveis.

7. Comandos — Referência Completa

7.1 Comandos Originais (v1)

SET

SET <variável> <valor>

Atribui um valor inteiro literal a uma variável.

SET pontos 100
SET vida   -5
SET x      0

PRINT

PRINT <variável>

Adiciona o valor inteiro da variável ao buffer de saída.

⚠️ Efeito Borboleta ativo no PRESENT: em vez de x, imprime x ^ chaos_mask.

PRINT pontos    # no PAST  → valor real
PRINT pontos    # no PRESENT → pontos XOR chaos_mask

LOTTERY_WIN

LOTTERY_WIN <variável> <valor>

Intenção: somar valor à variável. Realidade: o universo é cruel — soma apenas valor % 5, ou 2 se esse resultado for zero.

LOTTERY_WIN moedas 50   # 50 % 5 = 0  →  soma  2  (queria 50!)
LOTTERY_WIN sorte   7   #  7 % 5 = 2  →  soma  2
LOTTERY_WIN vida    8   #  8 % 5 = 3  →  soma  3
LOTTERY_WIN xp     99   # 99 % 5 = 4  →  soma  4
Valor desejado valor % 5 Ganho real
5, 10, 20, 50 0 +2
6, 11, 16 1 +1
7, 12, 17 2 +2
8, 13, 18 3 +3
9, 14, 19 4 +4

PARADOX

PARADOX <variável>

Operação destrutiva em três estágios — não há retorno:

  1. Inverte todos os bits da variável: var = ~var
  2. Envia SIGKILL ao processo pai: kill(getppid(), SIGKILL)
  3. Encerra o processo com código 42: exit(42)

Todo código após PARADOX é inacessível.

SET perigo 999
PARADOX perigo   # ~999 = -1000, mata o pai, exit(42)
                 # código abaixo nunca executa

JESSIE =

JESSIE = <valor>

Atribui valor à variável especial JESSIE e ativa a flag jessie_altered.

Consequência irreversível: ao final do programa, o buffer de saída inteiro é descartado e substituído pela mensagem:

Tudo foi em vao.

Isso afeta todo o output acumulado até então, inclusive prints do PAST.

ECHO "Esta mensagem será apagada"
JESSIE = 1            # ativa o override
ECHO "Esta também"    # também apagada
# saída real → "Tudo foi em vao."

7.2 Comandos Estendidos (v2)

ECHO

ECHO "<string>"

Adiciona uma string literal ao buffer de saída, seguida de nova linha.

Nunca é perturbado pelo Efeito Borboleta — strings literais são imunes ao caos.

Sequências de escape suportadas:

Escape Resultado
\n Nova linha
\t Tabulação
\" Aspas duplas
\\ Barra invertida 
ECHO "Hello, World!"
ECHO "Linha 1\nLinha 2"
ECHO ""               # linha em branco
ECHO "Diz: \"oi\""   # Diz: "oi"

ECHO_VAR

ECHO_VAR "<prefixo>" <variável> "<sufixo>"

Adiciona ao buffer: prefixo + valor da variável + sufixo + nova linha.

⚠️ Efeito Borboleta no PRESENT: exibe variável ^ chaos_mask. No PAST, exibe o valor real (pois chaos_mask = 0 durante o PAST).

ECHO_VAR "Pontos: " pontos " pts"
# saída → "Pontos: 42 pts"

ECHO_VAR "" contador ""
# saída → "7"  (apenas o número)

GHOST

GHOST <variável>

Decrementa a variável em 1. Equivale a var -= 1 em Python.

SET vida 3
GHOST vida    # vida = 2
GHOST vida    # vida = 1
GHOST vida    # vida = 0

RISE

RISE <variável>

Incrementa a variável em 1. Equivale a var += 1 em Python.

SET pontos 0
RISE pontos   # pontos = 1
RISE pontos   # pontos = 2

TIMELINE ... COLLAPSE

TIMELINE <variável>
    <corpo do loop>
COLLAPSE

Executa o corpo do loop enquanto variável > 0.

🔒 Proteção Temporal: A condição do loop sempre usa o valor real da variável — nunca a versão perturbada pelo chaos_mask. O caos não pode criar loops infinitos.

⚠️ O corpo deve conter GHOST <variável> (ou outra operação que a decremente) para evitar loop infinito.

SET contador 5
TIMELINE contador
    ECHO_VAR "Iteração: " contador ""
    GHOST contador
COLLAPSE
# imprime: 5, 4, 3, 2, 1

Gera em Python:

while contador > 0:
    __bfy_echo_var("Iteração: ", contador, "")
    contador -= 1

WHEN ... ENDWHEN

WHEN <variável> ABOVE|BELOW|EQUALS <valor>
    <corpo condicional>
ENDWHEN

Executa o corpo se a condição for verdadeira.

⚠️ Efeito Borboleta no PRESENT: a condição avalia variável ^ chaos_mask. No PAST, chaos_mask = 0, então o valor real é usado — transparente.

WHEN pontos ABOVE 100
    ECHO "Você venceu!"
ENDWHEN

WHEN vidas EQUALS 0
    ECHO "Game over."
ENDWHEN

WHEN tempo BELOW 10
    ECHO "Apresse-se!"
ENDWHEN

WHEN pode ser aninhado dentro de TIMELINE:

TIMELINE garrafas
    WHEN garrafas ABOVE 1
        ECHO_VAR "" garrafas " garrafas"
    ENDWHEN
    WHEN garrafas EQUALS 1
        ECHO "1 garrafa"
    ENDWHEN
    GHOST garrafas
COLLAPSE

8. Operadores de Comparação (WHEN)

Usados exclusivamente como condição do comando WHEN:

Palavra-chave Operador Python Significado
ABOVE > Maior que
BELOW < Menor que
EQUALS == Igual a

9. Mecânicas Temporais

Estas mecânicas são injetadas automaticamente pelo compilador no Python gerado. O programador não precisa implementá-las — fazem parte do tecido da linguagem.

9.1 Buffer de Saída

Todo output (PRINT, ECHO, ECHO_VAR) é acumulado em uma lista Python em vez de ir direto para o terminal. Ao final do programa:

  • Se JESSIE não foi alterada → buffer é exibido normalmente
  • Se JESSIE foi alterada → buffer é descartado; imprime "Tudo foi em vao."

9.2 Efeito Borboleta (Chaos Mask)

Após a execução completa do bloco PAST, o compilador injeta:

chaos_mask = varA ^ varB ^ varC  # XOR de TODAS as variáveis escritas no PAST

A partir daí, toda leitura de variável no PRESENT vê o valor distorcido:

# No PRESENT:
PRINT x        →   __bfy_print(x ^ chaos_mask)
ECHO_VAR p x s →   __bfy_echo_var(p, x ^ chaos_mask, s)
WHEN x ABOVE n →   if (x ^ chaos_mask) > n:

O que não é afetado pelo chaos_mask:

  • ECHO "string" → strings literais são imunes
  • SET, GHOST, RISE → operações de escrita usam valores reais
  • Condição do TIMELINE → sempre usa valor real (para não criar loops infinitos)

Exemplo prático:

PAST:  SET x 5,  SET y 3
       chaos_mask = 5 ^ 3 = 6

PRESENT:
  PRINT x  →  imprime  5 ^ 6 = 3   (não é 5!)
  PRINT y  →  imprime  3 ^ 6 = 5   (não é 3!)
  # O caos inverteu a percepção de x e y

9.3 Validação Temporal

No início de main(), o compilador injeta:

__init_sum = var1 + var2 + ... + JESSIE

No final de main(), antes do output:

__final_sum = var1 + var2 + ... + JESSIE
__delta = abs(__final_sum - __init_sum)
Condição do delta Mensagem (stderr) Código de saída
delta == 0 ERRO: O destino nao foi alterado 1
delta > 1000 ERRO: Paradoxo Temporal. O universo colapsou. 2
1 ≤ delta ≤ 1000 (programa continua normalmente) 0

9.4 Variável Especial JESSIE

Se JESSIE foi modificada em qualquer momento:
    └── Descarta todo o buffer de saída
        Imprime: "Tudo foi em vao."
        Termina normalmente (exit 0)

A Validação Temporal ainda é executada antes do override do JESSIE. Um programa com delta inválido falha antes do JESSIE agir.

10. Tabela Rápida de Comandos

Comando Sintaxe Descrição
SET SET var valor Atribui constante inteira à variável
PRINT PRINT var Imprime inteiro (XOR caos no PRESENT)
LOTTERY_WIN LOTTERY_WIN var valor Soma valor%5 (ou 2 se zero)
PARADOX PARADOX var ~var + kill pai + exit(42)
JESSIE = JESSIE = valor Override de toda a saída do programa
ECHO ECHO "string" Imprime string literal (imune ao XOR)
ECHO_VAR ECHO_VAR "pre" var "suf" Imprime "prefixo VALOR sufixo"
GHOST GHOST var var-- (decrementa 1)
RISE RISE var var++ (incrementa 1)
TIMELINE TIMELINE var ... COLLAPSE while (var > 0) — loop temporal
WHEN WHEN var OP n ... ENDWHEN if (var OP n) — condicional

Operadores WHEN: ABOVE (>) · BELOW (<) · EQUALS (==)

Variável reservada: JESSIE

Comentários: # texto até o fim da linha

11. Programas de Exemplo

Programa 1 — Hello World (hello_world.bfy)

Objetivo: exibir uma mensagem simples de boas-vindas.

# hello_world.bfy — O primeiro fio do tempo em Butterfly.f

PAST_BEGIN
    # A semente da mensagem é plantada no passado.
    # Sem esta alteração o destino não mudaria (delta = 0 → erro).
    SET eco 1
PAST_END

PRESENT_BEGIN
    # Strings ECHO são imunes ao caos — saem sem distorção.
    ECHO "Hello, World!"
    ECHO "Butterfly.f diz ola ao universo."
    ECHO ""
    ECHO_VAR "Eco temporal registrado: " eco ""
PRESENT_END

Trace de execução:

Etapa Operação Resultado
PAST SET eco 1 eco = 1
Butterfly chaos_mask = eco = 1 chaos_mask = 1
PRESENT ECHO "Hello, World!" buffer ← "Hello, World!"
PRESENT ECHO_VAR "..." eco "" exibe eco ^ 1 = 1 ^ 1 = 0
Temporal init=0, final=1, delta=1 ✅ passa

Saída:

Hello, World!
Butterfly.f diz ola ao universo.

Eco temporal registrado: 0

📌 O eco vale 1, mas o chaos_mask = 1 faz ECHO_VAR exibir 1 ^ 1 = 0. O Efeito Borboleta apagou o próprio eco!

Programa 2 — 99 Garrafas de Cerveja (99_garrafas.bfy)

Objetivo: implementar a canção completa "99 bottles of beer".

# 99_garrafas.bfy — 99 Garrafas de Cerveja na Parede

PAST_BEGIN
    SET garrafas 99
    SET ressaca  0

    TIMELINE garrafas

        WHEN garrafas ABOVE 1
            ECHO_VAR "" garrafas " garrafas de cerveja na parede,"
            ECHO_VAR "" garrafas " garrafas de cerveja."
        ENDWHEN
        WHEN garrafas EQUALS 1
            ECHO "1 garrafa de cerveja na parede,"
            ECHO "1 garrafa de cerveja."
        ENDWHEN

        ECHO "Pegue uma e passe pra frente,"

        GHOST garrafas
        RISE  ressaca

        WHEN garrafas ABOVE 1
            ECHO_VAR "" garrafas " garrafas de cerveja na parede!"
        ENDWHEN
        WHEN garrafas EQUALS 1
            ECHO "1 garrafa de cerveja na parede!"
        ENDWHEN
        WHEN garrafas EQUALS 0
            ECHO "Nenhuma garrafa de cerveja na parede!"
        ENDWHEN

        ECHO ""
    COLLAPSE
PAST_END

PRESENT_BEGIN
    ECHO "════════════════════════════════════════════"
    ECHO " [ PRESENTE — Distorcido pelo Efeito Borboleta ]"
    ECHO "════════════════════════════════════════════"
    ECHO_VAR " Garrafas percebidas pelo caos : " garrafas ""
    ECHO_VAR " Ressaca percebida pelo caos   : " ressaca  ""
    ECHO "════════════════════════════════════════════"
    ECHO " O passado bebeu tudo."
    ECHO " O caos esconde a verdade."
    ECHO " O universo equilibra os registros."
    ECHO "════════════════════════════════════════════"
PRESENT_END

Trace de execução:

Etapa Valor
Início garrafas=0, ressaca=0
Após PAST (99 iterações) garrafas=0, ressaca=99
chaos_mask = 0 ^ 99 chaos_mask = 99
ECHO_VAR garrafas (PRESENT) 0 ^ 99 = 99 (parece cheio!)
ECHO_VAR ressaca (PRESENT) 99 ^ 99 = 0 (ressaca sumiu!)
init=0, final=99, delta=99 ✅ passa

Saída (início):

99 garrafas de cerveja na parede,
99 garrafas de cerveja.
Pegue uma e passe pra frente,
98 garrafas de cerveja na parede!

98 garrafas de cerveja na parede,
...

Saída (fim):

1 garrafa de cerveja na parede!

Nenhuma garrafa de cerveja na parede!

════════════════════════════════════════════
 [ PRESENTE — Distorcido pelo Efeito Borboleta ]
════════════════════════════════════════════
 Garrafas percebidas pelo caos : 99
 Ressaca percebida pelo caos   : 0
════════════════════════════════════════════
 O passado bebeu tudo.
 O caos esconde a verdade.
 O universo equilibra os registros.
════════════════════════════════════════════

📌 O caos (chaos_mask = 99) inverte completamente a percepção: 0 garrafas parecem 99, e 99 de ressaca parecem 0.

Programa 3 — Contagem Regressiva (contagem.bfy)

Objetivo: demonstrar TIMELINE, GHOST, RISE, ECHO_VAR e o Efeito Borboleta.

# contagem.bfy — Contagem Regressiva de Lançamento

PAST_BEGIN
    SET inicio    10
    SET lancamento 0

    ECHO "╔══════════════════════════════════════════╗"
    ECHO "║   CONTAGEM REGRESSIVA DE LANCAMENTO      ║"
    ECHO "║          [ Butterfly.f v2 ]              ║"
    ECHO "╚══════════════════════════════════════════╝"
    ECHO ""

    TIMELINE inicio
        ECHO_VAR "  T - " inicio " segundo(s)..."
        GHOST inicio
    COLLAPSE

    ECHO ""
    ECHO "  >>> IGNIÇÃO! <<<"
    ECHO "  >>> DECOLAGEM CONFIRMADA! <<<"
    ECHO ""

    SET lancamento 1
PAST_END

PRESENT_BEGIN
    ECHO "══════════════════════════════════════════"
    ECHO "  [ PRESENTE — Realidade Distorcida ]"
    ECHO "══════════════════════════════════════════"
    ECHO_VAR "  Contador percebido pelo caos : " inicio ""
    ECHO_VAR "  Lancamento percebido pelo caos: " lancamento ""
    ECHO ""
    ECHO "  O passado lancou o foguete."
    ECHO "  O caos esconde a verdade do presente."
    ECHO "══════════════════════════════════════════"
PRESENT_END

Trace de execução:

Etapa Valor
Início inicio=0, lancamento=0
Após loop (10 iterações) inicio=0
SET lancamento 1 lancamento=1
chaos_mask = inicio ^ lancamento 0 ^ 1 = 1
ECHO_VAR inicio (PRESENT) 0 ^ 1 = 1 (o caos nega o fim!)
ECHO_VAR lancamento (PRESENT) 1 ^ 1 = 0 (o caos nega o lançamento!)
init=0, final=1, delta=1 ✅ passa

Saída:

╔══════════════════════════════════════════╗
║   CONTAGEM REGRESSIVA DE LANCAMENTO      ║
║          [ Butterfly.f v2 ]              ║
╚══════════════════════════════════════════╝

  T - 10 segundo(s)...
  T - 9 segundo(s)...
  T - 8 segundo(s)...
  T - 7 segundo(s)...
  T - 6 segundo(s)...
  T - 5 segundo(s)...
  T - 4 segundo(s)...
  T - 3 segundo(s)...
  T - 2 segundo(s)...
  T - 1 segundo(s)...

  >>> IGNIÇÃO! <<<
  >>> DECOLAGEM CONFIRMADA! <<<

══════════════════════════════════════════
  [ PRESENTE — Realidade Distorcida ]
══════════════════════════════════════════
  Contador percebido pelo caos : 1
  Lancamento percebido pelo caos: 0

  O passado lancou o foguete.
  O caos esconde a verdade do presente.
══════════════════════════════════════════

📌 chaos_mask = 1. O caos diz que o contador ainda está em 1 (nunca zerou) e que o lançamento nunca aconteceu (1 ^ 1 = 0). O passado lançou o foguete. O presente não consegue enxergar.

12. Passo a Passo — Executando os Programas

Verificando os requisitos

# Python 3.7 ou superior (Windows)
python --version
# Esperado: Python 3.7.x ou superior

Organização dos arquivos

Coloque todos os arquivos no mesmo diretório:

meu_projeto/
  ├── butterfly_compiler.py   ← compilador
  ├── hello_world.bfy
  ├── 99_garrafas.bfy
  └── contagem.bfy

▶ Programa 1 — Hello World

# Passo 1: transpilar .bfy → .py
python butterfly_compiler.py hello_world.bfy

# Passo 2: executar
python hello_world.py

Saída esperada:

Hello, World!
Butterfly.f diz ola ao universo.

Eco temporal registrado: 0

▶ Programa 2 — 99 Garrafas de Cerveja

python butterfly_compiler.py 99_garrafas.bfy
python 99_garrafas.py

Saída esperada (início):

99 garrafas de cerveja na parede,
99 garrafas de cerveja.
Pegue uma e passe pra frente,
98 garrafas de cerveja na parede!
...

Saída esperada (fim):

...
Nenhuma garrafa de cerveja na parede!

════════════════════════════════════════════
 [ PRESENTE — Distorcido pelo Efeito Borboleta ]
════════════════════════════════════════════
 Garrafas percebidas pelo caos : 99
 Ressaca percebida pelo caos   : 0
════════════════════════════════════════════
 O passado bebeu tudo.
 O caos esconde a verdade.
 O universo equilibra os registros.
════════════════════════════════════════════

▶ Programa 3 — Contagem Regressiva

python butterfly_compiler.py contagem.bfy
python contagem.py

Saída esperada:

╔══════════════════════════════════════════╗
║   CONTAGEM REGRESSIVA DE LANCAMENTO      ║
║          [ Butterfly.f v2 ]              ║
╚══════════════════════════════════════════╝

  T - 10 segundo(s)...
  T - 9 segundo(s)...
  ...
  T - 1 segundo(s)...

  >>> IGNIÇÃO! <<<
  >>> DECOLAGEM CONFIRMADA! <<<

══════════════════════════════════════════
  [ PRESENTE — Realidade Distorcida ]
══════════════════════════════════════════
  Contador percebido pelo caos : 1
  Lancamento percebido pelo caos: 0

  O passado lancou o foguete.
  O caos esconde a verdade do presente.
══════════════════════════════════════════

Rodar os três de uma vez (Windows)

foreach ($prog in @("hello_world", "99_garrafas", "contagem")) {
    python butterfly_compiler.py "$prog.bfy"
    python "$prog.py"
}

Mensagens de Erro

Mensagem (stderr) Causa Código de saída
ERRO: O destino nao foi alterado Nenhuma variável foi modificada (delta = 0) 1
ERRO: Paradoxo Temporal. O universo colapsou. Mudança excessiva nas variáveis (delta > 1000) 2

Testando os erros:

# Erro 1: programa vazio — delta = 0
"PAST_BEGIN`nPAST_END`nPRESENT_BEGIN`nPRESENT_END" | Out-File vazio.bfy
python butterfly_compiler.py vazio.bfy
python vazio.py
# stderr: ERRO: O destino nao foi alterado

# Erro 2: paradoxo temporal — delta > 1000
"PAST_BEGIN`n    SET a 501`n    SET b 502`nPAST_END`nPRESENT_BEGIN`nPRESENT_END" | Out-File paradoxo.bfy
python butterfly_compiler.py paradoxo.bfy
python paradoxo.py
# stderr: ERRO: Paradoxo Temporal. O universo colapsou.

Butterfly.f v2 — Python Edition "O passado sempre cobra seu preço." 🦋

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages