bfc-script

Comandos

imprimir 'John Doe'

percorrer(ate:5){
    imprimir indice
}

percorrer(de:3, ate:5){
    imprimir indice
}

percorrer(de:3, ate:5){ idPrincipal ->
    imprimir idPrincipal
    percorrer(de:6, ate:8){ idSecundario ->
        imprimir 'ID princial: ' + idPrincipal
        imprimir 'ID secundário: ' + idSecundario
    }
}

numeros = [1,2,3]
percorrer(de:1, ate:3, itens: numeros){ 
    imprimir item
}
// Irá imprimir os números 1, 2 e 3

letras = ['A','B','C']
percorrer(de:2, ate:3, itens: letras){ 
    imprimir item
}
// Irá imprimir as letras B e C, ou seja, do índice 2 até o índice 3

numeros = [1,2,3,4]
percorrer(numeros){
  se(item == 3){
    parar()
  } 
  imprimir item
}

//As instruções fora do comando percorrer serão executadas normalmente, somente o comando percorrer 
//será interrompido e não todo o script
imprimir 'Ok'

numeros = [1,2,3,4]
percorrer(numeros){
  se(item == 3){
    continuar()
  } 
  imprimir item
}

numeros = [1,2,3,4]
percorrer(itens: numeros, nome: 'p1'){ 
  imprimir 'p1: ' + item 
  percorrer(de: 1, ate: 5){
    se (indice == 3){
      parar 'p1'
    }
    imprimir 'p2: ' + indice
  }
}

p1: 1 // primeiro item da lista de números do percorrer 'p1'
p2: 1 // primeiro índice do segundo percorrer
p2: 2 // ...
p2: 3 // ...
p2: 4 // No índice 4 o comando parar 'p1' foi executado interrompendo a execução de todos os comandos percorrer até o 'p1'

numeros = [1,2,3]
percorrer(itens: numeros, nome: 'p1'){ 
  imprimir 'p1: ' + item
  percorrer(de: 1, ate: 5, nome: 'p2'){
    se (indice == 2){
      continuar 'p1'
    }
    imprimir 'p2: ' + indice
  }
}

p1: 1 // primeiro item da lista de números do percorrer 'p1'
p2: 1 // primeiro índice do segundo percorrer 
      // Ao passar pelo segundo ídice o comando continuar 'p1' foi execuado parando a execução do percorrer atual e avançando o item do 
      // percorrer 'p1' para a próxima iteração, neste caso o número 2
p1: 2 
p2: 1
p1: 3
p2: 1

valor = 10 * 2 * 3
retornar valor

retornar valor:10 * 2 * 3, nome:'David Crosby'

se(10 == 10){
   imprimir 'verdadeiro'
}

se(9 <= 20){
    imprimir 'verdadeiro'
}senao{
    imprimir 'falso'
}

tentar {
  resultado = Http.servico('https://endereco-nao-existe').GET()
  imprimir resultado.codigo()
} tratar {
   // Ao mandar imprimir o objeto excecao, será impresso o código, mensagem e linha (se existir)
   imprimir 'Estou tratando uma exceção: ' + excecao
}

tentar {
  resultado = Http.servico('https://endereco-nao-existe').GET()
  imprimir resultado.codigo()
} tratar {
   // Ao mandar imprimir o objeto excecao, será impresso o código, mensagem e linha (se existir)
   imprimir 'Estou tratando uma exceção: ' + excecao
} finalizar {
    imprimir 'O conteúdo deste bloco sempre será executado'
}

se(codigo != 10){
   suspender "O código $codigo é inválido"
}

imprimir Datas.hoje()
esperar 2000 //O script irá pausar a execução neste ponto durante 2000 millisegundos
imprimir Datas.hoje()

imprimir Datas.hoje()
esperar 1.segundo //O script irá pausar a execução neste ponto durante 1 segundo
imprimir Datas.hoje()

// exportando uma constante
exportar PI_APROXIMADO: 3.1415

// exportando múltiplos símbolos
exportar(
	nomeExterno: referencia,
	outroNome: outraReferencia
)

log = importar("log")
math = importar("calculadora")
counter = importar("contador")

log.info("Iniciando execução")
acum = 0

percorrer(ate: 20) {
  counter.incrementar()
  acum = math.somar(acum, indice)
  log.info("Executando operação #$indice")
}

Listas

Também conhecida como Arrays, podemos trabalhar com listas de maneira bem simplificada.

//Instancia uma lista com valores
valores = [0, 1, 2, 3, 4]

//Instancia uma lista vazia
nomes = []

//Adiciona um item na lista
nomes << 'Chuck Norris'

//Itera uma lista
percorrer(valores){
    imprimir item
}

O comando percorrer possui uma variável implícita para obter o valor da iteração chamada item.

A variável item e indice podem ser atribuídas à outras variáveis com nomes personalizados utilizando a seguinte sintaxe do comando percorrer:

percorrer(valores){ valor ->
    imprimir valor
}

percorrer(valores){ valor, posicao ->
    imprimir valor // Equivale a item
    imprimir posicao // Equivale a indice
}

percorrer(valores){ item, posicao ->
    imprimir item
    percorrer(outros){
        imprimir item //Equivale ao item do percorrer principal pois utilizou o mesmo nome da variável implícita
    }
}

Obtendo e atribuindo valores em posições específicas da lista. A primeira posição da lista tem o índice 0 (zero), a segunda posição tem o índice 1, e assim por diante. Os dados são acessados assim: lista[indice]

//Instancia uma lista com valores
nomes = ['Harrison Reid', 'Thomas Sharpe', 'Louie Hill']

//nomes[0] contém o valor 'Harrison Reid'
//nomes[1] contém o valor 'Thomas Sharpe'
//nomes[2] contém o valor 'Louie Hill'

//Obtendo o nome da segunda posição da lista:
nomeDaSegundaPosicao = nomes[1]

Mapas

É possível criar mapas simplificados e acessar seu valores de forma explicita.

pessoa = [nome:'João da Silva', idade:25, profissao: 'Contador']
 
imprimir pessoa.nome
imprimir pessoa.idade
imprimir pessoa.profissao

Observe o exemplo abaixo, usando uma lista de mapas:

//Declaração da lista. Será composta por um mapa que contém o nome, a idade e a profissão.
dadosPessoais = []

//Adicionando dados à lista
dadosPessoais << [nome:'Luca Ingram', idade:25, profissao: 'Process pipeline drafter']
dadosPessoais << [nome:'Jack Young', idade:30, profissao: 'Industrial economist']
dadosPessoais << [nome:'Jake Sullivan', idade:31, profissao: 'Gastroenterology nurse']

//Imprimindo os dados...
percorrer(dadosPessoais) {
  imprimir 'Posição: ' + indice + ' -> Dados:' + item 
}

//Temos o resultado:
Posição: 0 -> Dados:[nome:Luca Ingram, idade:25, profissao:Process pipeline drafter]
Posição: 1 -> Dados:[nome:Jack Young, idade:30, profissao:Industrial economist]
Posição: 2 -> Dados:[nome:Jake Sullivan, idade:31, profissao:Gastroenterology nurse]

//Agora, vamos alterar última posição da lista com novos dados. 
//Jake Sullivan trocou de profissão e precisamos atualizar seu dado profissional. Fazemos isso substituindo um mapa por outro:
dadosPessoais[2] = [nome:'Jake Sullivan', idade:31, profissao: 'Administrative leader']

//Voltamos a imprimir. Resultado:
Posição: 0 -> Dados:[nome:Luca Ingram, idade:25, profissao:Process pipeline drafter]
Posição: 1 -> Dados:[nome:Jack Young, idade:30, profissao:Industrial economist]
Posição: 2 -> Dados:[nome:Jake Sullivan, idade:31, profissao:Administrative leader]

//Outro exemplo: Preciso saber a idade do segundo profissional da lista, Jack Young:
imprimir dadosPessoais[1].idade
//Resultado: 30    

Intervalos

Intervalos permitem que você crie uma lista de valores sequenciais podendo serem utilizados como listas. A notação .. define um intervalo, do primeiro item até o último. Intervalos definidos com a notação ..< incluem o primeiro valor, mas não o último valor.

//Cria um intervalo
dias = 1..3

//Percorre um intervalo    
percorrer(dias){
    imprimir item
}

//Percorre um intervalo        
percorrer(4..7){
    imprimir item    
}

//Percorre um intervalo de forma decrescente
percorrer(8..7){
    imprimir item    
}

//Percorre um intervalo decrescente desconsiderando o último valor
percorrer(6..<4){
    imprimir item    
}

O comando percorrer possui uma variável implícita para obter o valor da iteração chamada item.

Datas

A linguagem permite trabalhar com datas de forma bem simplificada. Várias funções estão embutidas nos elementos de data facilitando muito o uso, além de tornar as implementações bem intuitivas. O exemplo abaixo demonstra o uso de algumas funções para datas da API padrão e como utilizar estas funções de forma simplificada, além de demonstrar formas nativas para somar datas/horas/etc.

//Funções para obter-se uma data/dataHora
hoje = Datas.hoje()
primeiroDiaDoAno = Datas.data(hoje.ano,1 ,1 )
ultimoDiaDoAno = Datas.dataHora(hoje.ano, 12, 31, 23, 59)

imprimir Datas.adicionaSegundos(hoje, 10)
imprimir hoje + 10.segundos

imprimir Datas.adicionaMinutos(hoje, 10)
imprimir hoje + 10.minutos

imprimir Datas.adicionaHoras(hoje, 10)
imprimir hoje + 10.horas

imprimir Datas.adicionaDias(hoje, 10)
imprimir hoje + 10.dias

imprimir Datas.adicionaMeses(hoje, 10)
imprimir hoje + 10.meses

imprimir hoje + 1.segundo
imprimir hoje + 1.minuto
imprimir hoje + 1.hora
imprimir hoje + 1.dia
imprimir hoje + 1.mes

imprimir hoje + 10.anos + 9.meses + 8.semanas + 7.dias + 6.horas + 5.minutos + 4.segundos + 3.milesegundos

imprimir Datas.ano(hoje)
imprimir hoje.ano
imprimir Datas.mes(hoje)
imprimir hoje.mes
imprimir Datas.dia(hoje)
imprimir hoje.dia
imprimir Datas.hora(hoje)
imprimir hoje.hora
imprimir Datas.minuto(hoje)
imprimir hoje.minuto
imprimir Datas.segundo(hoje)
imprimir hoje.segundo

imprimir Datas.diaSemana(hoje)
imprimir hoje.diaSemana

imprimir Datas.removeDias(hoje, 10)
imprimir hoje - 10.dias

imprimir Datas.removeMeses(hoje, 10)
imprimir hoje - 10.meses

imprimir Datas.extenso(hoje)
imprimir hoje.extenso

imprimir Datas.nomeDiaSemana(hoje)
imprimir hoje.nomeDiaSemana

imprimir Datas.nomeMes(hoje)
imprimir hoje.nomeMes

imprimir Datas.ehData('01/01/2010')

