Opções de análise

TParseOptions é um conjunto de sinalizadores TParseOption passados à função ParseInput para controlar o processamento após a tokenização. O valor predefinido é [] (sem opções).

Referência de opções

Opção Aplica-se a Efeito
opTrim Todos os tipos Remove os espaços em branco à esquerda e à direita de cada token antes de qualquer outro processamento.
opRequired Todos os tipos Rejeita entradas vazias; define ERR_EMPTY_NOT_ALLOWED.
opNotNull Todos os tipos Rejeita qualquer token que resulte em NULL; define ERR_NULL_NOT_ALLOWED.
opEmptyStringNull Apenas itString Os tokens vazios string produzem NULL em vez de ''.
opUpperCase Apenas itString Converte os valores dos tokens para maiúsculas.
opLowerCase Apenas itString Converte os valores dos tokens para minúsculas.

opTrim

Remove os espaços em branco à esquerda e à direita de cada valor de token antes de qualquer outro processamento. Para tipos que não sejam string (itInteger a itDateTime), os espaços já são removidos globalmente de toda a entrada antes da tokenização. opTrim não tem qualquer efeito adicional nesses tipos; é aceite silenciosamente. Para itString, os espaços são significativos por predefinição e são preservados como parte do valor. opTrim é a única forma de os remover:

Entrada: "  hello  ", itString, sem opções
  Valores[0]: "  hello  "    (espaços preservados)

Entrada: "  hello  ", itString, [opTrim]
  Valores[0]: "hello" (espaços removidos)

Quando opRequired também está definido, opTrim é aplicado primeiro. Uma entrada composta apenas por espaços só fica vazia após a remoção dos espaços e desencadeia ERR_EMPTY_NOT_ALLOWED.

opRequired

A entrada completa (após opTrim, quando presente) não pode estar vazia. Esta verificação é executada antes da tokenização, pelo que se aplica à entrada na sua totalidade string e não a tokens individuais. Quando a entrada está vazia, ResultType é definido como otInvalid e ErrorCode é ERR_EMPTY_NOT_ALLOWED.

Entrada: "", itInteger, [opRequired]
  ResultType: otInvalid
  ErrorCode:  ERR_EMPTY_NOT_ALLOWED

Entrada: "  ", itString, [opRequired, opTrim]
  ResultType: otInvalid
  ErrorCode:  ERR_EMPTY_NOT_ALLOWED

O opRequired é verificado antes do opNotNull. Quando ambos estão definidos e a entrada está vazia, apenas ERR_EMPTY_NOT_ALLOWED é devolvido.

opNotNull

Após a execução completa do ciclo de tokens, qualquer token cuja entrada SQLValues[] seja NULL faz com que ErrorCode seja definido como ERR_NULL_NOT_ALLOWED. ResultType é definido como otInvalid. Esta opção é útil quando as posições vazias numa lista ou os limites vazios de um intervalo devem ser rejeitados, em vez de serem silenciosamente convertidos para NULL.

Entrada: "1,,3", itInteger, [opNotNull]
  ResultType: otInvalid
  ErrorCode:  ERR_NULL_NOT_ALLOWED   (o token do meio é NULL)

Entrada: "1,,3", itInteger, []
  ResultType: otList
  SQLExpression: IN (1, NULL, 3)     (NULL aceite)

opNotNull não é verificado quando ERR_EMPTY_NOT_ALLOWED já tiver sido definido. Para itString sem opEmptyStringNull, os tokens vazios produzem '' (não NULL), pelo que opNotNull não é acionado para esses casos. Combine opEmptyStringNull com opNotNull para rejeitar tanto tokens vazios strings como tokens mapeados para NULL.

opEmptyStringNull

Aplica-se apenas a itString. Os tokens vazios — entradas originalmente vazias, posições vazias na lista e strings vazios entre aspas '' — produzem NULL em SQLValues[] em vez de um string vazio entre aspas ''.

Entrada: "hello;;world", itString, [opEmptyStringNull]
  SQLValues: ['hello', NULL, 'world']
  SQLExpression: IN ('hello', NULL, 'world')

Entrada: "hello;;world", itString, []
  SQLValues: ["'hello'", "''", "'world'"]
  SQLExpression: IN ('hello', '', 'world')

Quando combinados com opNotNull, os tokens vazios string provocam o erro ERR_NULL_NOT_ALLOWED.

opUpperCase / opLowerCase

Converte os valores dos tokens de itString para maiúsculas ou minúsculas. A conversão é aplicada tanto a Values[] como ao conteúdo dentro de SQLValues[] (entre aspas). Palavras-chave SQL como BETWEEN, IN, NULL, DATE e TIME não são afetadas.

Entrada: "hello", itString, [opUpperCase]
  Values[0]: "HELLO"
  SQLValues[0]: "'HELLO'"

Entrada: "hello", itString, [opLowerCase]
  Values[0]: "hello"
  SQLValues[0]: "'hello'"

Se tanto opUpperCase como opLowerCase estiverem definidos, opUpperCase tem precedência. opUpperCase e opLowerCase são ignorados silenciosamente para todos os tipos que não sejam string. A conversão é ignorada para tokens que resultaram em NULL (por exemplo, através de opEmptyStringNull); a palavra-chave NULL é preservada tal como está.

Resumo de precedência e interação

Ordem de processamento numa chamada ParseInput:

  1. opTrim (quando definido) — aplicado a toda a entrada antes de qualquer outro passo.
  2. opRequired — verificado em relação à entrada (possivelmente aparada); interrompe com ERR_EMPTY_NOT_ALLOWED se estiver vazio.
  3. Tokenização — a entrada é dividida em tokens.
  4. Processamento por token — análise de tipos, opTrim por token (para listas), opEmptyStringNull, opUpperCase/opLowerCase.
  5. opNotNull — verificado após o ciclo completo de tokens; interrompe com ERR_NULL_NOT_ALLOWED se alguma entrada de SQLValues[] for NULL.
  6. Verificação da ordem do intervalo — aplicada após opNotNull.
(C) 2026 Easygate, Lda