Interpretador de scripts - Manual preliminar

1. Descrição geral

O programa scripvox é um interpretador de linguagem de comandos
que permite um controle de execução de sequencias de ações controladas
por um programa.  Poderiamos pensar que é um equivalente dos antigos
comandos .BAT do MSDOS, mas com um poder tremendamente aumentado,
e adequado ao processamento no Windows.

As ações que podem ser executadas foram talhadas para possibilitar
a criação de interfaces sonoras para deficientes visuais.  A linguagem
e' facílima de ser aprendida, mas tem muitas facilidades que tornam
muito poderosa essa ferramenta.

A linguagem foi criada para ser absolutamente simples de ser
programada, quando o problema é simples.  Desta forma, se acredita
que um se crie um número grande de "programadores curiosos", gente
que não teria a paciência para aprender uma linguagem convencional
de computação ao ponto de criar alguma coisa útil.

A linguagem pode ser pensada também como "a primeira linguagem" do
aprendiz de programação, possibilitando que com um conhecimento
muito rudimentar de programação, um estudante crie programas de
interface que atuem sobre outros programas, possibilitando resultados
muito interessantes e criativos.

Nota:

É importante que se ressalte que um script tem escôpo de funcionamento
com lógica muito mais simples do que um programa convencional, escrito
em Pascal ou outra linguagem qualquer.  Assim, a linguagem não possui
comandos poderosos de controle, as variaveis são todas do mesmo tipo
(cadeias de caracteres) e o tratamento de rotinas não permite o uso
de parâmetros.  Da mesma forma, o tratamento aritmético é rudimentar.
Entretanto, um programa que em Pascal poderia consumir 500 linhas
ou mais pode ser escrito provavelmente em menos de 100 num script.

2. Funcionamento geral

Um script de comandos é um arquivo de texto com extensão .CMD.
Para ativa-lo no Winvox existem duas opções:

a. Localizar o arquivo .CMD desejado com a opção de arquivos e executar
   este arquivo com a opção x

ou então

b. Ativar o utilitário scripvox (opção U S) e informar o nome completo do
   arquivo .CMD de script

Nota sobre a instalação:

Deve-se assegurar que o arquivo \windows\dosvox.ini contenha as seguintes
linhas

[DOSVOX]
PROG.CMD=c:\winvox\scripvox.exe

[PROGUTIL]
Util16=S,c:\winvox\scripvox.exe,-DVUTSCRI,Executor de script de comandos

3. Estrutura de programação

a) Formato do programa

O programa é um texto comum.
Os comandos podem vir em maiúsculos ou minúsculos, com ou sem acentos.
As linhas podem ter até 256 letras.
Linhas em branco são ignoradas
Uma linha começada por asterisco é também ignorada (comentários)
Os brancos ao início da linha são desprezados, possibilitando a
utilização de endentação nos programas.

b) Funcionamento

As instruções do programa são executadas sequencialmente, linha
após linha.  As únicas exceções são os comandos que promovem
explicitamente um desvio no fluxo normal de execução, a saber:
desvia, se, chama e retorna.   Veremos o funcionamento destes
comandos mais adiante.

O programa permite o registro de informações nas chamadas "variaveis",
que são identificadas por uma única letra, de A até Z.  Assim, um
programa pode conter no máximo 26 variáveis.

As variáveis podem conter cadeias de caracteres de até 255 letras.
Números são tratados internamente como se fossem cadeias de caracteres
(ligeiramente particularizadas).

4. Um primeiro exemplo

Para que se tenha uma breve idéia da cara de um programa
vejamos o trecho abaixo.

* Meu primeiro programa
escreve "Oi amigo, qual seu nome?"
le n
escreve "Muito prazer, "&
escreve n
escreve "Realmente não é nada difícil programar"

A primeira linha é um comentário, e é ignorada pelo interpretador.
Em seguida a frase
Oi amigo, qual o seu nome ?
é mostrada numa janela e sintetizada em voz.
A seguir o usuário deve teclar uma resposta apertando depois Enter.
Este resposta será armazenada na variável n
A máquina vai então falar
Muito prazer,
(o indicador & diz que não se deve pular linha após essa escrita)
colocar ao lado o que foi teclado pelo usuário, armazenado internamente
na variável n, pular de linha (pois este comando escreve não possui uma
letra & ao final) e finalmente escrever
Realmente não é nada difícil programar