imprimir Datas.diferencaAnos(primeiroDiaDoAno, ultimoDiaDoAno)
imprimir Datas.diferencaDias(primeiroDiaDoAno, ultimoDiaDoAno)
imprimir Datas.diferencaHoras(primeiroDiaDoAno, ultimoDiaDoAno)
imprimir Datas.diferencaMeses(primeiroDiaDoAno, ultimoDiaDoAno)
imprimir Datas.diferencaMinutos(primeiroDiaDoAno, ultimoDiaDoAno)
imprimir Datas.diferencaSegundos(primeiroDiaDoAno, ultimoDiaDoAno)

amanha = hoje + 1.dia

//Podemos criar intervalos com datas
percorrer(hoje..amanha){
    imprimir item.extenso
}

percorrer(hoje+1.semana..<amanha+2.semanas){
    imprimir item.extenso
}

//Podemos obter uma data apartir de uma expressão como esta
semanaQueVem = 7.dias.apartirDe.hoje

imprimir semanaQueVem + 5.dias

É importante notar que os valores numéricos informados nas funções de data para representar ano, mês, dias, horas e segundos, diferentemente da formatação Brasileira, não devem conter zeros à esquerda:

//Correto
Datas.data(2017, 8, 5)

//Incorreto (Erro de compilação)
Datas.data(2017, 08, 05)

Valores nulos

Em programação de computadores, null é um valor especial para um ponteiro (ou qualquer outro tipo de referência) que indica que este ponteiro, intencionalmente, não se refere a um objeto (ponteiro nulo) - Wikipedia.

Este recurso se mostra útil para identificar quando um valor não esta disponível, assumindo um valor próprio para este comportamento, o nulo ou vazio.

A palavra reservada nulo representa o valor para este comportamento, de modo que no exemplo abaixo estamos dizendo que a variável valorCusto é igual a nulo ou em outras palavras, que seu valor é vazio.

    valorCusto = nulo

Um script pode receber variáveis com valores nulo, onde em certas ocasiões é necessário checar se o valor da variável é nulo ou não. Podemos realizar as checagens de duas formas:

    valorCusto = nulo

    // Forma 1
    se (valorCusto != nulo){
        imprimir ("A variável valorCusto não está nula.")
    }

    // Forma 2
    se (valorCusto){
        imprimir ("A variável valorCusto não está nula.")
    }

    se (!valorCusto){
        imprimir ("A variável valorCusto está nula.")
    }

    se (valorCusto && funcionario.agenciaBancaria){
        imprimir ("A variável valorCusto a a agência bancária do funcionário não estão nulas.")
    }

O acesso à referências nulas gera erros durante a execução de um script. No exemplo abaixo, suponhamos que a agência bancária do funcionário esteja nula:

    nomeFuncionario = funcionario.agenciaBancaria.nome

Ao tentar obter o nome de uma agência bancária nula, recebemos um erro de execução: A propriedade nome não é acessível em um elemento nulo. Para evitar este comportamento, podemos utilizar o operador de navegação segura (?):

    nomeFuncionario = funcionario.agenciaBancaria?.nome

O operador deve ser utilizado em diversos níveis de uma referência, caso seja apropriado:

    nomeFuncionario = funcionario.agenciaBancaria?.municipio?.nome

    // valor impresso 'null'
    imprimir(nomeFuncionario)

No exemplo acima, caso não utilizassemos o operador (?) no município (municipio?.nome), receberiamos um erro durante a execução, devido ao fato de que a agenciaBancária esta nula. Como resultado final o valor da variável nomeFuncionario é nula.

Em algumas ocasiões, gostariamos de considerar um valor padrão onde o resultado seria nulo. Para este propósito utilizamos a expressão ternária (?:), como podemos observar abaixo:

    nomeFuncionario = funcionario.agenciaBancaria?.municipio?.nome

    imprimir(nomeFuncionario?:'Sem nome')

No exemplo acima, quando o valor da variável nomeFuncionario for nulo, o valor retornado será Sem nome.

Poderiamos usar esta expressão diretamente, conforme o exemplo abaixo:

    nomeFuncionario = funcionario.agenciaBancaria?.municipio?.nome?:'Sem nome'

    imprimir(nomeFuncionario)

Caracteres

Caracteres.capitaliza(texto)

texto.capitaliza

Caracteres.direita(texto, quantidade)

texto.direita(quantidade)

Caracteres.equivalente(texto, expressao)

texto.equivalente(expressao)

Caracteres.esquerda(texto, quantidade)

texto.esquerda(quantidade)

Caracteres.maiusculo(texto)

texto.maiusculo

Caracteres.minusculo(texto)

texto.minusculo

Caracteres.posicao(texto, expressao, posicaoInicio)

texto.posicao(expressao, posicaoInicio)

Caracteres.posicao(texto, expressao regular, posicaoInicio)

texto.posicao(expressao regular, posicaoInicio)

Caracteres.posicaoFinal(texto, expressao regular, posicaoInicio)

texto.posicaoFinal(expressao regular, posicaoInicio)

Caracteres.removeEspacos(texto)

texto.removeEspacos

Caracteres.removeEspacosDireita(texto)

texto.removeEspacosDireita

Caracteres.removeEspacosEsquerda(texto)

texto.removeEspacosEsquerda

Caracteres.repetir(texto, repeticao)

texto.repetir(repeticao)

//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)

//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)

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

texto.sobrepor(posicaoInicial, quantidadeSobrepor, textoSobrepor)

Caracteres.substituir(texto, textoLocalizar, textoSubstituir)

texto.substituir(textoLocalizar, textoSubstituir)

Caracteres.subTexto(texto, inicio, tamanho)

texto.subTexto(inicio, tamanho)

Caracteres.tamanho(texto)

texto.tamanho

Caracteres.vazio(valor)

valor.vazio

Caracteres.dividir("boa|tarde", ~/\|/) //[boa, tarde]

valor.dividir(~/\|/)

Expressões regulares

A API 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/

Exemplo:

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

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

As operações disponíveis em um expressão sã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()

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

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

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

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

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

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

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

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

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

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

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

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

imprimir "C:\Temp\PDF\Leitura"

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

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

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

~\caractere de escape aqui~\

//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

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

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

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

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
}

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

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

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

Datas

Datas.adicionaDias(data, quantidadeDias)

data.adicionaDias(quantidadeDias)

Datas.adicionaHoras(data, quantidadeHoras)

Datas.adicionaMeses(data, quantidadeMeses)

data.adicionaMeses(quantidadeMeses)

Datas.adicionaMinutos(data, quantidadeMinutos)

data.adicionaMinutos(quantidadeMinutos)

Datas.adicionaSegundos(data, quantidadeMinutos)

data.adicionaSegundos(quantidadeMinutos)

Datas.ano(data)

data.ano

Datas.data(ano, mes, dia)

ano.data(mes, dia)

Datas.dataHora(ano, mes, dia, hora, minuto)

ano.dataHora(mes, dia, hora, minuto)

Datas.dia(data)

data.dia

Datas.diaSemana(data)

data.diaSemana

Datas.diferencaAnos(menorData, maiorData)

menorData.diferencaAnos(maiorData)

Datas.diferencaDias(menorData, maiorData)

menorData.diferencaDias(maiorData)

Datas.diferencaHoras(menorData, maiorData)

menorData.diferencaHoras(maiorData)

Datas.diferencaMeses(menorData, maiorData)

menorData.diferencaMeses(maiorData)

Datas.diferencaMinutos(menorData, maiorData)

menorData.diferencaMinutos(maiorData)

Datas.diferencaSegundos(menorData, maiorData)

menorData.diferencaSegundos(maiorData)

Datas.ehData(texto)

texto.ehData

Datas.extenso(data)

data.extenso

Datas.hoje()

Datas.hoje(data)

Datas.hora(data)

data.hora

Datas.mes(data)

data.mes

Datas.minuto(data)

data.minuto

Datas.nomeDiaSemana(data)

data.nomeDiaSemana

Datas.nomeMes(data)

data.nomeMes

Datas.periodo(dataInicial, dataFinal)

Datas.removeDias(data, quantidadeDias)

data.removeDias(quantidadeDias)

Datas.removeMeses(data, quantidadeMeses)

data.removeMeses(quantidadeMeses)

Datas.segundo(data)

data.segundo

Datas.formatar(data, formato)

data.formatar

//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

Numeros

Numeros.absoluto(valor)

Numeros.arredonda(valor, casasDecimais)

Numeros.coseno(valor)

Numeros.decimal(texto)

Numeros.ehNumero(texto)

Numeros.exponencial(numero)

Numeros.fatorial(numero)

Numeros.inteiro(texto)

Numeros.logaritmo(valor)

Numeros.logaritmo10(valor)

Numeros.maximo(valor1, valor2)

Numeros.minimo(valor1, valor2)

Numeros.numero(texto)

Numeros.pi(valorMultiplicar)

Numeros.piso(valor)

Numeros.raiz(valor)

Numeros.randomico(numeroDelimitador)

Numeros.resto(valorDividendo, valorDivisor)

Numeros.seno(valor)

Numeros.seZero(valor1, valor2, valorN)

Numeros.tangente(valor)

Numeros.teto(valor)

Numeros.trunca(valor, casasDecimais)

JSON

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

json = JSON.escrever([nome: "João da Silva"])
imprimir json // imprimie {"nome":"João da Silva"}

Leitura de arquivos

A leitura de arquivos está disponível através da função Arquivo.ler(). Esta função irá retornar uma implementação específica com operações distintas para realizar a leitura do arquivo conforme tipo. Esta função contém algumas variações para permitir diferentes origens e a passagem de parâmetros para as implementações:

• Arquivo.ler(arquivo ou conteúdo): Realiza a leitura do arquivo utilizando a implementação padrão para arquivos texto.
• Arquivo.ler(arquivo ou conteúdo, tipo do arquivo): Realiza a leitura do arquivo utilizando a implementação própria para o tipo de arquivo informado.
• Arquivo.ler(arquivo ou conteúdo, tipo do arquivo, parametros): Realiza a leitura de arquivo utilizando a implementação própria para o tipo do arquivo informado permitindo a passagem de parâmetros específicos da implementação.

Exemplo de utilização:

    arquivoTxt = Arquivo.ler(origem, 'txt');
    arquivoCsv = Arquivo.ler('Bob|Esponja', 'csv', [delimitador:'|']);

Escrita de arquivos

A criação de um novo arquivo está disponível através da função novo. Esta função irá retornar uma implementação específica com operações distintas para realizar a escrita do arquivo conforme tipo. A função novo contem algumas variações:

• Arquivo.novo(nome do arquivo): Cria um novo arquivo utilizando a implementação padrão para arquivos texto.
• Arquivo.novo(nome do arquivo, tipo do arquivo): Cria um novo arquivo arquivo utilizando a implementação própria para o tipo de arquivo informado.
• Arquivo.novo(nome do arquivo, tipo do arquivo, parametros): Cria um novo arquivo utilizando a implementação própria para o tipo de arquivo informado permitindo a passagem de parâmetros específicos da implementação.

Exemplo de utilização:

    arquivoTxt = Arquivo.novo('Jones.txt')
    arquivoCsv = Arquivo.novo('Spencer.csv', 'csv', [entreAspas: 'N'])

Download dos arquivos

Por padrão a API de arquivos não disponibiliza para download os arquivos criados pelas implementações. Para que os mesmos sejam incluídos no arquivo zip de resultado da execução de um script através da Ferramenta de Scripts é necessário adicionar estes arquivos ao resultado.

txt = Arquivo.novo('teste.txt', 'txt')

