Funções

Uma função é um bloco de código reutilizável que desempenha determinada tarefa. Sempre que precisar da tarefa, você pode usar a função no seu script. Isto economiza tempo e esforço necessários para adicionar código àquela tarefa no seu script toda vez que precisar dela. Isso também mantém os seus scripts mais organizados e menos poluídos ao reduzir a quantidade de código neles.

Funções podem:

• Tomar dados do script, manipulá-los de certa forma e retornar os resultados de volta ao script.
• Executar uma ação ou uma série de ações e passar os dados resultantes ao script.

Algumas funções são internas ao Studio para uso nos seus scripts. Não é preciso adicionar nada ao seu script para usar uma função interna. Quando quiser usar uma, você pode simplesmente chamá-la.

Você também pode criar as suas próprias funções personalizadas para usar em um script. Isso é útil quando você tem um código que usa frequentemente no seu script. Em vez de adicioná-lo ao script toda vez que precisa dele, você pode criar uma função que contém o código. E, então, quando precisar do código, você pode chamar a função.

Sintaxe

Nomes de função tem um conjunto de parênteses abertos e fechados ao fim delas: functionName().

Todo texto dentro dos parênteses vira parâmetro, o que define os dados que são passados entre a função e o script: functionName(param1,param2).

Para criar uma função personalizada, use esta sintaxe:

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

Nesta sintaxe:

• FUNCTION é palavra-chave obrigatória que inicia todas as instruções de função personalizada.
• <name> é o nome da função.
• ([<parameter>] [...]) define quaisquer parâmetros que a função requer.
• { ... } contém o código da função.
• [RETURN <data>] é a instrução a ser incluída para passar dados da função para o script principal.

Você pode nomear as suas funções personalizadas como quiser, desde que siga as seguintes diretrizes:

• Use caracteres alfanuméricos (a-z, A-Z, 0-9).

• O primeiro caractere do nome deve ser uma letra.
• Use o caractere de sublinhado ( _ ) e o sinal de cifrão ( $ ) em qualquer lugar do nome.
• Não use palavras reservadas ou os nomes de funções internas.

A sintaxe para uma instrução RETURN é:

RETURN ou RETURN <var>

Ao chamar uma função, use uma das seguintes sintaxes:

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Parâmetros e argumentos

Muitas funções precisam usar dados do script. Você pode fazer isso usando parâmetros e argumentos.

Parâmetros são definidos quando uma função é criada. Um parâmetro é um nome de variável que aparece nos parênteses que seguem o nome da função. Uma função pode ter mais de um parâmetro. Cada parâmetro é separado por uma vírgula. Você pode incluir um espaço se quiser, mas isso não é necessário. Por exemplo, a função logn(value, base) tem dois parâmetros, value e base.

Os dados específicos que o script passa à função pelos parâmetros são chamados de argumentos. O exemplo a seguir mostra o uso da função interna abs(value) em um script. Neste exemplo, -42 é o argumento que é passado ao parâmetro value.

ASSIGN abVal = abs(-42)

No Studio, todos os parâmetros são obrigatórios. Se uma função é definida com um parâmetro, você deve passar um valor quando chama a função. O número de argumentos passados à função deve corresponder ao número de parâmetros definidos.

O script não verifica para garantir que os argumentos estão no tipo ou formato correto. No entanto, se o argumento não é do tipo ou formato que a função espera, a função pode não ser concluída com sucesso ou os resultados podem não ser corretos.

Se muitos ou muito poucos argumentos forem passados à função, ocorrerá um erro de compilação quando você executar o script. Isso pode acontecer com funções internas e funções personalizadas.

Formatação de argumentos

Ao chamar uma função que exige parâmetros, você deve incluir os argumentos que está passando à função. Siga essas diretrizes para formatar os argumentos:

• Se o argumento for numérico ou uma variável, não é preciso colocá-lo dentro de aspas simples ou duplas.
• Se o argumento for uma variável, não é preciso colocá-lo dentro de chaves.
• Se o argumento for alfanumérico e não for uma variável, coloque-o dentro de aspas simples ou duplas.