Antes de prosseguir digite este texto, e o execute.

5. Desvios

É possível inserir no texto do programa linhas começando pela
letra @, seguidas (sem espaço em branco) por uma palavra.
Essas linhas são chamadas de "rótulos" e servem para que se
possa desviar a execução para uma delas.

O trecho a seguir ilustra um desvio

escreve "Digite uma palavra e eu repetirei"
escreve "Termine com a palavra FIM"

@outraPalavra
    le t
    escreve t
    se t = "FIM" desvia @fim
    desvia @outraPalavra

@fim
escreve "Tchau"

Notas sobre estilo:
É comum inserir-se uma linha em branco antes de um rótulo
para aumentar a legibilidade do programa.
Quando os comandos de desvio provocam uma repetição de
um trecho é usual que ele seja destacado através da inserção
de alguns espaços em branco em todas as linhas (indentação).

6. Comandos

Na descrição simplificada abaixo, o uso de chaves indica
um item adicional e o de colchetes, um item obrigatório.

6.1 Interações com o usuário

a)  escreve {MUDO} ["frase" ou variavel]

Escreve um texto, sintetizando simultaneamente.  Se a palavra
MUDO estiver contida, ele não é sintetizado, apenas escrito.
Quando o comando é terminado por &, nao pula linha.

exemplos:
    escreve "Oi"
    escreve "Eu me chamo " &
    escreve "Antonio Borges"
    seja a "Nasci em 1956"
    escreve a

b) le [variavel]

Obtém do teclado uma cadeia de caracteres para uma variavel.
Quando o comando é terminado por &, apenas uma letra é lida.

exemplos:
    le a
    le c&

c) tela [LIMPA ou MINIMIZADA ou NORMAL ou @x,y]

Controla a aparência da janela ou reposiciona o cursor nela.
A opções Minimizada serve para tirar a janela do script da
área visível, dando, provavelmente a vez para uma outra janela
que esteja abaixo dela.  A opção Normal traz para a atividade
uma janela de script que esteja minimizada ou escondida atrás
de outra.

Exemplos:
    tela LIMPA
    tela @10,10
    escreve "oi"
d) bipa {tipoBip}

Soa um bip ou clek.
Se o tipo do bip for omitido será emitido um bip.
Caso contrário, 0 = bip  1 = clek

e) cor [valor ou variavel]
   fundo [valor ou variavel]

Cores válidas:
  Preto          = 0
  Azul           = 1
  Verde          = 2
  Ciano (Azul)   = 3
  Vermelho       = 4
  Magenta        = 5
  Marrom         = 6
  Branco fosco   = 7
  Cinza escuro   = 8
  Azul claro     = 9
  Verde claro    = 10
  Ciano claro    = 11
  Vermelho claro = 12
  Magenta Claro  = 13
  Amarelo        = 14
  Branco         = 15

Escreve com a cor ou o fundo de letra dados, a partir deste momento.
Para desenhar usando uma janela colorida, use o comando fundo
seguido do comando tela limpa.

Exemplos:
    COR 4
    ESCREVE "Estou escrevendo este texto em vermelho"
    Fundo 9
    ESCREVE "Vermelho em fundo azul claro"
    FUNDO 0
    COR 7
    TELA LIMPA

f) observa TECLADO [variavel]

A variável selecionada recebe um dos seguintes valores
    0: não foi teclado nada
    1: teclado requer leitura, foi teclado algo

Exemplo:

@maisUmBip
    bipa 1
    observa TECLADO x
    se x = 0 desvia @maisUmBip
le a &

O exemplo acima fica repatidamente clekando até que o usuário aperte
uma tecla.

g) espera [tempoEmSegundos]

O script é paralisado durante o número de segundos especificado.

Exemplo:
    bipa
    espera 2
    bipa

O exemplo acima realiza dois bips separados por dois segundos de intervalo.


6.2 Ações de multimídia

a) toca ["nomeArquivo" ou variável]

Este comando permite a execução de um arquivo multimídia (MIDI, WAV, etc),
que possa ser processado pelo Windows.

Se este comando for terminado por &, o script prossegue,
não esperando a execução da mídia terminar.

