Referência de sintaxe Spintax

Referência completa para a marcação de templates spintax.

Enumerações { }

Seleciona aleatoriamente uma opção da lista.

{option1|option2|option3}

Exemplos

{blue|grey|clear}
{|free|paid} plan                 ← empty option = sometimes nothing
{Acme {Pro|Lite}}                ← nested enumerations
{order {|#42-A} confirmed}       ← nesting with empty option

Regras

• Delimitadores: { e }
• Separador: |
• Suporta aninhamento em profundidade arbitrária
• Opções vazias são válidas (produzem string vazia)
• A resolução vai da expressão mais interna para fora

Permutações [ ]

Seleciona N elementos, embaralha e junta com separadores.

Permutações simples

Todos os elementos incluídos, separados por espaços:

[1|2|3|4]

Exemplos de saída: 1 4 3 2, 2 3 4 1, 3 2 4 1

Com separador

Separador uniforme especificado em < > no início:

[<, > 1|2|3|4]

Exemplos de saída: 2, 1, 4, 3, 4, 3, 2, 1

Importante: Sem espaço entre [ e <separador>.

Separadores por elemento

Cada opção pode ter seu próprio separador definido com <sep> antes do | anterior. O separador viaja com seu elemento durante a mistura.

[<, > 1|2|3 < and >|4]

Exemplos de saída: 1, 3, 2 and 4, 3, 1, 2 and 4

Espaçamento automático: Separadores de palavras como <and> ou <or> são automaticamente preenchidos com espaços: <and> produz  and . Separadores de pontuação (<,>) não são preenchidos.

Permutações com combinações

Quantidade mínima/máxima de elementos e separadores configuráveis:

[<minsize=1;maxsize=3;sep=", ";lastsep=" and "> apple|plum|orange|apricot]

Exemplos de saída: apple, plum and orange, apple and apricot, orange

Parâmetros de configuração

Regras de permutação

• Delimitadores: [ e ]
• O bloco de configuração <...> deve seguir imediatamente [
• Os parâmetros de configuração são separados por ponto e vírgula
• Valores de string na configuração estão entre aspas: sep=", "
• Enumerações e permutações podem ser aninhadas dentro das opções
• Elementos HTML podem ser opções

Variáveis %var%

Define uma variável reutilizável que é substituída onde quer que apareça.

#set %VARIABLE_NAME% = value or spintax structure
#def %VARIABLE_NAME% = value or spintax structure

Exemplos

#set %name% = John
#set %greeting% = {Hello|Hi|Hey}
#set %items% = [<minsize=2;maxsize=3;sep=", ";lastsep=" and "> apples|oranges|bananas]
Some text with %name% and %greeting%, also %items%.

/# %greeting% above may differ between the two references — #set re-rolls.
   #def picks once and keeps it: #/
#def %tone% = {friendly|warm|upbeat}
A %tone% intro, and a %tone% outro — always the same word.

Regras de variáveis

• #set e #def devem iniciar no começo de uma linha
• Nomes de variáveis são delimitados por %: %nome%
• Nomes de variáveis são alfanuméricos + underscore
• Valores podem conter qualquer sintaxe spintax (enumerações, permutações, outras variáveis)
• Variáveis #set são expandidas quando referenciadas, não quando definidas (avaliação preguiçosa)
• #set é uma macro: seu valor é substituído novamente — e o spintax dentro dele sorteado de novo — a cada referência. #def resolve seu valor uma vez por renderização e mantém esse resultado em todos os lugares
• Linhas #set e #def são removidas da saída

Escopos de variáveis no plugin WordPress

O plugin suporta três escopos de variáveis. Quando o mesmo nome existe em múltiplos escopos, o escopo mais forte prevalece:

1. Variáveis de runtime (mais forte) — passadas via shortcode: [spintax slug="greeting" name="Alice"]
2. Variáveis locais — definidas com #set ou #def dentro do template
3. Variáveis globais (mais fraco) — definidas na página de Configurações

Condicionais {?VAR?then|else}

Os condicionais são a extensão distintiva do spintax.net à família GTW. Enquanto {a|b} é uma escolha aleatória uniforme que ignora variáveis, {?VAR?then|else} escolhe com base em %VAR% ter ou não um valor.

Use-o para escolhas orientadas por valor: mostrar uma linha de plano gratuito apenas quando existir, renderizar um bloco de recursos pro apenas quando o usuário estiver em um plano pago, ocultar um CTA não aplicável.

O pré-passo roda antes da expansão de %var% e antes do seletor aleatório de ramos, então um ramo falsy é totalmente descartado — nada em seu interior é avaliado.

Formas

{?VAR?then}                ← truthy ⇒ then; falsy ⇒ empty
{?VAR?then|else}           ← truthy ⇒ then; falsy ⇒ else
{?!VAR?then|else}          ← inverted

{?HasFreeTier? — free tier available since %founded%|, trusted since %founded%}

Truthy e falsy

A regra é deliberadamente mais simples que em JavaScript — truthy = pelo menos um caractere não-espaço:

Regras dos condicionais

• Nomes de variáveis seguem a mesma regex que %var% (sem distinção de maiúsculas)
• O prefixo ! inverte a verificação: {?!VAR?ausente}
• O primeiro | de profundidade 0 separa then de else; os seguintes ficam literais em else
• Condicionais aninhados são avaliados de fora para dentro — ramos falsy curto-circuitam
• Lógica composta (&&, ||, comparações) não é suportada — pré-calcule uma variável guarda no assemblador
• Formas malformadas ({??yes}, {?VAR}) nunca lançam — o playground as marca como avisos
• Aprofundar: veja o guia de spintax condicional com exemplos e anti-padrões

Plurais {plural %n%: idioma|idiomas}

Escolhe a forma gramaticalmente correta de uma palavra conforme um número. O contador vem antes dos dois pontos e as formas depois, separadas por |.

A forma é escolhida pela locale do render, não pelo template — portanto quantas formas você precisa fornecer depende dessa locale. O inglês pede duas, o russo três.

{plural %n%: form1|form2}          ← 2-form locale (en, de, es…)
{plural %n%: form1|form2|form3}    ← 3-form locale (ru, uk, sr…)

#def %LangCount% = 5
supports %LangCount% {plural %LangCount%: language|languages}
← supports 5 languages

Formas por locale

A locale é comparada pelo seu subtag de idioma, então ru-RU e ru se comportam igual:

Se a quantidade de formas não bater, o motor reporta plural.arity e deixa o bloco visível com chaves de largura total — um plural errado nunca vai ao ar em silêncio.

Regras dos plurais

• A abertura é literal, incluindo o espaço: {plural . {plural: x} e {pluralN: x} não são blocos plurais
• Os dois pontos são obrigatórios — separam o contador das formas
• O contador é uma referência %Var% ou um inteiro literal; variáveis no contador são substituídas antes da escolha da forma
• Números negativos usam o valor absoluto; o 0 recebe a forma "todo o resto"
• Uma variável contadora deve ser #def, não #set — #set é uma macro, então um valor como {1|4|9} ainda é spintax não resolvido na hora de decidir o plural e o bloco renderiza vazio. O playground sinaliza isso como plural.count-macro
• Um contador não numérico ou indefinido apaga o bloco em vez de adivinhar
• Aprofundar: veja o guia de plurais com as regras russas de três formas e exemplos resolvidos

Includes #include

Incorpora outro template na posição da diretiva.

#include "hero-text"

Regras de include

• A referência do template está entre aspas duplas
• Resolve por slug do template ou ID numérico
• Templates incluídos podem conter suas próprias variáveis e spintax
• Includes recursivos são suportados
• Referências circulares são detectadas e bloqueadas
• Templates filhos herdam variáveis globais e de runtime, mas não as locais #set / #def do pai

Comentários /#...#/

O texto entre marcadores de comentário é removido da saída antes de qualquer outro processamento.

/#
  This is a comment section.
  It can span multiple lines.
  It won't appear in output.
#/

Regras de comentários

• Delimitador de início: /#
• Delimitador de fim: #/
• Podem abranger múltiplas linhas
• Não podem ser aninhados
• Removidos antes de qualquer outro processamento

Aninhamento

Todos os elementos de sintaxe podem ser aninhados uns dentro dos outros em profundidade arbitrária:

{option1|[<, > sub1|sub2|sub3]|option3}

[<minsize=2;maxsize=3;sep=", ";lastsep=" and "> {red|blue} apples|{big|small} oranges|bananas]

#set %var% = {a|[b|c]}

Pós-processamento

O motor aplica correção automática de texto após a geração:

1. Protege URLs, emails, domínios, decimais e abreviações da capitalização
2. Elimina espaços e tabulações duplicados
3. Remove espaços antes da pontuação (, . ! ?)
4. Adiciona espaço após pontuação onde falta
5. Capitaliza a primeira letra da saída (pulando tags HTML)
6. Capitaliza após pontuação de fim de frase
7. Capitaliza após tags HTML de nível de bloco
8. Capitaliza após quebras de linha
9. Restaura os marcadores protegidos

Resumo da sintaxe

A sintaxe é compatível com o padrão Generating The Web (GTW).