//Adiciona o arquivo txt no zip do resultado
Resultado.arquivo(txt)

//Personaliza o nome do arquivo no zip do resultado
Resultado.arquivo(txt, 'meu_arquivo.txt')

//Personaliza o nome do arquivo e do diretório no zip do resultado
Resultado.arquivo(txt, 'meu_arquivo.txt', 'Arquivos texto')

//Personaliza o nome do arquivo
Resultado.nome('meu_resultado.zip')

Leitura

arquivo = Arquivo.ler(arquivo, 'txt')

Lendo um arquivo com um Encoding específico (Por padrão utiliza UTF-8):

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

texto = arquivo.lerLinha()

percorrer(enquanto: { arquivo.contemProximaLinha() }) {
    imprimir arquivo.lerLinha()
}

Escrita

arquivo = Arquivo.novo('FendaDoBiquine.txt')

Criando um novo arquivo com um Encoding específico (Por padrão utiliza UTF-8):

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

arquivo.escrever('Jonathan Peters')

arquivo.escrever('Jonathan Peters')
arquivo.novaLinha()
arquivo.escrever('Oscar Randall')

Leitura

arquivo = Arquivo.ler(arquivo, 'csv')

Lendo um arquivo com um Encoding específico (Por padrão utiliza UTF-8):

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

Parâmetros de leitura:

• delimitador: Caracter que delimita os valores do arquivo CSV. Por padrão utiliza uma virgula.
• encoding: Determina o encoding a ser usado na leitura do arquivo. Por padrão utiliza UTF-8.

texto = arquivo.lerLinha()

percorrer(enquanto: { arquivo.contemProximaLinha() }) {
    imprimir arquivo.lerLinha()
}

arquivo = Arquivo.ler('Nome,Endereco\nBob,Fenda do biquine', 'csv')
arquivo.pularLinhas(1)
imprimir arquivo.lerLinha() //Bob,Fenda do biquine

arquivo = Arquivo.ler('Plancton,Mar\nBob,Fenda do Biquine', 'csv')
arquivo.lerProximoValor() //Plancton
arquivo.lerProximoValor() //Mar
arquivo.lerProximoValor() //Bob

se(arquivo.contemProximoValor()){
    arquivo.lerProximoValor()
}

Escrita

arquivo = Arquivo.novo('FendaDoBiquine.csv', 'csv')

Criando um novo arquivo com um Encoding específico (Por padrão utiliza UTF-8):

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

Parâmetros de escrita:

• delimitador: Caracter para delimitar os valores do arquivo CSV. Por padrão utiliza uma virgula.
• entreAspas: Indica se os valores escritos no arquivo deverão estar entre aspas duplas. Utilizar S para Sim e N para Não.
• encoding: Determina o encoding a ser usado na criação do arquivo. Por padrão utiliza UTF-8.

arquivo.escrever('Jonathan Peters')

arquivo.escrever('Jonathan Peters')
arquivo.novaLinha()
arquivo.escrever('Oscar Randall')

Leitura

arquivo = Arquivo.ler(arquivo, 'xml')

se(arquivo.contemValor()){
    imprimir arquivo.valor()
}

percorrer(arquivo.atributos()){
    imprimir item.nome()
}

percorrer(enquanto: { xml.contemProximo() }) { 
  
  xml.proximo()
  
  imprimir '#Dados do elemento: ' + conta
  imprimir 'Tipo: ' + xml.tipo()
              
  se(xml.contemValor()){
  	 imprimir 'Valor: ' + xml.valor()
  }
  
  se(xml.contemProximo()){
	imprimir 'Tipo do proximo elemento: ' + xml.tipoProximo()
  }
  
  se(xml.ehTipoInicioElemento()){ 
      imprimir 'Nome: ' + xml.nome()   
      percorrer(xml.atributos()){
  		imprimir 'Atributo: ' + item.nome() + '=' + item.valor()
  	}
  }
}

xml = Arquivo.ler('<root><!-- Nomes dos colaboradores --><nome completo="N" composto="S">Marcos da Silva</nome><nome completo="S">Maria Joana Amaral</nome></root>', 'xml');

//Leitura baseada em elementos
percorrer(enquanto: { xml.proximoElemento() }) { 

  imprimir '#Dados do elemento:'
  imprimir 'Tipo: ' + xml.tipo()
  imprimir 'Nome: ' + xml.nome()   
  imprimir 'Valor: ' + xml.valor()

  percorrer(xml.atributos()){
	imprimir 'Atributo: ' + item.nome() + '=' + item.valor()
  }
}

Escrita

arquivo = Arquivo.novo('FendaDoBiquine.xml', 'xml')

Parâmetros de escrita:

• encoding: Encoding do documento XML. Por padrão utiliza UTF-8.
• indentar: Indica se o documento será escrito indentado ou de forma linear. Utilizar S para Sim e N para Não.

xml.escreverInicioElemento('pessoa')
xml.escreverAtributo('idade', '18')
//Saída: <pessoa idade="18">

xml.escreverInicioElemento('pessoa')
xml.escreverTexto('João')
xml.escreverFimElemento('pessoa')
    
//Saída: <pessoa>João</pessoa>

<!-- comentário -->

xml.escreverElementoVazio('vazio')
//Saída: <vazio />

xml.escreverInicioDocumento('UTF-8', '1.0')
//Saída: <?xml version='1.0' encoding='UTF-8'?>

xml.escreverInicioElemento('pessoa')   
//Saída: <pessoa>

xml.escreverInicioElemento('pessoa')
xml.escreverInicioElemento('endereco')
imprimir xml.nomeElementoAtual() //Saída: endereco
xml.escreverFimElemento()
imprimir xml.nomeElementoAtual() //Saída: pessoa

xml.escreverInicioElemento('pessoa')
xml.escreverInicioElemento('endereco')
xml.escreverFimElementos()

//Saída: <pessoa><endereco></endereco></pessoa>

xml.escreverInicioElemento('pessoa')
xml.escreverInicioElemento('endereco')
xml.escreverInicioElemento('cidade')
xml.escreverInicioElemento('bairro')

xml.escreverFimElementos('endereco')

//Saída: <pessoa><endereco><cidade><bairro></bairro></cidade></endereco>

xml.escreverElementoTexto('nome', 'Maria')
//Saída: <nome>Maria</nome>

xml.escrever('<nome>José</nome>')

Leitura

json = Arquivo.ler('''
{
    "nome": "João da Silva",
    "telefones": [
            "4899999999999",
            "4899999999992"
    ]
}
''', 'json')

json.proximo() // inicio do objeto
json.proximo() // nome do primeiro campo

nomePessoa = ""
telefonesPessoa = []

percorrer(enquanto: { !json.ehFimObjeto() }) {

    nomeCampo = json.texto()

    se(nomeCampo == "nome"){
        nomePessoa = json.proximo().texto()
    }

    se(nomeCampo == "telefones"){

        json.proximo() // inicio do array
        json.proximo() // primero item do array

        telefones = []
        percorrer(enquanto: { !json.ehFimMatriz() }) {
            telefonesPessoa<<json.texto()
            json.proximo() // proximo item
        }
    }

    json.proximo() // avança para o proximo campo
}

pessoa = [nome: nomePessoa, telefones: telefonesPessoa]

Escrita

json = Arquivo.novo('pessoa.json', 'json')

json.escreverInicioObjeto()
json.escreverNomeCampo("nome")
json.escreverTexto("João da Silva")

json.escreverNomeCampo("telefones")
json.escreverInicioMatriz()

json.escreverTexto("4899999999999")
json.escreverTexto("4899999999992")

json.escreverFimMatriz()
json.escreverFimObjeto()

{
    "valor": ""
}

{
    "valor": "abc"
}

{
    "valor": 123
}

{
    "valor": true
}

{
    "valor": null
}

json.escreverObjeto([nome: "AAA"])

{
    "valor": {
        "nome": "AAA"
    }
}

Leitura

A leitura de arquivos .zip está disponível através da seguinte chamada:

zip = Arquivo.ler('arquivo.zip', 'zip')

Onde iterando, é possível navegar entre os arquivos:

percorrer(zip) {
    
    //Imprime o nome do arquivo, sem considerar extensão
    imprimir item.nome;

    imprimir item.extensao;
    
    //Imprime o nome inteiro do arquivo, incluindo extensão e a sua estrutura de pastas
    imprimir item.nomeAbsoluto;
    
    //É possivel identificar se o item em questão representa um diretório
    imprimir item.ehDiretorio();
    
    //Recupera uma referência de um arquivo ao conteúdo do zip.
    arquivo = item.arquivo;
    
    //Pode ser utilizado outras apis para trabalhar no arquivo descompactado...
    Arquivo.ler(arquivo, 'txt');
}

Obs: Caso durante a geração do zip, seja utilizado um encoding diferente do UTF-8, o valor deve ser informado. Por exemplo:

zip = Arquivo.ler('arquivo.zip', 'zip', [encoding: 'CP437'])

Escrita

arquivo = Arquivo.novo('relatorios.zip', 'zip')

arquivo = Arquivo.novo('relatorios.zip', 'zip')
arquivo.criarDiretorio('2016')

relatorios.zip
└─ 2016

arquivo = Arquivo.novo('relatorios.zip', 'zip')
arquivo.adicionar(parametros.arquivo.valor)

arquivo = Arquivo.novo('relatorios.zip', 'zip')
arquivo.adicionar(parametros.arquivo.valor, 'despesas.pdf')

relatorios.zip
└─ despesas.pdf

arquivo = Arquivo.novo('relatorios.zip', 'zip')
arquivo.adicionar(parametros.arquivo.valor, 'despesas.pdf', '2016')

relatorios.zip
└─ 2016
    └─ despesas.pdf

arquivo = Arquivo.novo('relatorios.zip', 'zip')
arquivo.adicionar(parametros.arquivo.valor, 'despesas.pdf', '2016/Despesas')

relatorios.zip
└─ 2016
    └─ Despesas
        └─ despesas.pdf

arquivo = Arquivo.novo('relatorios.zip', 'zip')
arquivo.adicionar([parametros.despesas.valor, parametros.receitas.valor])

relatorios.zip
├─ Despesas.pdf
└─ Receitas.pdf

arquivo = Arquivo.novo('relatorios.zip', 'zip')
arquivo.adicionar([parametros.despesas.valor, parametros.receitas.valor], 'Arquivos')

relatorios.zip
└─ Arquivos
   ├─ Despesas.xml
   └─ Receitas.xml

Arquivo.novo('relatorios.zip', 'zip').comentario('Arquivo contendo os relatórios')

de(email)

Define o email do remetente da mensagem

de(email, nome)

Define o email e nome do remetente da mensagem

para(email)

Adiciona um email de destinatário na mensagem

para(email, nome)

Adiciona um email e nome de destinatário na mensagem

copiaPara(email)

Adiciona um email de cópia na mensagem

copiaPara(email, nome)

Adiciona um email e nome de cópia na mensagem

copiaOcultaPara(email)

Adiciona um email de cópia oculta na mensagem

copiaOcultaPara(email, nome)

Adiciona um email e nome de cópia oculta na mensagem

responderPara(email)

Adiciona um email no qual a mensagem deverá ser respondia pelos destinatários

responderPara(email, nome)