exemplo:
    toca "c:\windows\tada.wav"

b) mci [variavelRetorno] ["frase" ou variável]

Permite a execução de um comando do MCI - Media Control Interface,
permitindo o controle completo dos dispositivos multimidia, como
CD-ROM, exibição de filmes, sons, animações, etc...
Veja manual de programação do Windows para uma relação completa de
comandos MCI.

exemplo:
    mci "PLAY CDAUDIO"

6.3 Operações com arquivo

Os comandos a seguir trabalham com arquivos.  Para processamento,
um arquivo deve ser aberto, e associado a um número de 0 a 9, que
é referenciado durante a leitura ou escrita.

a) abre #n ["nomeArquivo" ou variavel]

Associa um número n a um arquivo
Terminando este comando com &, o arquivo é criado
(acrescentado se já existir)

exemplo:
    abre #1 "c:\winvox\treino\china.txt"
    abre #1 "novo.txt" &

b)fecha #n

Libera o sistema Windows do controle do arquivo previamente aberto.
O arquivo pode ser também uma conexão de Internet, como veremos
mais adiante.

exemplo:
    fecha #1

c) le #n [variavel]

Le uma linha completa do arquivo, se ela existir.
Deve-se sempre verificar se essa operação foi bem sucedida (por exemplo,
se não se chegou ao fim do arquivo) utilizando-se depois o comando checa.

exemplo
    le #1 x
    checa s
    se s <> 0 desvia @houveErroOuAcabouArquivo

d) checa [variavel]

Verifica o resultado da última operacao le ou escreve.
A variável selecionada recebe um código para indicar o que houve.
  0: não houve problemas
  <> 0: indica um erro ou fim de arquivo

exemplo: veja comando le

e) escreve #n ["valor" ou variavel]

Escreve uma linha no arquivo.
Terminado por & nao pula linha.

exemplo:
    escreve #1 "Antonio " &
    escreve #1 "Borges"

f) remove ["nomeArquivo" ou variavel]

Remove um arquivo.  Se este comando for terminado por &
e houver um problema na remoção (por exemplo, se o arquivo
não existir ou estiver protegido contra escrita, não acusa erro.

exemplo:
    remove "x.txt"

g) renomeia ["nomeArquivo" ou variavel] ["novoNome" ou variavel]

Troca o nome de um arquivo por outro
Se este comando for terminado por &, não acusa erro de execução
se não puder renomear o arquivo.

exemplos:
    renomeia "a.txt" "novo.txt"
    seja c "c.txt"
    seja d "d.txt"
    renomeia c d


--------

Esta parte do manual ainda não foi completada

6.4 Operações com diretórios

a) busca [variavel] {DIR} [["nomeArqs" ou variável] ou PRÓXIMO]

Se omitido nome ou PRÓXIMO devolve diretório atual

b)  dir {CRIA, REMOVE} ["nomeDiretorio" ou variavel]  {terminado por & não dá erro


6.5 Operações com Internet

a) internet [INICIA, TERMINA]

Este comando é obrigatório para estabelecer ou terminar a comunicação
via Internet.

b) conecta #n ["valor" ou variavel] ["porta" ou variavel]

Conecta uma porta remota, associando-a a um arquivo.
Posteriormente, pode-se tratar a conexão exatamente como se
fosse um arquivo comum.

c) serve #n ["porta" ou variavel]

d) observa #n [variavel]
   0: porta TCP/IP não requer atenção
   1: porta requer leitura

   Nota: quando ocorre uma desconexão remota, existe a indicação de
   que a porta requer leitura.  Assim deve-se utilizar o comando
   checa para verificar se houve um fechamento do arquivo.


6.6 Processamento de variáveis

a) seja [variavelDestino] {funcaoOpcional} [valor ou variavel]

    Atribui um valor a uma variável.
    Pode-se opcionalmente usar neste comando uma das seguintes funções,
que atuam como modificadores da valor ou variável

        TAMANHO     indica que ao invés da variável (ou valor) deve-se usar
                    o número de letras dela
        MAIUSC      indica que antes de realizar a operação deve-se trocar
                    o valor ou variável para maiúsculas
        TRIM        indica que antes de realizar a operação deve-se remover
                    os brancos ao início e fim do valor ou variável
        POS [subcadeia]   calcula a posição de uma subcadeia na variavel

