Skip to main content

API padrão

A engine padrão disponibiliza uma API com várias funções utilitárias para manipulação de datas, caracteres e números. As funções são separadas por classes e são invocadas como métodos. Alguns métodos para manipulação de datas e caracteres podem ser utilizados de maneira direta, invocando o método a partir do próprio elemento, não necessitando a invocação através da classe.

Este capítulo abordará detalhes de cada função da API padrão. Essas funções estarão disponíveis ao usuário final e serão absorvidas plenamente conforme a utilização.

Funções para manipulação de caracteres

A seguir são descritas todas as funções disponíveis para a manipulação de caracteres. Da mesma forma que para as funções de manipulação de números, serão apresentadas as funções, sua descrição e sintaxe em uma tabela, a fim de facilitar o entendimento.

FUNÇÃODESCRIÇÃO / OBJETIVOSINTAXE

capitaliza

Por meio desta função é possível colocar a primeira letra de cada palavra de um texto em maiúsculo e as outras letras para minúsculo.

Caracteres.capitaliza(texto)

OU

texto.capitaliza

direita

Obtém uma quantidade específica de caracteres iniciados da direita para esquerda.

Caracteres.direita(texto, quantidade)

OU

texto.direita(quantidade)

dividir

Esta função divide um texto de acordo com a expressão regular informada.

Caracteres.dividir(boa-tarde~/|/) //

OU

valor.dividir(~/|/)

equivalenteVerifica se uma expressão está contida em um texto.

Caracteres.equivalente(texto, expressao)

OU

texto.equivalente(expressao)

esquerdaObtém uma quantidade específica de caracteres iniciados da esquerda para direita.

Caracteres.esquerda(texto, quantidade)

OU

texto.esquerda(quantidade)

maiusculo

Converte todos os caracteres de um texto em maiúsculo.

Caracteres.maiusculo(texto)

OU

texto.maiusculo

minusculo

Converte todos os caracteres de um texto em minúsculo.

Caracteres.minusculo(texto)

OU

texto.minusculo

posicaoObtém a posição onde um caracter se encontra em uma texto.

Caracteres.posicao(texto, expressao, posicaoInicio)

OU

texto.posicao(expressao, posicaoInicio)

posicaoFinalObtem a posição final de uma expressão regular em um texto.

Caracteres.posicaoFinal(texto, expressao regular, posicaoInicio)

OU

texto.posicaoFinal(expressao regular, posicaoInicio)

removeEspacosRemove o excesso de espaços de um texto.

Caracteres.removeEspacos(texto)

OU

texto.removeEspacos

removeEspacosDireita

Remove o excesso de espaços de um texto a esquerda.

Caracteres.removeEspacosDireita(texto)

OU

texto.removeEspacosDireita

removeEspacosEsquerdaRemove o excesso de espaços de um texto à direita.

Caracteres.removeEspacosEsquerda(texto)

OU

texto.removeEspacosEsquerda

sobrepor

Sobrepõe um texto em outro em uma determinada posição e com uma quantidade específica de caracteres.

Caracteres.sobrepor(texto, posicaoInicial, quantidadeSobrepor, textoSobrepor)

OU

texto.sobrepor(posicaoInicial, quantidadeSobrepor, textoSobrepor)

substituir

Substitui as ocorrências de uma expressão localizada em um texto por outra expressão.

Caracteres.substituir(texto, textoLocalizar, textoSubstituir)

OU

texto.substituir(textoLocalizar, textoSubstituir)

subTextoObtém um número específico de caracteres de uma posição específica de um texto.

Caracteres.subTexto(texto, inicio, tamanho)

OU

texto.subTexto(inicio, tamanho)

tamanhoObtém o tamanho de um texto.

Caracteres.tamanho(texto)

OU

texto.tamanho

vazio

Verifica se uma palavra está vazia.

Caracteres.vazio(valor)

OU

valor.vazio

repetirRepete um texto especificado de acordo com uma quantidade definida.

Caracteres.repetir(texto, repeticao)

OU

texto.repetir(repeticao)

