advpl-encoding — cp1252 / utf-8 preserve-by-default

advpl-encoding — cp1252 / utf-8 preserve-by-default

Fontes ADVPL/TLPP em projetos Protheus reais misturam dois encodings:

• .prw / .prx clássicos → cp1252 (Windows-1252) — padrão histórico, herdado do Clipper.
• .tlpp moderno → UTF-8 é suportado e recomendado pela TOTVS para código novo.

Em clientes grandes essas duas extensões coexistem no mesmo repositório. Algumas codebases legadas chegam a ter .prw em UTF-8 (raro, mas existe). A regra é: preserve o encoding detectado, nunca normalize por conta própria.

Quando usar

• Antes de qualquer Edit ou Write em .prw, .prx, .tlpp.
• Quando o usuário menciona "acento errado", "ç", "ã", "caractere quebrado", "mojibake", "encoding".
• Quando ler um arquivo via Read e ver ç ou ã no output (sinal de cp1252 lido como utf-8).
• Antes de rodar /plugadvpl:ingest em base nova (verifique a política).
• Em REST/WebService onde XML/JSON entra UTF-8 e o fonte é cp1252.
• Em scripts auxiliares (instalador .ps1, .sh) que vão ser lidos por terminal cp1252.

Caracteres que tipicamente quebram (mojibake)

Ao salvar cp1252 como UTF-8 (ou vice-versa) sem decodificar corretamente, estes caracteres viram lixo:

Char cp1252	Byte cp1252	Lido como UTF-8 (mojibake)
ç	0xE7	ç
ã	0xE3	ã
á	0xE1	á
é	0xE9	é
ó	0xF3	ó
Á	0xC1	Ã
°	0xB0	°
— (em-dash)	0x97	â
↔ (arrow)	(não existe cp1252)	crash UnicodeEncodeError

Comentários // Atualizacao viram // Atualização quando lidos errado. Pior: o compilador AppServer rejeita o arquivo, ou compila e quebra strings em runtime.

Char fora do cp1252 = crash: ↔ (U+2194), → (U+2192), box-drawing (─, │), emojis. Não existem em cp1252 → quando Python/AppServer tenta encodar cp1252, dá UnicodeEncodeError: 'charmap' codec can't encode character. Foi exatamente o bug da v0.3.0 do plugadvpl no --help em Windows PS 5.1.

Como o parser plugadvpl detecta

Algoritmo real (parser.py, validado em ampla base de fontes ADVPL):

1. ASCII-only → reporta "cp1252" (default Protheus; ASCII é subset).
2. UTF-8 strict válido (tem multi-byte chars que decodam como UTF-8) → "utf-8".
3. cp1252 fast-path (99% dos fontes Protheus com chars latinos) → "cp1252".
4. chardet[:4096] (sample do início do arquivo) → heurística, último fallback.
5. latin-1 se chardet falhar.

Detalhe técnico: a ordem UTF-8 strict antes de cp1252 é proposital. cp1252 só tem 5 bytes indefinidos (0x81/8D/8F/90/9D); todos os outros valores 0x00-0xFF são "válidos" em cp1252. Então tentar cp1252 primeiro misdecodaria silenciosamente bytes UTF-8 multi-byte como sequência de chars latinos. UTF-8 strict rejeita bytes cp1252 típicos (ã = 0xE3 sozinho não forma sequência UTF-8 válida).

A extensão não influencia a ordem — .tlpp segue o mesmo algoritmo. Mas como .tlpp na prática tem mais chars multi-byte, o passo 2 acerta primeiro.

A coluna encoding da tabela fontes (não "sources") registra o resultado. Consulte antes de editar:

SELECT arquivo, encoding FROM fontes WHERE arquivo = 'XXX.prw';

Ou via CLI: /plugadvpl:doctor mostra distribuição de encoding na base.

Política --encoding-policy no ingest

/plugadvpl:ingest aceita uma das três políticas:

• preserve (default) — armazena o encoding detectado por fonte, não impõe regra global. Recomendado.
• cp1252 — assume cp1252 para .prw/.prx; emite warning para .tlpp UTF-8 detectado.
• utf8-warn — emite warning para qualquer fonte que NÃO seja UTF-8 (útil em migração ativa).

Para edição feita por Claude, preserve sempre.

Funções ADVPL de conversão runtime

Quando o código precisa misturar encodings em runtime (ex: REST que recebe JSON UTF-8 num fonte cp1252):