b) soma [variavelDest] [valor ou variavel]
    o valor pode ser negativo

c) concatena [variavelDest] [valor ou variavel]
    Adiciona à direita da variavel destino algumas outras letras.

d) copia [variavelDest] [variavel] [caracinicio] [caracfim]
    Traz para a variável destino um pedaço de uma outra variável

e) transfere [DE, PARA] [variavel]
    Move o conteúdo textual de uma linha da área de transferência DE
    ou PARA uma variável

f) substitui [variavel] [valor antigo] [valor novo]
    Troca todas as ocorrências de uma cadeia por outra numa variável

6.7 Processamento de desvios

a) executa ["programa" ou variavel]

   Executa um programa comum.
   Quando o comando é terminado por &, o script prossegue em paralelo
com a execução do programa, caso contrário, o script espera que
o programa conclua sua execução para prosseguir.

b) desvia [@rotulo]

   Desvia a execução para um ponto qualquer indicado pelo @rotulo

c) chama [@rotulo]

   Desvia a execução para um ponto qualquer indicado pelo @rotulo.
Algum momento após esta operação, entretanto, pode-se executar o
comando retorna para voltar a execução uma linha abaixo desta do
comando chama.

É o conceito convencional de chamada de subrotina.
É possível executar-se diversos comando chama,
desde que depois se executem diversos comandos retorna.

d) retorna

A execução deste comando provoca o desvio para depois do último
comando chama "empilhado".

e) se {NÃO} [variavel] [comparador] ["valor" ou variavel] comando

Este comando permite a execução condicional de comando qualquer,
baseado numa comparação de uma variável com outra (ou com um valor).
A comparação pode ser feita utilizando os seguintes comparadores:

=   igual (exceto possívelmente por maiúsculas)
==  igual inclusive nas maiúsculas
<>  diferente
<   menor
>   maior
<=  menor ou igual
>=  maior ou igual

*=* existe como subcadeia em
=*  é começada por
*=  é terminada por

f) cmd [variavel]

Este comando permite que uma variável seja montada (possivelmente
através de operações de concatenação) e depois interpretada como
se fosse um comando.


g) termina [MUDO]
    Termina a execução do script


h) debug {+ ou -}

Liga ou desliga o modo debug, no qual cada comando executado é falado.
Esse comando é útil durante a verificação de possíveis erros do script.

6.8 Operações com janelas

a) espera [tempo] ["nome janela" ou variavel]

Espera, no máximo por um certo tempo, que uma janela com título
começado por um certo nome receba atividade no Windows (venha para
cima das outras).

b) janela [FECHA, MINIMIZA, MAXIMIZA, NORMAL] ["nome janela" ou variavel]

Fecha, minimiza, maximiza ou traz para o topo das outras uma certa
janela.

c) captura [TÍTULO ou ATIVA, CAMPO, FOCO] [variavel]

Captura para uma variável ou título da janela ativa, o campo ativo
ou o elemento que está com o foco do Windows.

6.9 Ações do teclado e mouse

As ações a seguir são enviadas diretamente para a janela ativa atual do
windows, permitindo o seu uso em "controle remoto".  Esses comandos,
portanto são fundamentais para a criação de interfaces adaptativas para
programas do Windows.

a) digita "frase" [enter]

Envia uma sequencia de teclagens para o programa ativo.

b) aciona [tecla virtual]

Envia uma tecla virtual para o programa ativo.
São as seguintes as teclas virtuais mais importantes:

UP, DOWN, LEFT, RIGHT
ESCAPE ou ESC
ENTER e RETURN
TAB
F1 até F12
INS, DEL ou DELETE
HOME, END
PAGEUP, PAGEDN
PRIOR, NEXT    -> sinonimos de pageup e pagedn
SNAPSHOT       -> printScreen

As teclas a seguir são usadas em conjunto com outras, por exemplo
ALT+A, CONTROL+F1

CTRL+
SHIFT+
ALT+

c) clica {DUPLO} [x,y ou TELA x,y]

Executa um clique ou clique duplo de mouse numa posição.
O uso da palavra TELA indica que é uma coordenada absoluta de tela.
Se ela for omitida a coordenada é calculada em função da janela
atualmente ativa no Windows.