Um exemplo prático de utilização do Repetir é para completar os caracteres de um campo de um leiaute bancário. Por exemplo, no leiaute tem o campo nome com 100 caracteres, porém, se o nome não tiver 100 caracteres, então, o campo deve ser preenchido com espaços em branco à direita.

Segue um exemplo de preenchimento de um campo do tipo String:

//Script convencional
arquivo = Arquivo.novo('arq.txt', 'txt', [encoding: 'iso-8859-1']);

dadosFuncionarios = Dados.dubai.v1.funcionarios

percorrer(dadosFuncionarios.busca()){
arquivo.escrever(item.nome)
arquivo.escrever(Caracteres.repetir(" ", 100 - item.nome.tamanho()))
arquivo.escrever(item.rg)
arquivo.escrever(Caracteres.repetir(" ", 10 - item.rg.tamanho()))
arquivo.escrever('ABCDE')
arquivo.novaLinha()
}

Resultado.arquivo(arquivo)


//Script otimizado
preencherComEspacos = { texto, tamanho ->
texto + Caracteres.repetir(" ", tamanho - texto.tamanho())
}

arquivo = Arquivo.novo('arq.txt', 'txt', [encoding: 'iso-8859-1']);

dadosFuncionarios = Dados.dubai.v1.funcionarios

percorrer(dadosFuncionarios.busca()){
arquivo.escrever(preencherComEspacos(item.nome,100))
arquivo.escrever(preencherComEspacos(item.rg, 10))
arquivo.escrever('ABCDE')
arquivo.novaLinha()
}

Resultado.arquivo(arquivo)

Segue um outro exemplo, utilizando o mesmo leiaute bancário, de preenchimento com zeros à esquerda para um determinado campo do tipo numérico:

//Função para preencher os espaços do número
formatarNumero = { numero, tamanho ->

numeroTxt = "$item.id"

//Observe que o preenchimento do campo está à esquerda, no caso, antes do Código.
Caracteres.repetir('X', tamanho - numeroTxt.tamanho()) + numeroTxt

//Observe que o preenchimento do campo está à direita, no caso, depois do Código.
// numeroTxt + Caracteres.repetir('X', tamanho - numeroTxt.tamanho())
}

arquivo = Arquivo.novo('arq.txt', 'txt', [encoding: 'iso-8859-1']);

dadosFuncionarios = Dados.dubai.v1.funcionarios

percorrer(dadosFuncionarios.busca()){
idString = "$item.id"
//Aqui os números são preenchidos com os caracteres desejados sem utilizar a função formatarNumero()
imprimir item.nome + Caracteres.repetir(" ", 100 - item.nome.tamanho()) +
Caracteres.repetir("X", 10 - idString.tamanho()) + item.id + '-ABCDE'


arquivo.escrever(item.nome)
arquivo.escrever(Caracteres.repetir(" ", 100 - item.nome.tamanho()))
//Aqui é utilizado o recurso da função de preenchimento dos espaços - formatarNumero(a,b)
arquivo.escrever(formatarNumero(item.id,10))
arquivo.escrever('-ABCDE')
arquivo.novaLinha()
}

Resultado.arquivo(arquivo)

Expressões regulares

As funções de Caracteres suporta o uso de expressões regulares para realizar diversas operações baseadas em um padrão em textos.

Caracteres.expressao(texto, expressao)
//ou
"texto".expressao(expressao)

As expressões são representadas na linguagem de scripts utilizando o seguinte padrão: ~/expressão/

expNumeros = ~/\d+/
expLetras = ~/(?i)[a-z]/

Caracteres.expressao("1235", ~/[a-z]/)
"1235".expressao(~/[a-z]/)

As operações disponíveis em uma expressão estão listadas nos tópicos a seguir:

equivalente()

Verifica se o texto é totalmente equivalente à expressão.

//verdadeiro pois todo o texto equivale a expressão regular informada
Caracteres.expressao("123", ~/\d+/).equivalente()

//falso pois apesar do texto conter números o valor não é totalmente equivalente à expressão.
"123AB".expressao(~/\d+/).equivalente()

totalGrupos()

Retorna o total de grupos da expressão regular.

expBoasVindas = "boa-tarde".expressao(~/boa-(tarde|noite)/)
imprimir expBoasVindas.totalGrupos() // 1

