Passar argumentos de texto - Internet Computer

Este tutorial fornece uma variação simples do programa padrão que permite passar um único argumento de texto para um único ator, compilar o código para criar um cânister e recuperar o argumento. Ao longo deste documento, os termos cânister e cânister são considerados sinônimos.

Este tutorial ilustra como passar argumentos na linha de comando em um terminal usando a linguagem de descrição de interface Candid (IDL) e como modificar o programa para permitir que ele aceite mais de um valor para o argumento de texto.

Antes de começar

Antes de iniciar este tutorial, verifique o seguinte:

• Você baixou e instalou o pacote SDK conforme descrito em Download e install.
• Você parou todos os ambientes de execução do cânister no computador local.

Este tutorial leva aproximadamente 20 minutos para ser lido na integra.

Criar um novo projeto

Para criar um novo projeto para este tutorial:

• Abra um shell de terminal em seu computador local, se você ainda não tiver um aberto.
• Mude para a pasta que você está usando para seus projetos da Internet Computer, se estiver usando uma.
• Crie um novo projeto executando o seguinte comando:

dfx new location_hello

• Mude para o diretório do seu projeto executando o seguinte comando:

cd location_hello

Modificar a configuração padrão

No tutorial Explorar o projeto padrão, você viu que criar um novo projeto adiciona um arquivo de configuração padrãodfx.json ao diretório do projeto. Você deve sempre revisar as configurações padrão no arquivo para verificar se as informações refletem com precisão as configurações do projeto que deseja usar. Para este tutorial, você modificará a configuração padrão para remover as configurações que não são usadas.

Para modificar as configurações no arquivo de configuração dfx.json :

1. Abra o arquivo de configuração dfx.json em um editor de texto.
2. Verifique as configurações padrão para o projeto location_hello.
3. Remova todas as definições de configuração desnecessárias. Como este tutorial não envolve a criação de ativos de front-end, você pode remover todas as definições de configuração do arquivo location_hello_assets.
4. Salve suas alterações e feche o arquivo para continuar.

Modificar o programa padrão

No tutorial Explorar o projeto padrão, você viu que criar um novo projeto gera um diretório src padrão com um arquivo de modelo main.mo.

Para modificar o código-fonte do modelo padrão:

• Abra o arquivo de código-fonte src/location_hello/main.mo em um editor de texto.
• Modifique o código-fonte padrão para substituir a função greet por uma função location e o argumento name por um argumento city.

Por exemplo assim.

• Salve suas alterações e feche o arquivo para continuar.

Inicie o ambiente de execução do cânister local

Antes de construir seu projeto, você precisa se conectar a um ambiente de execução do cânister local ou à rede principal da blockchain Internet Computer.

Iniciar um ambiente de execução do cânister localmente requer um arquivo dfx.json, portanto, você deve ter certeza de que está no diretório raiz do seu projeto. Para este tutorial, você deve ter dois shells de terminal separados, para poder iniciar e ver as operações de rede em um terminal e gerenciar seu projeto em outro.

Para iniciar o ambiente de execução do cânister local:

• Abra uma nova janela de terminal ou guia em seu computador local.

• Navegue até o diretório raiz do seu projeto, se necessário.

• Agora você deve ter dois terminais abertos.

• Você deve ter o diretório do projeto como seu diretório de trabalho atual.

• Inicie o ambiente de execução do cânister em seu computador local executando o seguinte comando:

dfx start

Se você for solicitado a permitir ou negar conexões de rede de entrada, clique em Allow.

• Deixe o terminal que exibe as operações de rede aberto e mude seu foco para o terminal original onde você criou seu projeto.

Registre, construa e implante o dapp

Depois de se conectar ao ambiente de execução do cânister local, você pode registrar, construir e implementar seu dapp localmente.

Para implantar o dapp localmente:

1. Verifique se você ainda está no diretório raiz do seu projeto, se necessário.
2. Registre, construa e implante seu aplicativo executando o seguinte comando:

dfx deploy

A saída do comando dfx deploy exibe informações sobre as operações que ele executa.

Passar um argumento de texto

Agora você tem um programa implantado como um cânister em seu ambiente de execução do cânister local e pode testar seu programa usando comandos dfx canister call.

Para testar o programa que você implantou localmente:

• Chame o método location no programa e passe seu argumento cityde tipo text executando o seguinte comando:

dfx canister call location_hello location "San Francisco"

Como o argumento neste caso inclui um espaço entre San e Francisco, você precisa colocar o argumento entre aspas. O comando exibe uma saída semelhante à seguinte:

("Hello, San Francisco!")