Adiciona um email e nome no qual a mensagem deverá ser respondia pelos destinatários

mensagem(mensagem)

Define o conteúdo da mensagem

mensagemHtml(mensagem)

Define o conteúdo da mensagem como HTML

assunto(assunto)

Define o assunto da mensagem

cabecalho(nome, valor)

Adiciona um cabecalho no e-mail

autenticacao([usuario, senha, porta, host])

Autentica o envio do email. Exemplo de uso:

.autenticacao([ usuario: joao, senha: joao, porta: 587, host: smtp.live.com])

enviar()

Envia a mensagem de e-mail

Criando anexos:

A criação de anexos pode ser realizada através de funções específicas da API ou de forma simplificada pela mensagem. Anexos criados pelas funções da API devem ser manualmente adicionados à mensagem. Por motivo de performance, caso o mesmo anexo do tipo Arquivo tenha que ser enviado para vários destinatários em mensagens diferentes, este deverá ser criado pela API uma única vez no processo.

Funções de anexo da API

 csv = Arquivo.novo('teste.csv', 'csv')
 csv.escrever('Valor')
 csv.fechar()
 
 //Arquivo criado pela API de arquivos
 anexoArquivo = Email.criarAnexoArquivo(csv)
 
 //Parâmetro do script tipo Arquivo
 anexoParametro = Email.criarAnexoArquivo(parametros.xml.valor)
 
 Email.novo()
    .anexar(anexoArquivo)
    .anexar(anexoParametro)
 

Propriedades dos anexos

Funções de anexo da Mensagem

 anexo = Email.criarAnexoUrl('http://cnd.fgv.br/sites/cnd.fgv.br/files/teste_2.pdf', 'Nome do arquivo.pdf')
 msg.anexar(msg)

 csv = Arquivo.novo('teste.csv', 'csv')
 csv.escrever('Valor')
 csv.fechar()
 
 //Arquivo criado pela API de arquivos
 msg.anexarArquivo(csv)
 
 //Parâmetro do script tipo Arquivo
 msg.anexarArquivo(parametros.xml.valor) 

 msg.anexarUrl('http://cnd.fgv.br/sites/cnd.fgv.br/files/teste_2.pdf', 'Nome do arquivo.pdf')

Envio de e-mail autenticado

Email.novo()
	.autenticacao([ usuario: 'usuario', senha: 'senha', porta: 'porta', host: 'smtp.live.com' ])
	.de('betha@betha.com.br','Betha Sistemas')
	para(destinatario, 'Destinatário')
	.mensagem('Testando envio de email')
	.assunto('Envio cloud job')
	.enviar();

Envio de e-mail com anexos

email = Email.novo()
   
imagemAssinatura = Email.criarAnexoUrl('http://www.betha.com.br/site/images/betha-2.png', 'logo.png')
                        .dispostoParaVisualizacao()
                        .incorporado()
   
destinatario = 'destinatario@betha.com.br'
   
email.de('betha@betha.com.br','Betha Sistemas')
     .para(destinatario, 'Destinatário')
     .copiaPara(destinatario, 'Destinatário de cópia')
     .copiaOcultaPara(destinatario)
     .responderPara(destinatario, 'Nome para Resposta')
     .assunto('Teste de e-mail')
     .mensagemHtml('Este é um teste de e-mail. <br/><br/>' +
                      'Att, <br/><br/>' +
                      'Betha Sistemas <p/><p/>' + 
                      '<img src="cid:logo.png" width="319" height="51" />')
     .anexar(imagemAssinatura)
     .anexarUrl('http://cnd.fgv.br/sites/cnd.fgv.br/files/teste_2.pdf', 'Nome do arquivo.pdf')
     .enviar()
               
   
imprimir 'E-mail enviado com sucesso!'

Enviar arquivos dos parâmetros do script e API de Arquivos

csv = Arquivo.novo('teste.csv', 'csv')
csv.escrever('Valor')

anexoCsv = Email.criarAnexoArquivo(csv, 'teste.csv')
 
Email.novo()
     .de('betha@betha.com.br','Betha Sistemas')
     .para('destinatario@betha.com.br', 'Destinatário')
     .assunto('Teste de e-mail')
     .mensagem('Novo arquivo enviado.')
     .anexar(anexoCsv)
     .anexarArquivo(parametros.arquivo.valor, 'Arquivo.xml')
     .enviar()

para(usuarios)

Adiciona um usuário como destinatário da notificação. É possível adicionar vários usuários:

Notificacao.nova('Seja bem vindo!')
           .para('joao.silva', 'maria.silva')
           .enviar()

Também é possível adicionar o usuário logado como destinatário da notificação usando o identificador usuario.id:

Notificacao.nova('Seja bem vindo!')
           .para(usuario.id)
           .enviar()

Mais um exemplo, usando o usuário logado e outros usuários:

Notificacao.nova('Seja bem vindo!')
           .para(usuario.id, 'joao.silva', 'maria.silva')
           .enviar()

mensagem(mensagem)

Define a mensagem a ser enviada pela notificação

link(href)

Define o link a ser enviado pela notificação

link(href, titulo)

Define o link com título a ser enviado pela notificação

link(href, titulo, label)

Define o link, titulo e label a ser enviado pela notificação

enviar()

Realiza o envio da notificação aos destinatários.

Soap.servico(url)

Cria um novo servico com base na URL informada por parâmetro.

servico = Soap.servico('http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx')

Soap.servico(url, namespace, prefixo)

Cria um novo serviço com base na URL informada por parâmetro. O namespace e prefixo (target namespace) informados serão utilizados como padrão na montagem da mensagem e manipulação dos elementos.

Soap.servico('http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx',
             'http://ws.cdyne.com/',
             'ws')

Soap.servico(url, namespace, prefixo, usuario, senha)

Esta opção dá suporte a criação de serviços que utilizem mecanismos de autenticação HTTP básico permitindo informar também o usuário e senha de conexão como parâmetros.

Soap.criarNamespace(namespace, prefixo)

Cria uma representação de um namespace e prefixo para ser reutilizado nas funções da API, desta forma não é necessário informar namespace e prefixo a cada função.

Os valores podem ser acessados através das funções: namespace() e prefixo() da representação criada.

namespace = Soap.criarNamespace('http://ws.cdyne.com/', 'ws')
servico = Soap.servico('http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx', namespacePadrao)

imprimir namespace.namespace()
imprimir namespace.prefixo()

cabecalho(nome, valor)

Adiciona um cabeçalho(header) HTTP na requisição SOAP do serviço.

servico = Soap.servico('http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx')
servico.cabecalho('Authorization','Bearer 239e3d8e-1e93-4f2b-beff-c430103b9287')

cookie(nome, valor, path)

Adiciona um cookie na requisição SOAP do serviço.

servico = Soap.servico('http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx')
servico.cookie('nome', 'valor', 'path')

detalhe: path é opcional e pode ser omitido.

mensagem()

Cria uma nova mensagem (envelope) à ser enviado ao serviço.

mensagem(namespace, prefixo)

Cria uma nova mensagem (envelope) à ser enviado ao serviço sobrescrevendo o namespace e prefixo padrão informados na criação do serviço.

mensagem(namespace)

Cria uma nova mensagem (envelope) à ser enviado ao serviço sobrescrevendo o namespace e prefixo padrão informados na criação do serviço. Esta opção deve ser utilizada com namespaces criados com a função Soap.criarNamespace.

tempoLimite(valor)

Define o tempo limite para a execução das requisições. O valor deve ser informado em milissegundos.

namespace(namespace, prefixo)

Adiciona um namespace a mensagem. Este namespace será adicionado ao envelope SOAP da mensagem e poderá ser utilizado na declaração dos elementos.

namespace(namespace)

Adiciona um namespace a mensagem. Este namespace será adicionado ao envelope SOAP da mensagem e poderá ser utilizado na declaração dos elementos.

namespaces()

Retorna uma lista com os namespaces declarados na mensagem.

namespacePadrao()

Retorna o namespaces definido como padrão da mensagem.

corpo()

Retorna o elemento do corpo da mensagem.

corpo(conteudo)

Escreve o conteúdo XML no corpo da mensagem. É importante lembrar que o conteúdo deverá ser um XML válido e utilizar os namespaces declarados na mensagem/corpo.

servico.mensagem().corpo('<ws:VerifyEmail><ws:email>teste@test.com</ws:email><ws:LicenseKey>example</ws:LicenseKey></ws:VerifyEmail>')

corpo(arquivo)

Escreve o conteúdo XML no corpo da mensagem com base em uma fonte de arquivo. É importante lembrar que o conteúdo do arquivo deverá ser um XML válido e utilizar os namespaces declarados na mensagem/corpo.

xml = Arquivo.novo('msg.xml', 'xml')
xml.fechar()

servico.mensagem().corpo(xml)

cabecalho()

Retorna o elemento do cabeçalho da mensagem.

cabecalho(conteudo)

Escreve o conteúdo XML no cabeçalho da mensagem. É importante lembrar que o conteúdo deverá ser um XML válido e utilizar os namespaces declarados na mensagem/corpo.

servico.mensagem().cabecalho('<ws:VerifyEmail><ws:email>teste@test.com</ws:email><ws:LicenseKey>example</ws:LicenseKey></ws:VerifyEmail>')

cabecalho(arquivo)

Escreve o conteúdo XML no cabecalho da mensagem com base em uma fonte de arquivo. É importante lembrar que o conteúdo do arquivo deverá ser um XML válido e utilizar os namespaces declarados na mensagem/corpo.

xml = Arquivo.novo('msg.xml', 'xml')
xml.fechar()

servico.mensagem().cabecalho(xml)

operacao(operacao)

Define a operação/método/função a ser executada no webservice. Este valor será informado no cabeçalho HTTP SOAPAction da mensagem.

executar()

Executa a chamada ao método/função do serviço SOAP e retorna uma representação da resposta.

executar(operacao)

Executa a chamada ao método/função do serviço SOAP e retorna uma representação da resposta. Esta opção permite que o a operação à ser executada seja informada diretamente pela função executar() sem a necessidade de pré-definir o valor através da função operacao().

requisicao()

Retorna uma representação para leitura da requisição SOAP realizada. Esta leitor de mensagem contém as mesmas funcionalidades da resposta e poderá ser utilizado para fins de depuração.

Elementos

Um elemento pode ser considerado como uma representação baseada em árvore para descrever uma informação na mensagem. Os elementos de uma mensagem (corpo, cabeçalho) SOAP utilizam o padrão XML.

As opções disponíveis para manipulação dos elementos são:

nome()

Retorna o nome do elemento.

namespace()

Retorna o namespace do elemento.

adicionarElemento(nome)

Adiciona/cria um novo elemento. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

elemEnderecos = servico.mensagem()
                       .corpo()
                       .adicionarElemento('endereco')
                           
elemEnderecos.adicionarElemento('residencial')    
elemEnderecos.adicionarElemento('comercial')                                     

O elemento elemEnderecos irá produzir o seguinte XML na mensagem:

<endereco>
    <residencial></residencial>
    <comercial></comercial>
</endereco>

adicionarElemento(nome, namespace, prefixo)

Adiciona/cria um novo elemento informando também o namespace e prefixo de declaração do elemento. É importante lembrar que o namespace utilizado deve estar declarado na mensagem ou elemento pai. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