Função	Direção	Quando usar
EncodeUTF8(cStr)	cp1252 → UTF-8	Antes de enviar string ADVPL pra REST/JSON
DecodeUTF8(cStr)	UTF-8 → cp1252	Após receber body UTF-8 de REST/JSON
STRICONV(cStr, nCodepage)	cp1252 ↔ outras	Conversões cross-codepage (sistemas externos)

// Recebendo body REST UTF-8 e gravando em fonte cp1252
WSMETHOD POST cadastraCliente WSRECEIVE cBody WSSERVICE zClientes
    Local oJson := Nil
    Local cBody := DecodeUTF8(Self:GetContent())   // converte UTF-8 → cp1252

    FwJsonDeserialize(cBody, @oJson)
    RecLock("SA1", .T.)
    SA1->A1_NOME := AllTrim(oJson:nome)   // string cp1252, OK pra gravar
    MsUnlock()
Return .T.

// Enviando resposta JSON UTF-8 a partir de dados cp1252
WSMETHOD GET listaClientes WSSERVICE zClientes
    Local cResp := '{"nome":"' + AllTrim(SA1->A1_NOME) + '"}'
    Self:SetResponse(EncodeUTF8(cResp))           // converte cp1252 → UTF-8
Return .T.

Quirk: EncodeUTF8() com char inválido retorna NIL e loga warning no console.log do AppServer. Sempre verifique retorno em rotinas críticas.

XML é exceção: o parser XML do ADVPL internamente já faz UTF-8 ↔ cp1252 — você lê chars como á, ç direto no XmlElem:Text sem conversão manual.

Display correto no console do AppServer (Windows)

ConOut/FwLogMsg no console.log aparece com mojibake se o terminal estiver em codepage diferente:

:: appserver.bat — antes de subir
chcp 1252
TotvsAppServer.exe -console

Pra Linux/WSL: locale pt_BR.iso-8859-1 ou converter o log com iconv na hora de ler.

Workflow correto antes de Edit — ⚠️ CRÍTICO

🚨 PERIGO: o Read tool do Claude Code lê .prw cp1252 como UTF-8. Bytes acentuados (0x80-0xFF) viram � (U+FFFD). Se você fizer Edit nessa visão, o Edit regrava o arquivo inteiro em UTF-8, com � no lugar dos acentos não-editados. Acentos não-editados ficam corrompidos. Bug clássico do reporter, v0.8.8 doc.

Workflow obrigatório pra editar .prw cp1252 com Claude (Caminho A)

# 1. ANTES de Read/Edit: converte cp1252 -> utf-8 (preserva acentos)
plugadvpl edit-prw stage <fonte.prw>
# Atalho de: plugadvpl edit-prw save <fonte> --from cp1252 --to utf-8
# Cria .bak automático com bytes cp1252 originais

# 2. Agora Read mostra "Função" certinho. Edit/Write podem operar sem perda.
#    O ARQUIVO está temporariamente em UTF-8 — não compila assim, mas
#    o Claude vê tudo correto.

# 3. DEPOIS das edições: volta pra cp1252 (acentos novos viram bytes 0xE7 etc.)
plugadvpl edit-prw commit <fonte.prw>
# Atalho de: plugadvpl edit-prw save <fonte> --from utf-8 --to cp1252
# Detecta automático que o arquivo está em utf-8 agora

Caminhos alternativos

Caminho B — edição cirúrgica via PowerShell em cp1252 nativo (zero conversão):

$path = "Customizados\FOO.PRW"
$enc  = [System.Text.Encoding]::GetEncoding(1252)
$txt  = $enc.GetString([System.IO.File]::ReadAllBytes($path))
$txt  = $txt -replace 'PADRAO_VELHO', 'PADRAO_NOVO'
[System.IO.File]::WriteAllBytes($path, $enc.GetBytes($txt))

Bom quando a mudança é mecânica (find/replace). Verboso pra refactor complexo.

Caminho C — restringir Edit a trechos ASCII puro (frágil): Só edita linhas sem � no Read output. Mas o Edit regrava arquivo inteiro e os � ficam → bug. NÃO RECOMENDADO.

Regras gerais

1. Consulte o encoding indexado primeiro: plugadvpl --format json doctor (ou SELECT encoding FROM fontes WHERE arquivo='X.prw').
2. Se Claude vê mojibake no Read (Funç..., ç, �), não é o arquivo que está corrompido — é a tool lendo errado. Confirme com plugadvpl edit-prw check <fonte>.
3. Ao editar: ou use Caminho A (stage/commit), ou Caminho B (PowerShell nativo). NUNCA edite direto via Claude Edit se o Read mostrou �.
4. Para arquivos novos: siga a extensão. .prw novo → cp1252; .tlpp novo → UTF-8.
5. Scripts auxiliares (.ps1, .sh, .bat) que rodam em terminal cp1252 → ASCII-only é mais portável. UTF-8 BOM nesses scripts atrapalha mais que ajuda (causa parse errors em PS 5.1).