Por exemplo, a função dateadd() requer três parâmetros, unit, date e value.

Unit define a parte da data que você quer que a função altere, como o ano ou o mês. Date é a data original que deseja modificar. E value é em quanto você quer que a função aumente a unidade especificada da data original. O exemplo a seguir mostra como cada parte é formatada:

ASSIGN NewDateYearNumeric = dateadd('year', MyDateTime, 1)

O unit é uma string alfanumérica, então é formatada com aspas simples. O date neste exemplo é uma variável, portanto não possui aspas. Caso tenha passado uma string de data, ela precisará de aspas. O value não é formatado porque é numérico.

Instruções RETURN

Uma instrução RETURN encerra uma função e devolve o controle ao script. Ela também pode passar dados de volta ao script.

Instruções RETURN só podem passar dados ao script como um valor de variável ou uma matriz. Elas não podem passar vários valores, a não ser que tais valores sejam parte de uma matriz ou objeto. Elas não podem passar objetos, a não ser que os objetos sejam primeiro convertidos para JSON. Se necessário, você pode convertê-la de volta para um objetot no script.

A sintaxe para uma instrução RETURN é:

RETURN ou RETURN <var>

Todas as funções internas que retornam um valor ao script contêm uma instrução RETURN. Em funções personalizadas que você cria, instruções RETURN são opcionais. Se não houver uma instrução RETURN, a função não poderá passar nenhum valor de volta ao script. A única forma de usar uma função que não tem uma instrução RETURN é chamá-la como uma instrução.

Se incluir uma instrução RETURN em uma função, ela deve estar na última linha da função.

Visibilidade Variável

O comportamento padrão é que todos os valores na função estão disponíveis e são para uso somente dentro da função. Quando a função termina, todos os valores na função são perdidos. Se a função contiver uma instrução RETURN que passa um valor de variável de volta ao script, apenas os valores passados pela instrução RETURN estarão disponíveis fora da função.

Se incluir variáveis em uma função personalizada que existe no script principal, essas variáveis terão escopo global. Isso significa que esses valores estarão disponíveis fora da função sem usar uma instrução RETURN. Da mesma forma, se declarar uma variável dentro da função como global, seu valor estará disponível no script principal. Isso é parecido com o comportamento visto em subscripts.

Quando você usa uma função em uma expressão ou como o valor de uma variável, ela segue o comportamento padrão. No entanto, se chamar uma função como uma instrução, todos os valores na função terão escopo global e estarão disponíveis para uso fora da função. Para funções sem uma RETURN, esta é a única forma em que podem ser usadas.

Criar funções personalizadas

Você pode criar funções personalizadas quando tiver código que gostaria de usar em vários lugares no seu script. Uma função personalizada só fica disponível dentro do script onde ela é criada. Se quiser usar uma função personalizada em um script diferente, você deve copiar o código de definição da função naquele script.

Você pode criar uma função em uma ação Snippet em seu script e depois chamá-la a partir de outras ações Snippet no mesmo script. Se você depurar o snippet contendo a definição da função, ela estará incluída na depuração. No entanto, a função não será incluída quando você depurar os outros snippets.

A sintaxe para declarar uma função personalizada é:

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

FUNCTION é a palavra-chave que permite ao script saber que o que segue é uma função personalizada. Nomes de função devem seguir as mesmas diretrizes de nomeação de outras entidades nos scripts:

• Use caracteres alfanuméricos (a-z, A-Z, 0-9).

• O primeiro caractere do nome deve ser uma letra.
• Use o caractere de sublinhado ( _ ) e o sinal de cifrão ( $ ) em qualquer lugar do nome.
• Não use palavras reservadas ou os nomes de funções internas.

Se a função exigir parâmetros, coloque-os entre os parênteses ao fim do nome da função. Se não houver parâmetros, os parênteses podem ser deixados em branco. Separe vários parâmetros com vírgulas.

