advpl-fundamentals — Convenções básicas ADVPL/TLPP

ADVPL (Advanced Protheus Language) e seu sucessor TLPP são linguagens proprietárias da TOTVS, derivadas do Clipper/xBase. Têm convenções fortes que não são opcionais em código de qualidade Protheus.

Quando usar

• Antes de gerar qualquer função/variável ADVPL.
• Quando o usuário pede para criar User Function, Static Function, Main Function.
• Ao revisar nomes de variáveis ou funções existentes.
• Ao decidir se um símbolo é do customer, do TOTVS padrão, ou de uma biblioteca terceira.
• Antes de chamar qualquer função "esquisita" (consulte funcoes_restritas).

Notação húngara — obrigatória

Toda variável ADVPL começa com um prefixo de tipo (1 letra minúscula) seguido de PascalCase:

Violação dispara BP-006 no lint (severidade info).

// CORRETO
Local cCodCli := "000001"
Local nValor  := 1500.00
Local lOk     := .T.

// ERRADO — sem prefixo, parecido com C
Local codigo := "000001"
Local valor  := 1500.00

Prefixo de cliente em User Function

User Function é o ponto de entrada de customização. Por convenção institucional, o nome deve começar com um prefixo de 2–3 letras do cliente para evitar colisão com customizações de outros parceiros instaladas no mesmo RPO.

// Cliente "XYZ"
User Function XYZValCli(cCod)  // OK
    Return .T.

// Sem prefixo — risco de sobrescrever User Function homônima de outro fornecedor
User Function ValCli(cCod)     // EVITAR
    Return .T.

Combine com o pattern de PE: User Function MT100LOK() (PE oficial, sem prefixo cliente — exceção justificada).

Prefixos de módulo (rotinas TOTVS padrão)

Funções/rotinas oficiais TOTVS seguem padrões de prefixo por módulo. Conhecer ajuda a localizar rapidamente:

Use o lookup modulos_erp (carregado em /plugadvpl:init) para a lista completa.

Naming — funções

• User Function → customização do cliente, prefixo cliente.
• Static Function → privada ao fonte, sem prefixo cliente obrigatório.
• Main Function → entrypoint de JOB, scheduler, MainAdvpl.
• Class ... Method → OOP (preferido em TLPP).

Toda função (incluindo Static) deveria ter cabeçalho Protheus.doc (regra BP-007, severidade info):

/*/{Protheus.doc} XYZValCli
Valida codigo do cliente conforme regra fiscal do cliente XYZ.
@type function
@author Equipe ABC
@since 2024-01-15
@param cCod, character, codigo do cliente
@return logical, .T. se valido
/*/
User Function XYZValCli(cCod)
    Return AllTrim(cCod) != ""

Funções restritas pela TOTVS — 195 catalogadas

TOTVS mantém uma lista de funções, classes e variáveis internas que não devem ser usadas em customização:

• Não documentadas, não suportadas.
• Podem ser removidas/alteradas sem aviso.
• Algumas têm compilação bloqueada desde release 12.1.33.

Exemplos comuns que aparecem em código legado:

• MV_PAR01..MV_PARxx (use ParamBox/Pergunte parametrizados em vez de leitura direta).
• nUsado (variável interna do framework).
• Várias funções com prefixo __ ou Fwk/FW internas.

Antes de usar qualquer função "que parece nativa", consulte:

/plugadvpl:find function <nome>

Se aparecer em funcoes_restritas, não use. Dispara SEC-005 (crítico) no lint.

Tipos primitivos e operadores

• Atribuição: := (não =).
• Igualdade: == (estrito) ou = (igualdade ADVPL, depende do contexto).
• Diferente: != ou <>.
• .T. / .F. — true / false.
• Conversão: cValToChar, Val, StoD (string-to-date), DtoC, DtoS.

Anti-padrões

• Nomes sem prefixo húngaro → lint BP-006.
• Declarar Local no meio do código (depois de If/While) → lint BP-002 (crítico).
• Usar Private/Public quando Local resolveria → lint BP-002b.
• User Function sem prefixo cliente → risco de colisão entre fornecedores.
• Usar MV_PAR01 direto sem ParamBox → fragil, perde controle.
• Shadowing de variável reservada (cFilAnt, cEmpAnt, __cInternet) → lint BP-008 (crítico).

Referência rápida

Comandos plugadvpl relacionados

• /plugadvpl:find function <nome> — descobre se função é nativa, restrita ou customer.
• /plugadvpl:lint <arq> — valida convenções (BP-001..008).
• /plugadvpl:callers <fn> — vê quem chama uma função antes de renomear.

Referência profunda

Para detalhes completos (~2.9k linhas), consulte reference.md ao lado deste arquivo:

• Histórico ADVPL/Clipper e arquitetura do RPO/APO compilado.
• Diretivas de pré-processamento (#include, #define, #command, #xcommand, #translate) com exemplos.
• Catálogo expandido de funções de string, data, array, conversão (Substr, At, Asc, Time, MonthName, AScan, ASort, AEval).
• Estruturas de controle avançadas (Begin Sequence/Break/Recover, For Each, code blocks).
• Tabela completa de prefixos de módulo (50+ módulos com tabelas/rotinas típicas) e regras de naming.