dividir()

Esta função divide um texto de acordo com a expressão regular informada retornando uma lista com os valores separados.

partes = "boa|tarde".expressao(~/\|/).dividir()
percorrer(partes){
imprimir item
}

//Saída:
//boa
//tarde

substituirPor(valor)

Realiza a substituição de todos os valores da expressão encontrados no texto pelo valor informado no parâmetro.

valor = "A1B2".expressao(~/[0-9]+/).substituirPor("*")
imprimir valor // A*B*

substituirPrimeiroPor(valor)

Realiza a substituição do primeiro valor da expressão encontrado no texto pelo valor informado no parâmetro.

valor = "A1B2".expressao(~/[0-9]+/).substituirPrimeiroPor("*")
imprimir valor // A*B2

encontrouPadrao()

Indica se o padrão da expressão foi encontrado no texto.

encontrouAlgo = "1235A".expressao(~/[0-9]+/).encontrouPadrao()
imprimir encontrouAlgo // true

concatenarValoresEncontrados()

Retorna todos os valores encontrados no texto pela expressão concatenados.

imprimir "B30th45".expressao(~/[0-9]+/).concatenarValoresEncontrados() // 3045

concatenarValoresEncontrados(separador)

Retorna todos os valores encontrados no texto pela expressão concatenados com o separador informado no parâmetro.

imprimir "B30th45".expressao(~/[0-9]+/).concatenarValoresEncontrados(",") // 30,45

Caractere de escape

imprimir "These "names" sets apply to this country: American"

//Resultado:
Há um erro de sintaxe. (1:18)

Isto ocorre, porque o compilador interpreta os caracteres de aspas duplas dentro da cadeia de caracteres como delimitadores. Para eliminar o problema emprega-se o caractere de escape \ (barra contrária, ou backslash) antes das aspas:

imprimir "These \"names\" sets apply to this country: American"

//Resultado:
These "names" sets apply to this country: American

Veja este caso:

imprimir "C:\Temp\PDF\Leitura"

//Resultado:
Há um erro de sintaxe. (1:13)

Isso ocorre porque o compilador interpreta as barras contrárias como caracteres de escape. Mas não é o que queremos. Queremos imprimir um caminho de pastas usando, literalmente, as barras contrárias:

//Adicione mais um caractere de escape em cada barra
imprimir "C:\\Temp\\PDF\\Leitura"

//Resultado:
C:\Temp\PDF\Leitura

Dentro das expressões regulares, é necessário inserir, no caractere de escape, um til entre as barras contrárias:

~\caractere de escape aqui~\

Veja abaixo um exemplo usando caracteres de escape. Repare que, dentro do último comando "expressao", há uma solicitação de substituir uma barra por uma string vazia.

//O código abaixo remove caracteres especiais
caracteres = "Caráctéres\$ Es\$,pêc-i_a*i/s. fôrám removídós\$: !@#¨&*^´()\n"