Exemplo — comentário com acento

.prw (cp1252, byte 0xE7 para ç):

// Funcao de validacao do codigo do cliente
User Function ValCli()
    Local cMsg := "Operacao concluida com sucesso"
Return .T.

Como exibição em markdown, vou usar comentário sem acentos pra clareza. No fonte real, ç, ã, é estão lá literalmente como bytes cp1252 — Claude/IDE precisa decodar como cp1252 pra ler corretamente.

Os bytes do source: // Fun\xe7\xe3o de valida\xe7\xe3o. Se Claude leu como UTF-8, vai ver // Função. Não "conserte" isso editando — o arquivo está correto, o problema é o decoder.

Anti-padrões

• "Vou normalizar tudo pra UTF-8 para evitar problemas" → NÃO. Quebra compilação no AppServer clássico, desalinha includes #include "TOTVS.CH", dispara EncodeUTF8() falhas em runtime.
• Salvar .prw com BOM UTF-8 (EF BB BF) → AppServer rejeita.
• Salvar .ps1/.sh/.bat com BOM UTF-8 → terminal PS 5.1 não reconhece, parser quebra (bug real do install.ps1 v0.3.1).
• Editar .tlpp em cp1252 só porque o resto do projeto é cp1252 → perde recurso natural do TLPP (chars Unicode, emoji em strings, etc.).
• Confiar em "abrir e olhar" — use file -i (Linux/WSL) ou /plugadvpl:doctor para encoding real.
• Concatenar string cp1252 com retorno de REST sem DecodeUTF8 → byte sequences inválidos no SQL.
• Acento em identificador (cNomeCliênte) — compilador aceita mas quebra deserialização cross-encoding (CSV, REST). Veja [[advpl-fundamentals]].
• Char fora de cp1252 (setas ↔/→, emojis, box-drawing) em string de fonte .prw → UnicodeEncodeError em runtime quando AppServer tenta exibir.

Referência rápida

Extensão	Encoding esperado	Alternativa aceita	Política Claude
.prw	cp1252	(raro) utf-8	preserve
.prx	cp1252	—	preserve
.tlpp	utf-8	cp1252 (legado)	preserve
.ch	cp1252	utf-8	preserve
.th	utf-8	—	preserve
.ps1/.sh (instaladores)	ASCII-only OU UTF-8 sem BOM	—	preserve, ASCII se possível
Body REST/JSON	utf-8	—	EncodeUTF8/DecodeUTF8

Cross-references com outras skills

• [[advpl-fundamentals]] — char ASCII-only em identificadores; .prw (cp1252, 10 chars) vs .tlpp (utf-8, 250 chars).
• [[advpl-webservice]] — REST/JSON precisa EncodeUTF8/DecodeUTF8 ao entrar/sair do fonte cp1252.
• [[advpl-web]] — Webex/HTML serve em UTF-8; conversão é obrigatória.
• [[advpl-debugging]] — mojibake é sintoma frequente; primeiro passo é /plugadvpl:doctor.
• [[advpl-code-review]] — não há regra de lint específica de encoding ainda (gap conhecido).
• [[plugadvpl-index-usage]] — /plugadvpl:doctor checa encoding real de cada fonte ingesto.

Comandos plugadvpl relacionados

• /plugadvpl:doctor — checa encoding real de cada fonte ingesto.
• /plugadvpl:ingest --encoding-policy {cp1252|preserve|utf8-warn} — controla detecção.
• /plugadvpl:status — mostra distribuição de encodings na base.
• Query direta: SELECT encoding, COUNT(*) FROM fontes GROUP BY encoding.

Sources

• O que é CODEPAGE e ENCODING - Tudo em AdvPL
• EncodeUTF8 - TDN
• Aplicando codificação UTF-8 com DecodeUTF8 e EncodeUTF8 - Maratona AdvPL TL++ 138
• Acentuação FWRest AdvPL - DevForum TOTVS
• Como mudar codificação padrão no VSCode - Terminal de Informação
• Tag CP-1252 - Tudo em AdvPL
• Tag UTF-8 - Tudo em AdvPL