adicionarElemento(nome, namespace)

Adiciona/cria um novo elemento informando também o namespace de declaração do elemento. É importante lembrar que o namespace utilizado deve estar declarado na mensagem ou elemento pai. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

adicionarTexto(texto)

Adiciona conteúdo do tipo texto à um elemento. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

elemEnderecos.adicionarElemento('residencial')
             .adicionarTexto('Rua geral')

produzirá:

<residencial>Rua geral</residencial>

adicionarElementoTexto(nome, texto)

Adiciona um novo elemento com conteúdo do tipo texto. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

elemEnderecos.adicionarElementoTexto('residencial', 'Rua geral')

produzirá:

<residencial>Rua geral</residencial>

adicionarElementoTexto(nome, texto, namespace, prefixo)

Adiciona um novo elemento com conteúdo do tipo texto indicando também o namespace e prefixo que o elemento está vinculado. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

adicionarElementoTexto(nome, texto, namespace)

Adiciona um novo elemento com conteúdo do tipo texto indicando também o namespace e prefixo que o elemento está vinculado. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

adicionarAtributo(nome, valor)

Adiciona um novo atributo ao elemento atual. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

elemEnderecos.adicionarElemento('residencial')
             .adicionarAtributo('principal','N')

produzirá:

<residencial principal="N">Rua geral</residencial>

adicionarAtributo(nome, valor, namespace, prefixo)

Adiciona um novo atributo ao elemento atual indicando também o namespace e prefixo ao qual o atributo está vinculado. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

adicionarAtributo(nome, valor, namespace)

Adiciona um novo atributo ao elemento atual indicando também o namespace e prefixo ao qual o atributo está vinculado. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

adicionarNamespace(namespace, prefixo)

Adiciona a declaração de um namespace ao elemento atual. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

adicionarNamespace(namespace)

Adiciona a declaração de um namespace ao elemento atual. O retorno desta função é a representação do novo elemento criado e poderá ser utilizado para adicionar elementos filhos caso necessário.

elementoAnterior()

Utilizado para navegação entre os elementos criados de uma mesma família. Esta opção contém a representação do elemento pai do elemento corrente.

servico.mensagem()
       .corpo()
       .adicionarElemento('pessoas')
       .adicionarElementoTexto('nome', 'João')
       .elementoAnterior() //O elemento pai do elemento nome é pessoas
       .adicionarElementoTexto('nome', 'Maria')
                

produzirá:

<pessoas>
    <nome>João</nome>
    <nome>Maria</nome>
</pessoas>

contemElementoAnterior()

Indica se o elemento atual possui um próximo elemento.

proximoElemento()

Utilizado para navegação entre os elementos criados de uma mesma família. Esta opção contém a representação do primeiro elemento filho do item corrente.

contemProximoElemento()

Indica se o elemento atual possui um elemento anterior.

elemPessoas = servico.mensagem()
                     .corpo()
                     .adicionarElemento('pessoas')

imprimir elemPessoas.contemElementoAnterior() // true pois corpo() e cabecalho() são elementos da mensagem            
imprimir elemPessoas.contemProximoElemento() // false

elemPessoas.adicionarElementoTexto('nomePessoa', 'João')

imprimir elemPessoas.contemProximoElemento() // true
elemPessoas.proximoElemento().nome() // nomePessoa

Métodos

Métodos são representações auxiliares para simplificar a montagem dos elementos da mensagem nos casos em que o webservice contém apenas parâmetros simples como entrada.

As opções disponíveis para criação de métodos a partir da mensagem são:

metodo(operacao)

Cria um novo método para a operação/função informado no parâmetro.

metodo(operacao, namespace, prefixo)

Cria um novo método utilizando a operação, namespace e prefixo informados nos parâmetros.

metodo(operacao, namespace)

Cria um novo método utilizando a operação e namespaces informados nos parâmetros.

Exemplo:

metodoVerificaEmail = servico.mensagem().metodo('VerifyEmail')

As funções disponíveis na representação de métodos são:

parametro(nome, valor) Adiciona um parâmetro de entrada ao método atual.

parametro(nome, valor, namespace) Adiciona um parâmetro de entrada ao método atual utilizando o namespace informado.

operacao()

Retorna a operação do método atual.

namespace()

Retorna o namespace do método atual.

elemento()

Retorna o elemento que representa o método atual.

requisicao()

Retorna uma representação para leitura da requisição SOAP realizada. Esta leitor de mensagem contém as mesmas funcionalidades da resposta e poderá ser utilizado para fins de depuração.

executar()

Executa a chamada do método atual e retorna uma representação da resposta.

mensagem()

Retorna a representação da mensagem em que o método foi criado.

Exemplo:

servico = Soap.servico('http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx',
                       'http://ws.cdyne.com/', 'ws')
                       
resposta = servico.mensagem()
                  .metodo('VerifyEmail')
                  .parametro('email', parametros.email.valor)
                  .parametro('LicenseKey', '123')
                  .executar()

imprimir()

Imprime o conteúdo XML da resposta no console do editor de scripts.

conteudo()

Retorna o conteúdo XML da resposta no formato caracter.

resposta = servico.metodo('VerifyEmail')
       .parametro('email', parametros.email.valor)
       .parametro('LicenseKey', '123')
       .executar()

imprimir resposta.conteudo()

arquivo()

Retorna uma fonte de arquivo que contém o conteúdo da resposta. Esta opção deverá ser utilizada em conjunto com as demais APIs da engine de scripts.

resposta = servico.metodo('VerifyEmail')
       .parametro('email', parametros.email.valor)
       .parametro('LicenseKey', '123')
       .executar()

//Utilizando com a API de arquivos
xml = Arquivo.ler(resposta.arquivo(), 'xml')

//Utilizando o retorno como anexo da API de Email
Email.novo()
     .de('webservice@betha.com.br')
     .para('usuarios@betha.com.br')
     .assunto('Arquivo de resposta do webservice!')
     .anexarArquivo(resposta.arquivo(), 'resposta.xml')
     .enviar()     

xml()

Retorna um leitor de arquivos XML da API de Arquivos para o conteúdo da resposta.

resposta = servico.metodo('VerifyEmail')
       .parametro('email', parametros.email.valor)
       .executar()

xml = resposta.xml()
xml.proximoElemento('GoodEmail')

se(xml.valor() == 'true'){
  imprimir 'O endereço ' + parametros.email.valor + ' é um e-mail válido!'
} senao {
  imprimir 'O endereço ' + parametros.email.valor + ' é inválido!'
}

anexos()

Retorna uma lista com os anexos presentes na mensagem de retorno do serviço.

retorno = servico.mensagem().corpo(xml).executar()
anexos = retorno.anexos()

percorrer(anexos) {
    imprimir item.id()
    imprimir item.tipo()
    imprimir item.cabecalho("Content-Type") // mesmo valor do item.tipo()
    
    arquivo = item.arquivo()
}

anexo(id)

Localiza e retorna um anexo de acordo com o seu id

retorno = servico.mensagem().corpo(xml).executar()

anexo = retorno.anexo(xmlRetorno.atributo("href").valor());
Resultado.arquivo(anexo.arquivo());

Contornando a limitação cumulativa

Caso seja necessário codificar ou decodificar diversos conteúdos e esteja sendo esbarrado no limite cumulativo, pode-se utilizar métodos que não retornam como o resposta o conteúdo (não alocando no contexto global), e sim disponibilizam ele dentro de uma closure, que acaba liberando a memória alocada mais rapidamente:

input = 'Meu texto'; //poderia ser um arquivo
BaseCodec.padrao64().codifica(input) { conteudo ->
   imprimir conteudo.texto();
}

inputEncoded = 'YWJjZGVmZ2hp'; //poderia ser um arquivo
BaseCodec.padrao64().decodifica(inputEncoded) { conteudo ->
   imprimir conteudo.texto();
}

Fazendo o uso dessas chamadas, o limite passa a ser de 30mb de forma individual e não descontando do limite cumulativo global.

É recomendado que não se atríbua essa variável interna para um contexto maior, permitindo assim que a memória alocada seja liberada

identificador

Identificador único do script.

executar(parametros)

Função responsável pela execução do script.

parametros = [ p1 : 100, p2 : 200]

Scripts.somar.executar(parametros)

variaveis(Map)

Função responsável por enviar variáveis para outro script sem a necessidade de ter parâmetros no script que recebe essas variáveis.

O script de exemplo tem dois parâmetros do tipo arquivo, com os nomes arquivo e arquivo2, esses arquivos são enviados para o segundo script identificado por scriptb:

arquivos = [arquivo1: parametros.arquivo.valor, arquivo2: parametros.arquivo2.valor, val3:'teste teste 123']

Scripts.scriptb.variaveis(arquivos).executar();

No script que recebe as variáveis, os valores estão disponíveis da seguinte maneira:

Resultado.arquivo(variaveis.arquivo1)
Resultado.arquivo(variaveis.arquivo2)

imprimir variaveis.val3

O scriptb não precisa ter nenhum parâmetro para receber as variáveis e qualquer tipo pode ser passado por variaveis().

Outro exemplo seria um script principal que gera um arquivo csv com valores obtidos em execuções de outros três scripts:

Script principal:

//Escrita
csv = Arquivo.novo('teste.csv', 'csv', [delimitador:';'])

csv.escrever('ID')
csv.escrever('NOME')
csv.escrever('SALARIO')

Scripts.geraarquivo.funcionarios1.variaveis(arquivo:csv).executar()


geraArquivo = {col1, col2, col3 ->
  csv.novaLinha()
  
  csv.escrever(col1)
  csv.escrever(col2)
  csv.escrever(col3)
}

Scripts.geraarquivo.funcionarios2.variaveis(retorno:geraArquivo).executar()

retorno = Scripts.componente3.executar()

imprimir retorno.variaveis.geraArquivo2();  // imprime o valor teste2 no log de execução do script principal

retorno.variaveis.geraArquivo(csv)

Resultado.arquivo(csv)

Script com o identificador geraarquivo.funcionarios1:

csv = variaveis.arquivo
criterio = Criterio.onde('nome').igual('Paulo Henrique')

dadosFuncionarios = Dados.dubai.v1.funcionarios

percorrer(dadosFuncionarios.busca(campos:"nome, id, salario", criterio: criterio)){ 
    csv.novaLinha()
  	csv.escrever(item.id)
	csv.escrever(item.nome)
	csv.escrever(item.salario)
}

Script com o identificador geraarquivo.funcionarios2:

dadosFuncionarios = Dados.dubai.v1.funcionarios
criterio = Criterio.onde('nome').igual('Wellington')

id = '';
nome = '';
salario = '';

percorrer(dadosFuncionarios.busca(campos:"nome, id, salario", criterio: criterio)){ 
  	id = item.id
	nome = item.nome
	salario = item.salario
}

variaveis.retorno(id, nome, salario)

Script com o identificador componente3:

geraArquivo2 = {
  retornar "teste2"
}

geraArquivo = {csv ->
  csv.novaLinha()
  
  csv.escrever('Valor 31')
  csv.escrever('Valor 32')
  csv.escrever('Valor 33')
  
}

Ao executar o script principal o arquivo csv é gerado.

valor

Recupera o valor retornado pelo script executado.

imprimir resultado.valor()

vazio

Verifica se o script invocado retornou algum resultado.