caracteres.expressao(~/[à|á|ã]/).substituirPor("a")
.expressao(~/[Á|Ã|À]/).substituirPor("A")
.expressao(~/[é|ê]/).substituirPor("e")
.expressao(~/[É|É]/).substituirPor("E")
.expressao(~/[É|É]/).substituirPor("")
.expressao(~/[í]/).substituirPor("i")
.expressao(~/[Í]/).substituirPor("I")
.expressao(~/[õ|ó|ô]/).substituirPor("o")
.expressao(~/[Õ|Ó|Ô]/).substituirPor("O")
.expressao(~/[ü|ú]/).substituirPor("u")
.expressao(~/[Ú|Ü]/).substituirPor("U")
.expressao(~/[ç]/).substituirPor("c")
.expressao(~/[Ç]/).substituirPor("C")
.expressao(~/ /).substituirPor(" ")
.expressao(~/[,|~\\n~\|~\/~\|-|_|*|.|!|@|#|$|%|¨|&|*|^|´|.|~|:|;|)|(|%|~\-|]/).substituirPor("")

//Resultado:
Caracteres Especiais foram removidos

Múltiplas ocorrências e grupos

Uma expressão pode encontrar diversas ocorrências de um padrão em um texto. Estes valores podem ser organizados por grupos ou simplesmente por valor localizado.

Percorrendo todas as ocorrências encontradas em um texto:

achaNumeros = "B30th45".expressao(~/[0-9]+/)
percorrer(achaNumeros){
imprimir item.valorEncontrado()
}
//Saída:
// 30
// 45

posicaoInicial()

Retorna a posição inicial do texto que coincida com a expressão localizada. Caso o padrão não seja encontrado retorna -1.

posicaoFinal()

Retorna a posição final do texto que coincida com a expressão localizada. Caso o padrão não seja encontrado retorna -1.

achaNumeros = "B30th45".expressao(~/[0-9]+/)
percorrer(achaNumeros){
valor = item.valorEncontrado()
inicio = item.posicaoInicial()
fim = item.posicaoFinal()
imprimir "O valor $valor inicia na posição $inicio e termina na posição $fim"
}

// Saída:
//O valor 30 inicia na posição 1 e termina na posição 3
//O valor 45 inicia na posição 5 e termina na posição 7

posicaoFinal()

Retorna a posição final do texto que coincida totalmente com a expressão utilizada. Caso não encontrado retorna -1.

imprimir "B30th".expressao(~/\d+/).posicaoFinal() //3

valoresGrupos()

Retorna uma lista com todos os valores encontrados pelos grupos especificados na expressão.

exp = "boa-tarde".expressao(~/boa-(tarde|noite)/)
percorrer(exp){
imprimir item.valoresGrupos() // [tarde]
}

valorGrupo(indice)

Retorna ao valor do grupo encontrado conforme índice e expressão.

exp = "bom-dia".expressao(~/(boa|bom)-(dia|tarde|noite)/)
percorrer(exp){
imprimir item.valorGrupo(0) //bom
imprimir item.valorGrupo(1) //dia
}

exp2 = "boa-tarde".expressao(~/(boa|bom)-(dia|tarde|noite)/)
percorrer(exp2){
imprimir item.valorGrupo(0) //boa
imprimir item.valorGrupo(1) //tarde
}

valorEncontrado()

Retorna o conteúdo do texto encontrado de acordo com a expressão/grupo utilizado.

exp = "Muito boa-tarde respeitável público.. Ops, acho que seria boa-noite!".expressao(~/(boa|bom)-(dia|tarde|noite)/)
percorrer(exp){
imprimir item.valorEncontrado()
}

//Saída:
// boa-tarde
// boa-noite

concatenarValoresGrupos()

Retorna os valores dos grupos da expressão concatenados.

exp = "boa-Tarde".expressao(~/(boa|bom)-(dia|(t|T)arde|noite)/)
percorrer(exp){
imprimir item.concatenarValoresGrupos() // boaTardeT
}

concatenarValoresGrupos(separador)

Retorna os valores dos grupos da expressão concatenados com o separador informado no parâmetro.

exp = "boa-Tarde".expressao(~/(boa|bom)-(dia|(t|T)arde|noite)/)
percorrer(exp){
imprimir item.concatenarValoresGrupos("-") // boa-Tarde-T
}

Datas

FUNÇÃODESCRIÇÃO / OBJETIVOSINTAXE
adicionaDiasAdiciona uma quantidade especificada de dias à uma data.

Datas.adicionaDias(data, quantidadeDias)

OU

data.adicionaDias(quantidadeDias)

adicionaHorasAdiciona uma quantidade especificada de horas em uma data/horaDatas.adicionaHoras(data, quantidadeHoras)
adicionaMesesAdiciona uma quantidade especificada de meses em uma data. Caso o dia da data especificada não seja um dia válido para o mês resultante, Ex: 31/10/2011, adiciona 1 mês, valor inválido para nova data 31/11/2011, a diferença de dias será acrescentada na nova data, Ex:31/10/2011, adiciona 1 mês fica 01/12/2011.

Datas.adicionaMeses(data, quantidadeMeses)

OU

data.adicionaMeses(quantidadeMeses)

adicionaMinutosAdiciona uma quantidade especificada de minutos em uma data/hora.

Datas.adicionaMinutos(data, quantidadeMinutos)

OU

data.adicionaMinutos (quantidadeMinutos)

adicionaSegundosAdiciona uma quantidade especificada de segundos em uma data/hora.

Datas.adicionaSegundos(data, quantidadeMinutos)

OU

data.adicionaSegundos(quantidadeMinutos)

anoObtém o ano em que se encontra uma determinada data

Datas.ano(data)

OU

data.ano

dataGera uma data sem hora de acordo com o dia, mês e ano passados por parâmetro.

Datas.data(ano, mês, dia)

OU

ano.data(mês, dia)

dataHoraGera uma data com a hora de acordo com o dia, mês, ano, hora e minuto passados por parâmetro

Datas.dataHora (ano, mês, dia, hora, minuto)

OU

ano.dataHora (mês, dia, hora minuto)

diaObtém o dia em que se encontra uma determinada data.

Datas.dia(data)

OU

data.dia

diaSemanaObtem o dia da semana em que se encontra uma determinada data, considerando-se o domingo comoprimeiro dia e o sábado como o sétimo dia.

Datas.diaSemana(data)

OU

data.diaSemana

diferencaAnosCalcula a diferença em anos entre duas datas.

Datas.diferencaAnos(menorData, maiorData)

OU

menorData.diferencaAnos (maiorData)

diferencaDiasCalcula a diferença em dias entre duas datas.

Datas.diferencaDias(menorData, maiorData)

OU

menorData.diferencaDias(maiorData)

diferencaHorasCalcula a diferença em horas entre duas datas.

Datas.diferencaHoras(menorData, maiorData)

OU

menorData.diferencaHoras(maiorData)

diferencaMesesCalcula a diferença em meses entre duas datas

Datas.diferencaMeses(menorData, maiorData)

OU

menorData.diferencaMeses(maiorData)

diferencaMinutosCalcula a diferença em minutos entre duas datas/hora.

Datas.diferencaMinutos(menorData, maiorData)

OU

menorData.diferencaMinutos(maiorData)

diferencaSegundosCalcula a diferença em segundos entre duas datas/hora

Datas.diferencaSegundos (menorData, maiordata)

OU

menorData.diferencaSegundos(maiorData)

ehDataVerifica se um texto é uma hora válida.

Datas.ehData(texto)

OU

texto.ehdata

extensoObtém a data por extenso.

Datas.extenso(data)

OU

data.extenso

hojeObtém a data e hora do sistema operacional

Datas.hoje()

OU

Datas.hoje(data)

horaObtém a hora em que se encontra uma determinada data/hora.

Datas.hora(data)

OU

Data.hora

mêsObtém o mês em que se encontra uma determinada data.

Datas.mes(data)

OU

data.mes

minutoObtém os minutos referentes a uma determinada data/hora.

Datas.minuto(data)

OU

data.minuto

nomeDiaSemanaObtém o nome do dia da semana.

Datas.nomeDiaSemana(data)

OU

data.nomeDiaSemana

nomeMesObtém o nome do mês de uma data,

Datas.nomeMes(data)

OU

data.nomeMes

periodoCria um período com data inicial e final.Datas.periodo(dataInicial, dataFinal)
removeDiasRemove uma quantidade especificada de dias de uma data.

Datas.removeDias(data, quantidade

OU

data.removeDias(quantidadeDias)

removeMesesRemove uma quantidade especificada de meses de uma data. Caso o dia da data especificada não seja um dia válido para o mês resultante, Ex: 31/12/2011, remove 1 mês, valor inválido para nova data 31/11/2011, a diferença de dias será acrescentada da nova data, Ex: 31/12/2011,remove 1 mês fica 01/12/2011.

Datas.removeMeses(data, quantidadeMeses)

OU

data.removeMeses(quantidadeMeses)

SegundoObtém os segundos referentes a uma determinada data/hora.

Datas.segundo(data)

OU

data.segundo

formatarObtém o valor de uma data formatado de acordo com um padrão especificado.

Datas.formatar(data, formato)

EXEMPLO:

//data definida como dia 26/05/2017

imprimir data.formatar('yyyy-MM-dd') // 2017-05-26

imprimir data.formatar('MM/yyyy') // 05/2017

imprimir data.formatar('EEEE') // Sexta-feira

Padrões para formatação:

LetraDescriçãoExemplos
yAno2009; 09
MMês do anoJulho; Jul; 07
wSemana no ano27
WSemana no mês2
DDia no ano189
dDia no mês10
FDia da semana no mês2
ENome do dia da semanaSegunda-feira, Seg
uNúmero do dia da semana (1=Segunda.7=Domingo)1
aIndicador de AM/PMAM
HHora no dia (0-23)0
kHora no dia (1-24)24
KHora no dia (0-11)0
hHora no dia (1-12)12
mMinuto na hora55
sSegundos no minuto30
SMilissegundo978

Funções para manipulação de números

A API padrão provê uma série de funções para a manipulação de números. Sendo assim o quadro a seguir exibe todas as funções disponíveis de maneira prática. Além da função propriamente dita, informa a sua descrição ou objetivo dela, bem como a sintaxe de cada função.

FUNÇÃODESCRIÇÃO / OBJETIVOSINTAXE
absolutoCalcula o valor absoluto de um número.Numeros.absoluto(valor)
arredondaArredonda um valorNumeros.arredonda(valor, casasDecimais)
cosenoCalcula o cosseno de um ângulo.Numeros.coseno(valor)
decimalConverte o valor de um texto em um número decimal de alta precisão.Numeros.decimal(texto)
ehNumeroVerifica se um texto é um número válido.Numeros.ehNumero(texto)
exponencialObtém o exponencial de um número específico.Numeros.exponencial(numero)
fatorialObtém o fatorial de um número.Numeros.fatorial(numero)
inteiroConverte o valor de um texto em um número inteiro. Caso o texto represente um número decimal, este será truncado para um inteiro, ou seja, a parte decimal será descartada.Numeros.inteiro(texto)
logaritmoInforma o logaritmo natural de um número.Numeros.logaritmo(valor)
logaritmo10Informa logaritmo de base 10 de um número.Numeros.logaritmo10(valor)
maximoObtém o maior valor entre dois números.Numeros.maximo(valor1, valor2)
minimoObtém o menor valor entre dois números.Numeros.minimo(valor1, valor2)
numero

Converte o valor de um texto em um número, retornando o tipo Long para números inteiros e Double para números decimais.

IMPORTANTE! Esta função NÃO deve ser utilizada para trabalhar com valores monetários. O tipo Double não é adequado para esse fim e vai resultar em imprecisões que ao longo de um cálculo podem alterar de forma significativa o resultado. A função adequada para este fim é a Numeros.decimal.

Numeros.numero(texto)
piMultiplica o valor de PI pelo número especificado.Numeros.pi(valorMultiplicar)
pisoObtém o maior número que é menor ou igual ao número especificado, sendo este número inteiro.Numeros.piso(valor)
raizCalcula a raiz quadrada de um número.Numeros.raiz(valor)
randomicoObtém um número aleatório entre 1 a um valor limite especificado.Numeros.randomico(numeroDelimitador)
restoRetorna o resto da divisão realizada entre o dividendo e o divisor, que são passados por parâmetro.Numeros.resto(valorDividendo, valorDivisor)
senoCalcula o seno de um ângulo.Numeros.seno(valor)
seZeroTesta os valores passados como parâmetro e retorna o primeiro diferente de zero.Numeros.seZero(valor1, valor2, valorN)
tangenteCalcula a tangente de um ângulo.Numeros.tangente(valor)
tetoObtém o menor número que é maior ou igual ao número especificado, sendo este número inteiro.Numeros.teto(valor)
truncaTrunca um valor de acordo com o número de casas decimais especificadas.Numeros.trunca(valor, casasDecimais)

JSON

FUNÇÃODESCRIÇÃO / OBJETIVOSINTAXE
lerConverte um json em um mapa

pessoa = JSON.ler('{"nome":"João da Silva"}')

imprimir pessoa.nome // imprimie João da Silva

escrever

Converte um objeto em json

json = JSON.escrever([nome: "João da Silva"])

imprimir json // imprimie {"nome":"João da Silva"}