Se o argumento não contivesse um espaço que exigisse colocar o texto entre aspas, você poderia permitir que a linguagem de descrição da interface Candid inferisse o tipo de dados assim:

dfx canister call location_hello location Paris

A Candid infere o tipo de dados como Text e retorna a saída do seu programa como um texto como este:

("Hello, Paris!")

• Chame o método location no programa e passe seu argumento city explicitamente usando a sintaxe da linguagem de descrição da interface Candid para argumentos de texto:

dfx canister call location_hello location '("San Francisco and Paris")

O comando exibe uma saída semelhante à seguinte:

("Hello, San Francisco and Paris!")

Como seu programa aceita apenas um único argumento de texto, especificar várias strings retorna apenas o primeiro argumento.

Por exemplo, se você tentar este comando:

dfx canister call location_hello location '("San Francisco","Paris","Rome")

Apenas o primeiro argumento ("Hello, San Francisco!") é retornado.

Revise o código-fonte em seu programa

Para estender o que você aprendeu neste tutorial, você pode tentar modificar o código-fonte para retornar resultados diferentes. Por exemplo, você pode querer modificar a função location para retornar vários nomes de cidades.

Para experimentar a modificação do código-fonte deste tutorial:

• Abra o arquivo de configuração dfx.json em um editor de texto e altere as configurações padrão location_hello para favorite_cities.

Para esta etapa, você deve modificar tanto o nome do cânister como o caminho para o programa principal para que o cânister utilize favorite_cities.

• Salve suas alterações e feche o arquivo dfx.json para continuar.

• Copie o diretório do arquivo de origem location_hello para corresponder ao nome especificado no arquivo de configuração dfx.jsonexecutando o seguinte comando:

cp -r src/location_hello src/favorite_cities

• Abra o arquivo src/favorite_cities/main.mo em um editor de texto.

• Copie e cole o exemplo de código a seguir para substituir a função location por duas novas funções.

Por exemplo assim.

Você pode notar que Text neste exemplo de código está entre colchetes [ ]. Por si só, Text representa uma coleção de caracteres UTF-8. Os colchetes em torno de um tipo indicam que é uma matriz desse tipo. Nesse contexto, portanto, [Text] indica um vetor de uma coleção de caracteres UTF-8, permitindo que o programa aceite e retorne várias strings de texto.

A amostra de código também usa o formato básico de uma operação apply para a matriz, que pode ser resumida como:

public func apply<A, B>(fs : [A -> B], xs : [A]) : [B] {
    var ys : [B] = [];
    for (f in fs.vals()) {
        ys := append<B>(ys, map<A, B>(f, xs));
    };
    ys;
};

Para obter informações sobre as funções que executam operações em vetores, consulte a descrição do módulo Vetor na biblioteca base do Motoko ou o Motoko Programming Language Reference. Para outro exemplo focado no uso de vetores, veja Quicksort no repositório de exemplos.

• Registre, crie e implante o dapp executando o seguinte comando:

dfx deploy

• Chame o método location no programa e passe seu argumento city usando a sintaxe de descrição da interface Candid executando o seguinte comando:

dfx canister call favorite_cities location '(vec {"San Francisco";"Paris";"Rome"})'

O comando usa a sintaxe de descrição da interface Candid (vec { val1; val2; val3; }) para retornar um vetor de valores. Para obter mais informações sobre a linguagem de descrição da interface do Candid, consulte o guia de linguagens do Candid.

Este comando exibe uma saída semelhante à seguinte:

("Hello, from ["San Francisco", "Paris", "Rome"]!")

• Chame o método location_pretty no programa e passe seu argumento city usando a sintaxe de descrição da interface executando o seguinte comando:

dfx canister call favorite_cities location_pretty '(vec {"San Francisco";"Paris";"Rome"})'

O comando exibe uma saída semelhante à seguinte:

("Hello from San Francisco, Paris, Rome, bon voyage!")

• Teste seu código usando a interface do usuário Candid.

Para testar seu código, siga as instruções aqui. Neste exemplo, cada função aceita uma matriz de strings de texto. Portanto, você primeiro seleciona o comprimento da matriz e, em seguida, define os valores para cada item antes de clicar em Chamar.

Pare o ambiente local de execução do cânister

Depois de terminar de experimentar seu programa, você pode parar o ambiente de execução do cânister local para que ele não continue sendo executado em segundo plano.

Para parar o ambiente de execução do cânister local:

1. No terminal que exibe as operações de rede, pressione Control-C para interromper o processo local.

2. Pare o ambiente de execução do cânister executando o seguinte comando:

dfx stop

Este artigo foi publicado no portal do desenvolvedor da Internet Computer. Tradução e adaptação por Marcelo Panegali.