resultado = Scripts.somar.executar([ p1 : 100, p2 : 200])
 
se(resultado.vazio){
   imprimir 'Nenhum resultado foi retornado pelo script somar'
}

variavel(nome)

Recupera o valor de uma variável declarada no script invocado.

resultado = Scripts.somar.executar([ p1 : 100, p2 : 200]) 
imprimir resultado.variavel('log') //Realizando soma

Note que a variável log foi declarada no conteúdo do script somar:

log = "Realizando soma"  
retornar parametros.p1.valor + parametros.p2.valor

retornar

O retorno de um script é realizado utilizando o comando retornar:

retornar 'Retornando uma mensagem'

ret = [valor: 1, mensagem: 'Retornando um mapa']
retornar ret

Exemplos de utilização:

Exemplo 1: Este exemplo demonstra um componente que abstrai uma API REST.

Segue o código de um componente cujo identificador foi denominado restapi e que será chamado pelo script pai:

// variável local e privada ao componente
api = Http.servico('https://jsonplaceholder.typicode.com')
 
// closure privada ao componente
extractContent = { response ->
  conteudo = -1
  
  se (response.sucesso() && response.contemResultado()) {
    conteudo = response.conteudo()
  }
  
  retornar conteudo
}
 
getPost = { id ->
  extractContent(api.caminho("posts/$id").GET())
}
 
getComments = { idPost ->
  extractContent(api.caminho("posts/$idPost/comments").GET())
}
 
Scripts.exportar(
  buscarPublicacao: getPost,
  buscarComentarios: getComments
)

O comando exportar é utilizado para definir quais recursos serão expostos pelo componente. Repare que as declarações que não foram exportadas permanecem privadas ao componente, permitindo assim uma modelagem mais robusta de funcionalidades comuns a vários scripts.

Segue o código do script pai que chama o componente acima:

api = Scripts.restapi.importar()

publicacao = api.buscarPublicacao(1)

se (publicacao != -1) {
  imprimir "Publicacao: " + publicacao
}

comentarios = api.buscarComentarios(1)

se (comentarios != -1) {
  imprimir "Comentarios: " + comentarios
}

A importação dos recursos de um componente é realizada utilizando a palavra reservada Scripts, seguido do identificador e o método de importação. O resultado é atribuído a uma variável, a partir da qual os recursos importados podem ser acessados.

Alternativamente, pode-se utilizar a palavra reservada importar, passando como parâmetro o identificador do componente, no caso, fica assim:

api = importar "restapi"

Exemplo 2: Este exemplo trata de múltiplos componentes para um único Script Pai:

Existem 3 componentes:

• Que simula uma calculadora;
• Que executa um contador;
• Que gera um log;

Componente 1: identificador ped.calculadora

add = { p1, p2 ->
  p1 + p2
}

sub = { p1, p2 ->
  p1 - p2
}

mul = { p1, p2 ->
  p1 * p2
}

div = { p1, p2 ->
  p1 / p2
}

exportar(
  somar: add,
  subtrair: sub,
  multiplicar: mul,
  dividir: div
)

Componente 2: identificador ped.contador

current = 0

inc = { amount = 1 -> current += amount }
dec = { amount = 1 -> current -= amount }
reset = { current = 0 }
get = { current }

Scripts.exportar(
        incrementar: { inc(1) },
        incrementarEm: inc,
        decrementar: { dec(1) },
        decrementarEm: dec,
        zerar: reset,
        atual: get
)

Componente 3: identificador ped.log

logFile = Arquivo.novo('log.txt')

logInfo = { text ->
  logFile.escrever("INFO: $text")
  logFile.novaLinha()
}

logError = { text ->
  logFile.escrever("ERROR: $text")
  logFile.novaLinha()
}

commit = {
  imprimir "Adicionado log no resultado"
  Resultado.arquivo(logFile, 'log.txt')
}

exportar(
  info: logInfo,
  erro: logError,
  salvar: commit
)

Finalmente, o Script Pai:

calculadora = importar "ped.calculadora"
contador = importar "ped.contador"

imprimir "2 + 2 = ${calculadora.somar(2, 2)}"
imprimir "2 - 2 = ${calculadora.subtrair(2, 2)}"
imprimir "2 * 2 = ${calculadora.multiplicar(2, 2)}"
imprimir "2 / 2 = ${calculadora.dividir(2, 2)}"

imprimir "Inicio: " + contador.atual()
imprimir "+1: " + contador.incrementar()
imprimir "+10: " + contador.incrementarEm(calculadora.somar(5, 5))
imprimir "Zerado: " + contador.zerar()

//------------------------------------------------
log = importar "ped.log"

log.info("Iniciando execução")

percorrer(ate: 5) {
  log.info("Executando passo #$indice")
}

log.erro("Erro na conversão dos valores")
log.salvar()

cookie(nome, valor)

Adiciona um cookie na requisição HTTP.

cookie(nome, valor, caminho, domínio, versão)

Adiciona um cookie na requisição HTTP informando também o caminho/path, domínio e versão do cookie.

cookie(Mapa[nome, valor])

Adiciona um ou vários cookies (nome/valor) na requisição HTTP com base em uma mapa.

servico = Http.servico('https://jsonplaceholder.typicode.com/posts')
servico.cookie('Usuario', 'João da Silva')
servico.cookie('Usuario', 'João da Silva', '/usuarios', 'betha.com.br', 1)
servico.cookie([ Usuario: 'João da Silva', Accesso: 'sim' ])

cabecalho(nome, valor)

Adiciona um cabeçalho/header na requisição HTTP.

cabecalho(nome, lista de valores)

Adiciona um cabeçalho/header com vários valores na requisição HTTP.

cabecalho(Mapa[nome, valor])

Adiciona um ou vários cabeçalhos/headers (nome/valor) na requisição HTTP com base em uma mapa.

servico.cabecalho('Authorization', 'Basic ABCF5065FGC==')
servico.cabecalho('User', ['murphy', 'luiz.silva'])
servico.cabecalho([ User: 'alex.o.leao'])

Parâmetros e caminhos

Para permitir que um mesmo serviço atenda as mais diversas situações encontradas em APIs HTTP, as funções caminho() e parametro() possuem um comportamento diferenciado das demais. Estas funções quando executadas criam uma cópia da requisição atual adicionado os respectivos parâmetro(s)/caminho(s). Desta forma a requisição original não é alterada e pode ser reutilizada para outras invocações no mesmo serviço.

Exemplo:

servico = Http.servico('https://jsonplaceholder.typicode.com')

//Gera uma chamada GET ao endereço https://jsonplaceholder.typicode.com/posts?id=5
servico.caminho('posts')
       .parametro('id', 5)
       .GET()

//Gera uma chamada GET ao endereço https://jsonplaceholder.typicode.com/users/admins?id=5
servico.caminho('users')
       .caminho('admins')
       .parametro('id', 2)
       .GET()

//Caso se deseje alterar a requisição original basta associar a cópia ao serviço original, desta forma
//todas as requisições criadas à partir deste serviço utilizaram estes caminhos
servico = servico.caminho('users')
                 .caminho('admins')

//Gera uma chamada GET ao endereço https://jsonplaceholder.typicode.com/users/admins/ativos?id=5
servico.caminho('ativos')
       .parametro('id', 5)
       .GET()

parametro(nome, valor)

Cria uma cópia da requisição atual adicionando um parâmetro de query.

parametro(nome, lista de valores)

Cria uma cópia da requisição atual adicionando um ou mais parâmetros de query na requisição.

parametro(Mapa[nome, valor])

Cria uma cópia da requisição atual adicionando um ou mais parâmetros de query na requisição com base no mapa informado no parâmetro.

servico.parametro('id', '1') //posts?id=1
servico.parametro('id', ['1', '2', '5']) //posts?id=1&id=2&id=5
servico.parametro([ id: '5', nome: 'joao']) //posts?id=1&nome=joao

servico = Http.servico(...)
servico.parametro('id', 1)
servico.parametro('id', 2)

imprimir servico.parametros() //[] - Vazio pois como cria uma cópia o serviço original não é alterado
servico = servico.parametro('id', 1)
                 .parametro('id', 2)

imprimir servico.parametros() //[id : [1,2]] - pois atribuímos a cópia o serviço original

caminho(caminho)

Cria uma cópia da requisição atual adicionando um caminho/path na URL corrente.

servico = Http.servico('https://jsonplaceholder.typicode.com')

servico.caminho('posts')
       .caminho('listar') //URL: https://jsonplaceholder.typicode.com/posts/listar

aceitarTipoMidia(midias)

Informa qual tipo de mídia é aceito pela requisição. O valor padrão é Http.TODOS.

servico.aceitarTipoMidia('application/json')

A API conta com algumas constantes para os tipos de mídia comuns:

• Http.JSON: application/json
• Http.XML: application/xml
• Http.TEXTO_XML: text/xml
• Http.XHTML: application/xhtml+xml
• Http.TEXTO_HTML: text/html
• Http.TEXTO: text/plain
• Http.FORMULARIO: application/x-www-form-urlencoded
• Http.MULTIPART: multipart/form-data
• Http.ARQUIVO: application/octet-stream
• Http.TODOS: */*

servico.aceitarTipoMidia(Http.JSON)
servico.aceitarTipoMidia([Http.JSON, Http.XML])

credenciais(usuario, senha)

Configura a autenticação básica HTTP no serviço.

servico.credenciais('user', '123')

tempoLimite(valor)

Define o tempo limite para requisições executadas a partir do serviço. O valor deve ser informado em milissegundos.

// define timeout de 30 segundos
servico.tempoLimite(30000)

GET (Mapa[marcadores])

Executa uma chamada do tipo GET ao serviço retornando uma representação de resposta.

resposta = Http.servico('https://www.betha.com.br/users').GET()

svcUsuarios = Http.servico('https://www.betha.com.br/usuarios/{uf}/{nome}')
svcUsuarios.GET([uf: 'SC', nome: 'joao'])
svcUsuarios.GET([uf: 'SP', nome: 'maria'])

OPTIONS (Mapa[marcadores])

Executa uma chamada do tipo OPTIONS ao serviço retornando uma representação de resposta.

resposta = Http.servico('https://www.betha.com.br/users').OPTIONS()

HEAD (Mapa[marcadores])

Executa uma chamada do tipo HEAD ao serviço retornando uma representação de resposta.

resposta = Http.servico('https://www.betha.com.br/users').HEAD()

TRACE (Mapa[marcadores])

Executa uma chamada do tipo TRACE ao serviço retornando uma representação de resposta.

resposta = Http.servico('https://www.betha.com.br/users').TRACE()

DELETE ()

DELETE (Mapa[marcadores])

DELETE (dados, Mapa[marcadores])

DELETE (dados, Tipo de mídia)

DELETE (dados, Tipo de mídia, Mapa[marcadores])

Executa uma chamada do tipo DELETE ao serviço retornando uma representação de resposta. Os dados da requisição são enviados conforme tipo de mídia informado no parâmetro sendo Http.JSON (application/json) o valor padrão.

dados = [
    id: "5",
    author: "Uncle Bob",
]

resposta = Http.servico('https://www.betha.com.br/users').DELETE()
resposta = Http.servico('https://www.betha.com.br/users/{id}').DELETE([id: '5'])
resposta = Http.servico('https://www.betha.com.br/users/{id}').DELETE(dados, [id: '5'])
resposta = Http.servico('https://www.betha.com.br/users/{id}').DELETE(dados, Http.JSON)
resposta = Http.servico('https://www.betha.com.br/users/{id}').DELETE(dados, Http.JSON, [id: '5'])

POST (dados)

POST (dados, Mapa[marcadores])

POST (dados, Tipo de mídia)

POST (dados, Tipo de mídia, Mapa[marcadores])

POST (formulário)

POST (formulário, Mapa[marcadores])

Executa uma chamada do tipo POST ao serviço retornando uma representação de resposta. Os dados/formulário da requisição são enviados conforme tipo de mídia informado no parâmetro sendo Http.JSON (application/json) o valor padrão.

conteudo = [
    title: "The rabbit in the topper",
    author: "Mr. M",
]

resposta = Http.servico('https://www.betha.com.br/users')
               .POST(conteudo, Http.JSON)

resposta = Http.servico('https://www.betha.com.br/users')
               .POST('{"nome":"Test"}', Http.JSON)

resposta = Http.servico('https://www.betha.com.br/users/{id}')
               .POST(conteudo, Http.JSON, [id: 5])

PUT (dados)

PUT (dados, Mapa[marcadores])

PUT (dados, Tipo de mídia)

PUT (dados, Tipo de mídia, Mapa[marcadores])

PUT (formulário)

PUT (formulário, Mapa[marcadores])

Executa uma chamada do tipo PUT ao serviço retornando uma representação de resposta. Os dados/formulário da requisição são enviados conforme tipo de mídia informado no parâmetro sendo Http.JSON (application/json) o valor padrão.

conteudo = [
    title: "The rabbit in the topper",
    author: "Mr. M",
]

resposta = Http.servico('https://www.betha.com.br/users')
               .PUT(conteudo, Http.JSON)

resposta = Http.servico('https://www.betha.com.br/users')
               .PUT('{"nome":"Test"}', Http.JSON)

resposta = Http.servico('https://www.betha.com.br/users/{id}')
               .PUT(conteudo, Http.JSON, [id: 5])

PATCH (dados)

PATCH (dados, Mapa[marcadores])

PATCH (dados, Tipo de mídia)

PATCH (dados, Tipo de mídia, Mapa[marcadores])

PATCH (formulário)

PATCH (formulário, Mapa[marcadores]

Executa uma chamada do tipo PATCH ao serviço retornando uma representação de resposta. Os dados/formulário da requisição são enviados conforme tipo de mídia informado no parâmetro sendo Http.JSON (application/json) o valor padrão.

conteudo = [
    title: "The rabbit in the topper",
    author: "Mr. M",
]

resposta = Http.servico('https://www.betha.com.br/users')
               .PATCH(conteudo, Http.JSON)

resposta = Http.servico('https://www.betha.com.br/users')
               .PATCH('{"nome":"Test"}', Http.JSON)

resposta = Http.servico('https://www.betha.com.br/users/{id}')
               .PATCH(conteudo, Http.JSON, [id: 5])

METODO (método)

METODO (Mapa[marcadores], método)

METODO (método, dados)

METODO (método, dados, Mapa[marcadores])

METODO (método, tipo de mídia)

METODO (método, dados, tipo de mídia)

METODO (método, dados, tipo de mídia, Mapa[marcadores])

METODO (formulário)

METODO (formulário, Mapa[marcadores]

A função METODO é utilizada para realizar chamadas utilizando métodos personalizados. Tem como retorno uma representação de resposta. Os dados/formulário da requisição quando existentes são enviados conforme tipo de mídia informado no parâmetro sendo Http.JSON (application/json) o valor padrão.

dados = [
    title: "The rabbit in the topper",
    author: "Mr. M",
]

resp = Http.servico('https://www.betha.com.br/users')
           .METODO('GET'); //GET sem corpo

resp = Http.servico('https://www.betha.com.br/users/{id}')
           .METODO([id: 'joao'], 'GET'); //Marcadores de URL

resp = Http.servico('https://www.betha.com.br/users')
           .METODO('POST', dados)

Formulários

Para permitir o uso de serviços web onde os dados são recebidos no formato de formulários (form), a API conta com os seguintes facilitadores:

servico = Http.servico('https://www.betha.com.br/users')
formulario = servico.criarFormulario()

formulario = servico.criarFormulario()
                    .parametro("nome", "Betha")

parametros = [nome: "Betha", site: "www.betha.com.br"]

formulario = servico.criarFormulario()
                    .parametro(parametros)

parametros = [nome: "Betha", site: "www.betha.com.br"]

resposta  = servico.criarFormulario()
                    .parametro(parametros)
                    .POST()

resposta  = servico.criarFormulario().PUT()

resposta  = servico.criarFormulario().PATCH()

resposta  = servico.criarFormulario().METODO('POST')

servico = Http.servico('https://www.betha.com.br/users')
formulario = servico.criarFormularioMultipart()

servico = Http.servico('https://www.betha.com.br/users')
formulario = servico.criarFormularioMultipart()
                    .parametro("nome", "João")
                    .parametro("foto", arquivo, Http.ARQUIVO) //Fonte de arquivo da API de arquivos
                    .parametro([nome: "Betha", site: "www.betha.com.br"]) //valores baseados em um mapa

resposta  = servico.criarFormularioMultipart().POST()

resposta  = servico.criarFormularioMultipart().PUT()

resposta  = servico.criarFormularioMultipart().PATCH()

resposta  = servico.criarFormularioMultipart().METODO('POST')

codigo()

Retorna o código HTTP da resposta.

resposta = ...

se (resposta.codigo() == 404) {
    imprimir 'Servidor não encontrado';
}

tipoMidia()

Retorna o tipo de mídia da resposta

imprimir 'A resposta é do tipo ' + resposta.tipoMidia()

ehJson()

Indica se o tipo de mídia da resposta é do tipo JSON

se (resposta.ehJson()){
    imprimir 'A resposta é um JSON'
}

sucesso()

Indica se o código resposta é considerado como sucesso segundo o padrão HTTP.

se (resposta.sucesso()){
    imprimir 'Tudo OK com a chamada HTTP'
}

tamanho()

Retorna o tamanho do conteúdo segundo o cabeçalho da resposta (Content-Length) recebido. Caso o valor não seja retornado pelo servidor ou seja inválido retorna -1.

contemResultado()

Indica se a requisição retornou algum resultado. Esta verificação é realizada com base no conteudo() e no tamanho() da mensagem e pode ou não estar presente dependendo de cada serviço utilizado.

ultimaModificacao()

Retorna a data da ultima modificação do resultado. Este valor é obtido do resultado da requisição e pode ou não estar presente dependendo de cada serviço utilizado.

cookie(nome)

Recupera um cookie da resposta com base no nome. Um cookie pode conter as seguintes informações:

• nome(): Nome do cookie
• valor(): Valor do cookie
• valorCodificado(): Valor do cookie codificado no padrão URL
• valorDecodificado(): Valor do cookie no padrão URL decodificado
• caminho(): Caminho/Path do cookie
• dominio(): Domínio do cookie
• versao(): Versão do cookie (número)
• comentario(): Comentário do cookie
• idadeLimite(): Idade limite/tempo de duração do cookie (maxAge)
• expira(): Data de expiração do cookie
• ehSeguro(): Indica se é seguro
• ehSomenteHttp(): Indica se é somente HTTP

usaEnterComoTab = resposta.cookie('UsaEnterComoTab')
imprimir 'O usuário utiliza enter como TAB: ' + usaEnterComoTab.valor()

contemCookie(nome)

Indica se a resposta contém um cookie com o nome informado no parâmetro.

cookies()

Recupera uma lista contendo os cookies retornados na resposta.

percorrer(resposta.cookies()){
    imprimir item.nome() + ':' + item.valor()
}

cabecalho(nome)

Recupera um cabeçalho(Header) da resposta com base no nome. Um cabeçalho poder conter as seguintes informações:

• nome(): Nome do cabeçalho
• valores(): Uma lista contendo todos os valores do cabeçalho
• valor(): O primeiro valor encontrado do cabeçalho

imprimir resposta.cabecalho('Authorization').valor()

contemCabecalho(nome)

Indica se a resposta contém um cabeçalho (Header) com o nome informado no parâmetro.

cabecalhos()

Recupera uma lista contendo os cabeçalhos retornados na resposta.

percorrer(resposta.cabecalhos()){
    imprimir item.nome() + ':' + item.valor()
}

cookie(nome)

Retorna o cookie (caso definido)

resposta.cookie('nome').valor();

imprimir()

Imprime o conteúdo da resposta no console do editor de scripts.

conteudo()

Retorna o conteúdo da resposta no formato de caracteres.

resposta = Http.servico('https://www.betha.com.br/users').GET()
imprimir resposta.conteudo()

arquivo()

Retorna uma fonte de arquivo que contém o conteúdo da resposta. Esta opção deverá ser utilizada em conjunto com as demais APIs da engine de scripts.

resposta = Http.servico('https://www.betha.com.br/users').GET()

//Utilizando com a API de arquivos
texto = Arquivo.ler(resposta.arquivo(), 'txt')

//Utilizando o retorno como anexo da API de Email
Email.novo()
     .de('webservice@betha.com.br')
     .para('usuarios@betha.com.br')
     .assunto('Arquivo de resposta do webservice!')
     .anexarArquivo(resposta.arquivo(), 'resposta.txt')
     .enviar()

json()

Retorna o resultado de uma serviço JSON como Mapa/Lista de mapa.

resposta = Http.servico('https://www.betha.com.br/users/5').GET()

json = resposta.json()

imprimir json.id
imprimir json.nome

Obrigatoriedade dos valores

Caso seja necessário configurar a obrigatoriedade dos valores de forma pontual, é possível configurar em qualquer operação que aceite um valor como parâmetro:

Criterio.onde('idade').igual(valor, [ parametro: Criterio.obrigatorio() ]); 
Criterio.novo([ parametros: Criterio.obrigatorio('É necessário informar um valor para o campo ${campo}') ]).onde('idade').igual(27).e('nome').igual(valorNome, [ parametro: Criterio.opcional() ]);

Quando se configura a obrigatoriedade para todos os parâmetros do critério, a propriedade se chama parametros. Porém quando é configurado a nível de operação, se chama parametro.

Com delimitador

numero = [1,2,5] 
criterio = Criterio.onde('idade').contidoEm(numero, [delimitador: '"']);

O critério acima, gera o seguinte filtro:

idade in ("1", "2", "5")

Sem delimitador

numero = [1,2,5] 
criterio = Criterio.onde('idade').contidoEm(numero);

O critério acima, gera o seguinte filtro:

idade in (1, 2, 5)

Com formatação e delimitador

data1 = Datas.data(2017, 1, 11) 
data2 = Datas.data(2016, 1, 10) 
datas = [ data1, data2 ] 
criterio = Criterio.onde('aniversario').contidoEm(datas, [formatacao: "data", delimitador: "'"])

O critério acima, gera o seguinte filtro:

aniversario in ('2017-01-11', '2016-01-10')

​Informar uma das formatações pré-definidas (data e hora)

​​Criterio.onde('dataNascimento').igual(Datas.hoje()​, [formatacao: 'data']​); 
Criterio.onde('​horaAlmoco').igual(Datas.hoje()​, [formatacao: 'hora']​);​ ​​

Os critérios acima, geram os seguintes filtros:

dataNascimento = ​2018-02-05 
horaAlmoco = 09:43:45.045

​Informar uma ​formatação customizada

​​Criterio.onde('dataNascimento').igual(Datas.hoje(), [ formatacao: 'dd/MM/yyyy']);

Consultar o protocolo da execução

Execucao.atual.protocolo

Consultar se a execução foi cancelada pelo usuário

Execucao.atual.foiCancelada

Cache.adicionar(chave, valor)

Adiciona um novo valor no cache, com a chave informada e o tempo de expiração padrão de 12 horas.

Cache.adicionar('meu-token', 'aaabbbccc')

Cache.adicionar(chave, valor, expirarEm)

Adiciona um novo valor no cache, com a chave informada e o tempo de expiração (opicional).

Cache.adicionar('meu-token', 'aaabbbccc', 2.horas)

Cache.recuperar(chave, valorPadrao)

Recupera um valor colocado previamente no cache, ou retorna o valor padrão.

Cache.recuperar('meu-token', '')

Cache.contem(chave)

Verifica se o cache ontem algum valor para a chave informada.

Cache.remover(chave)

Remove o valor para chave informada.

Stack Dubai

O bfc-script esta disponível desde a versão 1.7.0 da stack.

Deve-se mapear as seguintes dependências:

        <dependency>
            <groupId>com.betha.bfc.commons</groupId>
            <artifactId>bfc-rest-script</artifactId>
        </dependency>
        <dependency>
            <groupId>com.betha.bfc.core</groupId>
            <artifactId>bfc-script-standard-engine</artifactId>
        </dependency>
        <dependency>
            <groupId>com.betha.bfc.commons</groupId>
            <artifactId>bfc-script-standard-engine-production</artifactId>
        </dependency>        

Para projetos web, não é necessário mapear a dependência bfc-rest-script.

Em projetos que possuem explicitamente o uso do cglib, ou alguma dependência que o utiliza, é necessário remove-la do projeto, para não gerar conflito com o bfc-script.

Passando parâmetros para um script

Para passar informações para nossos scripts, precisamos seta-las como variáveis dentro da engineContext. Observe o script abaixo. Daremos um id à este script, 30.

valor = valorSalarioHora * 8 * 22
 
imprimir valor

Executamos o script acima passando o id do script para o método run.

ScriptEngineContext engineContext = ScriptManager.createContext();
 
engineContext.setVariable("valorSalarioHora", 66.35);
engineContext.run("30");

O script de código 30 utiliza uma variável chamada valorSalarioHora para efetuar um calculo, esta variável é setada no momento da execução desse script, conforme vimos acima.

valor = funcionario.valorSalarioHora * 8 * 22
 
imprimir valor

Funcionario funcionario = new Funcionario();
funcionario.setValorSalarioHora(66.35);

ScriptEngineContext engineContext = ScriptManager.createContext();

engineContext.setVariable("funcionario", funcionario);
engineContext.run("30");

percorrer(funcionarios){
    valor = item.valorSalarioHora * 8 * 22

    imprimir valor
}

Funcionario funcionario1 = new Funcionario();
funcionario.setValorSalarioHora(66.35);

Funcionario funcionario2 = new Funcionario();
funcionario.setValorSalarioHora(70.23);

List<Funcionario> funcionarios = new ArrayList<Funcionario>();
funcionarios.add(funcionario1);
funcionarios.add(funcionario2);

ScriptEngineContext engineContext = ScriptManager.createContext();

engineContext.setVariable("funcionarios", funcionarios);
engineContext.run("30")

    @ScriptInjectable.NoProxy
    public class Funcionario{
        // ...
    }

@ScriptInjectable
public class VariaveisScriptFolha {

    @ScriptInjectable.Variable
    private Funcionario funcionario;

    @ScriptInjectable.Variable(name = "eventoFolha")
    private Evento evento;

    @ScriptInjectable.Variable(name = "usuarioLogado")
    private String usuario;

    public VariaveisScriptFolha(Funcionario funcionario, Evento evento, String usuario) {
        this.funcionario = funcionario;
        this.evento = evento;
        this.usuario = usuario;
    }
    
}

	Funcionario funcionario = ...;
	Evento evento = ...;
	String usuarioLogado = ...;
	
	VariaveisScriptFolha = variaveisScript = new VariaveisScriptFolha(funcionario, evento, usuarioLogado);
	
	ScriptEngineContext engineContext = ScriptManager.createContext();
	
	engineContext.inject(Injectables.byAnnotation(variaveisScript));

@ScriptInjectable
public class VariaveisScriptFolha {

    @ScriptInjectable.Variable(doc = @ScriptInjectable.Doc("Funcionário para o qual o calculo esta sendo executado"))
    private Funcionario funcionario;

    @ScriptInjectable.Variable(name = "eventoFolha", doc = @ScriptInjectable.Doc("Fornece os dados sobre o evento da folha que esta sendo calculado"))
    private Evento evento;

    @ScriptInjectable.Variable(name = "usuarioLogado", doc = @ScriptInjectable.Doc("Usuário logado no sistema"))
    private String usuario;

    public VariaveisScriptFolha(Funcionario funcionario, Evento evento, String usuario) {
        this.funcionario = funcionario;
        this.evento = evento;
        this.usuario = usuario;
    }

}

public class Funcionario {

    private String nome;

    private Integer idade;

    private BigDecimal salario;

    private Date dataAdmissao;

    @ScriptInjectable.Method(
            doc = @ScriptInjectable.Doc("Nome do funcionário"),
            ret = @ScriptInjectable.Return(
                    doc = @ScriptInjectable.Doc("O nome do funcionário")))
    public String getNome() {
        return nome;
    }

    @ScriptInjectable.Method(
            doc = @ScriptInjectable.Doc("Idade do funcionário"),
            ret = @ScriptInjectable.Return(
                    doc = @ScriptInjectable.Doc("A idade do funcionário")))
    public Integer getIdade() {
        return idade;
    }

    @ScriptInjectable.Method(
            doc = @ScriptInjectable.Doc("Salário do funcionário"),
            ret = @ScriptInjectable.Return(
                    doc = @ScriptInjectable.Doc("O salário do funcionário")))
    public BigDecimal getSalario() {
        return salario;
    }

    @ScriptInjectable.Method(
            doc = @ScriptInjectable.Doc("Data de admissão do funcionário"),
            ret = @ScriptInjectable.Return(
                    doc = @ScriptInjectable.Doc("A data de admissão do funcionário")))
    public Date getDataAdmissao() {
        return dataAdmissao;
    }

}

@ScriptInjectable
public class VariaveisScriptFolha {
    
    // outros atributos
    
    @ScriptInjectable.Class(name = "RepositorioFuncionarios", doc = @ScriptInjectable.Doc("Classe de funções para consulta e manipulação de funcionários"))
    private RepositorioFuncionario repositorioFuncionario;

}

Obtendo dados de um script

Em alguns casos iremos precisar obter o retorno de um script ou o valor de alguma variável específica. A engine fornece métodos para a obtenção de variáveis registradas dentro da engine ou ainda para recuperar os dados de retorno de um script.

Observe o script abaixo cujo o id é 30.

idadeFuncionario = 60
dataCalculo = Datas.hoje()

valor = valorSalarioHora * 8 * 22
nomeFuncionario = 'Robert Plant'

retornar salario:valor, nome: nomeFuncionario

No exemplo acima estamos utilizando a variável injetada valorSalarioHora para fazermos um suposto calculo salarial. Criamos a variável nomeFuncionario, e atribuímos o nome para o funcionário e utilizamos o comando retornar para submetermos estes dados como valor de retorno para o script, atribuindo uma chave para cada valor. Estes valores serão resgatados através de uma java.util.Map como veremos abaixo.

ScriptEngineContext engineContext = ScriptManager.createContext();

engineContext.setVariable("valorSalarioHora", 66.35);
Result result = engineContext.run("30");

Map returnData = result.getValue();

Number salario = (Number)returnData.get("salario");
String nomeFuncionario = (String)returnData.get("nome");

Todo script executado gera um retorno. Este tipo de retorno precisa ser previamente reconhecido pelo executor do script, pois será necessário fazer um cast para obtermos o valor de retorno. Para o exemplo acima, o retorno é obtido através de um mapa, através das chaves previamente reconhecidas, obtemos os valores requeridos.

Podemos resgatar os valores das variáveis de outra forma. Para o script executado acima, existem duas outras variáveis declaradas que não foram submetidas ao comando retornar, poderíamos passar elas normalmente para o comando, assim como fizemos com as variáveis salario e nome, ou podemos recuperar seus valores conforme veremos abaixo:

ScriptEngineContext engineContext = ScriptManager.createContext();

engineContext.setVariable("valorSalarioHora", 66.35);
Result result = engineContext.run("30");

int idade = result.getVariable("idadeFuncionario");
Date dataCalculo = result.getVariable("dataCalculo");

A classe Result fornece um método para obtermos as variáveis usadas dentro do script. Através do método getVariable, podemos resgatar qualquer variável registrada no script, inclusive aquelas que submetemos ao comando retornar. Devido ao uso de generics no retorno do método getVariable, não precisamos fazer o cast para o tipo requerido, pois o cast é feito implicitamente.

Stack Dubai

Configuração front-end

Configuração back-end

A engine de execução

Foi estudado a viabilidade de se implementar uma engine de execução para o bfc-script, porém, foi constatado que existem diversas engines disponíveis para JVM, algumas amplamente utilizadas pela comunidade. Após uma primeira avaliação, foram elencadas 3 engines para testes: Jruby (Ruby), Rhino (Java Script) e Groovy (Mix Java/Ruby).

Os principais requisitos para a seleção de uma engine eram: tipagem dinamica, boa performance, favorecer a criação de DSLs. A engine do groovy foi a que melhor preencheu estes requisitos, se tornando a engine de execução do bfc-script.

Registro de engines

Várias engines podem ser registradas em um mesmo ambiente de execução. Isso poderá ser útil caso seja necessário criar engines que resgatam scripts de lugares específicos, ou que ainda precisem restringir ou liberar recursos específicos. As engines são registradas através do mecanismo de service/lookup do java. O ScriptManager faz lookup das engines registradas no classpath, através de uma identificação atribuida à engine no momento em que esta é registrada, constituida por um nome e um Environment (PRODUCTION ou DEVELOPMENT). Portanto podemos ter duas engines com o mesmo nome mas para ambientes diferentes. O Environment possibilita que as engines implementem caracteristicas desejáveis para os ambientes distintos, sendo estas caracteristicas perceptiveis na compilação e execução do scripts.

Para maioria dos casos de uso não será necessário criar uma engine e sim utilizar a engine engine padrão.

Engine padrão

A engine de execução padrão foi desenvolvida para dar suporte às necessidades de praticamente todas as aplicações da Betha. A engine permite que pacotes de funções utilitárias sejam plugados, personalizando o box de funções utilitárias da engine para um caso de uso desejado.

A engine padrão, possui um conjunto de funções utilitárias para manipulação de datas, caracteres, números, e também instruções de iteração e condicionais, que definem a linguagem e utilitários da engine.