O código que compõe a função fica entre as chaves. O local de colocação das chaves é flexível. Elas podem ficar na mesma linha do nome e da palavra-chave FUNCTION ou podem ficar em linhas separadas. Por exemplo, ambas as definições de função a seguir são válidas:

FUNCTION myFunction() { ASSIGN var = "value" } 

FUNCTION myFunction() 
{ 
	ASSIGN var = "value"
}

Se a função incluir uma instrução RETURN, ela deve ser a última instrução na função antes da chave de fechamento.

função não precisa de uma string, de aspas, mas assume variável se nenhuma aspa e nenhum número ou booleano

Você pode saber mais sobre a criação de funções na página Instruções de declaração.

Ajuda com auto-preenchimento para funções personalizadas

Você pode adicionar ajuda com auto-preenchimento para suas funções personalizadas. Esse é um texto de dica de ferramenta que aparece quando você começa a digitar o nome da função na janela Snippet editor. Esta ajuda aparece apenas ao se chamar a função com notação de ponto.

Ver imagem

Você pode usar essas dicas de ferramentas para fornecer informações sobre as funções. Por exemplo, você pode usá-las para definir os parâmetros da função.

Para adicionar a ajuda com auto-preenchimento, adicione um comentário na mesma linha da instrução da função. Por exemplo, para criar a dica de ferramenta mostrada na imagem anterior, a sua instrução de função deveria aparecer assim:

FUNCTION MyAppend(a,b) // My function to append the text
{
   RETURN "{a}{b}"
}	

Se adicionar ajuda com auto-preenchimento a uma função, as chaves contendo o código da função devem ser colocadas em uma linha separada da definição da função. O script considera todo texto depois das duas barras para frente como sendo parte de um comentário. Se as chaves estiverem na mesma linha, o script as incluirá no comentário.

Chamar funções em um script

Quando quiser usar uma função no seu script, você deve chamá-la. Há três maneiras de se chamar uma função. Nem todas as opções funcionam para todas as funções. As opções disponíveis para uma determinada função dependem se a função retorna um valor ou não. Você pode chamar uma função:

• Sozinha como uma instrução. Esta opção funciona com todas as funções.
• Em um lugar onde usaria uma variável ou expressão. Esta opção funciona somente com funções que retornam um valor.
• Com uma variável usando notação de ponto. Esta opção funciona somente com funções que retornam um valor.

Chamar uma função como uma instrução

Uma instrução é uma linha de código com uma palavra-chave de comando que diz ao script o que fazer. Você pode usar uma função como uma instrução. Ao fazê-lo, não é preciso uma palavra-chave de comando especial, como com outras declarações em um snippet. O código na função diz ao script o que fazer.

Você pode chamar qualquer função como uma instrução. Se uma função não contiver uma instrução RETURN, esta é a única forma de chamá-la. Isso é porque uma instrução RETURN passa dados da função de volta ao script. Quando não houver uma RETURN, ser chamada como uma instrução será a única forma que o script terá acesso aos dados na função.

A sintaxe para chamar funções como uma instrução é:

<functionName><([parameter], [parameter], [...])>

O exemplo a seguir mostra a função append() sendo chamada como uma instrução:

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

Use uma função no lugar de uma variável

Quando uma função retorna um valor, você pode usá-las em qualquer lugar onde usaria uma variável ou expressão. O script pode usar o valor que a função retorna como usaria o valor de uma variável ou o resultado da expressão.

As sintaxes para usar uma função no lugar de uma variável são:

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

FUNCTION replaceCharacters(string)
{
	ASSIGN adjustedString = string.replace("&", "and")
	RETURN adjustedString
}			

ASSIGN testString = "dogs & cats"
ASSIGN stringRes = "My favorite animals are {replaceCharacters(testString)}."

FUNCTION MyAppend(a,b)
{
   RETURN "{a}{b}"
}	

FOR i=1 TO 9
{
   ph = "{ph.MyAppend(i)}"
}