Interpretador de scripts - Manual preliminar

1. Descrio geral

O programa scripvox  um interpretador de linguagem de comandos
que permite um controle de execuo de sequencias de aes 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 aes que podem ser executadas foram talhadas para possibilitar
a criao de interfaces sonoras para deficientes visuais.  A linguagem
e' faclima 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 nmero grande de "programadores curiosos", gente
que no teria a pacincia para aprender uma linguagem convencional
de computao ao ponto de criar alguma coisa til.

A linguagem pode ser pensada tambm como "a primeira linguagem" do
aprendiz de programao, possibilitando que com um conhecimento
muito rudimentar de programao, 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 escpo de funcionamento
com lgica muito mais simples do que um programa convencional, escrito
em Pascal ou outra linguagem qualquer.  Assim, a linguagem no possui
comandos poderosos de controle, as variaveis so todas do mesmo tipo
(cadeias de caracteres) e o tratamento de rotinas no permite o uso
de parmetros.  Da mesma forma, o tratamento aritmtico  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 extenso .CMD.
Para ativa-lo no Winvox existem duas opes:

a. Localizar o arquivo .CMD desejado com a opo de arquivos e executar
   este arquivo com a opo x

ou ento

b. Ativar o utilitrio scripvox (opo U S) e informar o nome completo do
   arquivo .CMD de script

Nota sobre a instalao:

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 programao

a) Formato do programa

O programa  um texto comum.
Os comandos podem vir em maisculos ou minsculos, com ou sem acentos.
As linhas podem ter at 256 letras.
Linhas em branco so ignoradas
Uma linha comeada por asterisco  tambm ignorada (comentrios)
Os brancos ao incio da linha so desprezados, possibilitando a
utilizao de endentao nos programas.

b) Funcionamento

As instrues do programa so executadas sequencialmente, linha
aps linha.  As nicas excees so os comandos que promovem
explicitamente um desvio no fluxo normal de execuo, a saber:
desvia, se, chama e retorna.   Veremos o funcionamento destes
comandos mais adiante.

O programa permite o registro de informaes nas chamadas "variaveis",
que so identificadas por uma nica letra, de A at Z.  Assim, um
programa pode conter no mximo 26 variveis.

As variveis podem conter cadeias de caracteres de at 255 letras.
Nmeros so tratados internamente como se fossem cadeias de caracteres
(ligeiramente particularizadas).

4. Um primeiro exemplo

Para que se tenha uma breve idia 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 no  nada difcil programar"

A primeira linha  um comentrio, e  ignorada pelo interpretador.
Em seguida a frase
Oi amigo, qual o seu nome ?
 mostrada numa janela e sintetizada em voz.
A seguir o usurio deve teclar uma resposta apertando depois Enter.
Este resposta ser armazenada na varivel n
A mquina vai ento falar
Muito prazer,
(o indicador & diz que no se deve pular linha aps essa escrita)
colocar ao lado o que foi teclado pelo usurio, armazenado internamente
na varivel n, pular de linha (pois este comando escreve no possui uma
letra & ao final) e finalmente escrever
Realmente no  nada difcil programar

Antes de prosseguir digite este texto, e o execute.

5. Desvios

 possvel inserir no texto do programa linhas comeando pela
letra @, seguidas (sem espao em branco) por uma palavra.
Essas linhas so chamadas de "rtulos" e servem para que se
possa desviar a execuo 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 rtulo
para aumentar a legibilidade do programa.
Quando os comandos de desvio provocam uma repetio de
um trecho  usual que ele seja destacado atravs da insero
de alguns espaos em branco em todas as linhas (indentao).

6. Comandos

Na descrio simplificada abaixo, o uso de chaves indica
um item adicional e o de colchetes, um item obrigatrio.

6.1 Interaes com o usurio

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

Escreve um texto, sintetizando simultaneamente.  Se a palavra
MUDO estiver contida, ele no  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]

Obtm 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 aparncia da janela ou reposiciona o cursor nela.
A opes Minimizada serve para tirar a janela do script da
rea visvel, dando, provavelmente a vez para uma outra janela
que esteja abaixo dela.  A opo Normal traz para a atividade
uma janela de script que esteja minimizada ou escondida atrs
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 contrrio, 0 = bip  1 = clek

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

Cores vlidas:
  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 varivel selecionada recebe um dos seguintes valores
    0: no 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 usurio aperte
uma tecla.

g) espera [tempoEmSegundos]

O script  paralisado durante o nmero de segundos especificado.

Exemplo:
    bipa
    espera 2
    bipa

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


6.2 Aes de multimdia

a) toca ["nomeArquivo" ou varivel]

Este comando permite a execuo de um arquivo multimdia (MIDI, WAV, etc),
que possa ser processado pelo Windows.

Se este comando for terminado por &, o script prossegue,
no esperando a execuo da mdia terminar.

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

b) mci [variavelRetorno] ["frase" ou varivel]

Permite a execuo de um comando do MCI - Media Control Interface,
permitindo o controle completo dos dispositivos multimidia, como
CD-ROM, exibio de filmes, sons, animaes, etc...
Veja manual de programao do Windows para uma relao completa de
comandos MCI.

exemplo:
    mci "PLAY CDAUDIO"

6.3 Operaes com arquivo

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

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

Associa um nmero 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 tambm uma conexo 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 operao foi bem sucedida (por exemplo,
se no 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 varivel selecionada recebe um cdigo para indicar o que houve.
  0: no 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 remoo (por exemplo, se o arquivo
no existir ou estiver protegido contra escrita, no 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 &, no acusa erro de execuo
se no 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 no foi completada

6.4 Operaes com diretrios

a) busca [variavel] {DIR} [["nomeArqs" ou varivel] ou PRXIMO]

Se omitido nome ou PRXIMO devolve diretrio atual

b)  dir {CRIA, REMOVE} ["nomeDiretorio" ou variavel]  {terminado por & no d erro


6.5 Operaes com Internet

a) internet [INICIA, TERMINA]

Este comando  obrigatrio para estabelecer ou terminar a comunicao
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 conexo exatamente como se
fosse um arquivo comum.

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

d) observa #n [variavel]
   0: porta TCP/IP no requer ateno
   1: porta requer leitura

   Nota: quando ocorre uma desconexo remota, existe a indicao 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 variveis

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

    Atribui um valor a uma varivel.
    Pode-se opcionalmente usar neste comando uma das seguintes funes,
que atuam como modificadores da valor ou varivel

        TAMANHO     indica que ao invs da varivel (ou valor) deve-se usar
                    o nmero de letras dela
        MAIUSC      indica que antes de realizar a operao deve-se trocar
                    o valor ou varivel para maisculas
        TRIM        indica que antes de realizar a operao deve-se remover
                    os brancos ao incio e fim do valor ou varivel
        POS [subcadeia]   calcula a posio 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 varivel destino um pedao de uma outra varivel

e) transfere [DE, PARA] [variavel]
    Move o contedo textual de uma linha da rea de transferncia DE
    ou PARA uma varivel

f) substitui [variavel] [valor antigo] [valor novo]
    Troca todas as ocorrncias de uma cadeia por outra numa varivel

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 execuo do programa, caso contrrio, o script espera que
o programa conclua sua execuo para prosseguir.

b) desvia [@rotulo]

   Desvia a execuo para um ponto qualquer indicado pelo @rotulo

c) chama [@rotulo]

   Desvia a execuo para um ponto qualquer indicado pelo @rotulo.
Algum momento aps esta operao, entretanto, pode-se executar o
comando retorna para voltar a execuo uma linha abaixo desta do
comando chama.

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

d) retorna

A execuo deste comando provoca o desvio para depois do ltimo
comando chama "empilhado".

e) se {NO} [variavel] [comparador] ["valor" ou variavel] comando

Este comando permite a execuo condicional de comando qualquer,
baseado numa comparao de uma varivel com outra (ou com um valor).
A comparao pode ser feita utilizando os seguintes comparadores:

=   igual (exceto possvelmente por maisculas)
==  igual inclusive nas maisculas
<>  diferente
<   menor
>   maior
<=  menor ou igual
>=  maior ou igual

*=* existe como subcadeia em
=*   comeada por
*=   terminada por

f) cmd [variavel]

Este comando permite que uma varivel seja montada (possivelmente
atravs de operaes de concatenao) e depois interpretada como
se fosse um comando.


g) termina [MUDO]
    Termina a execuo do script


h) debug {+ ou -}

Liga ou desliga o modo debug, no qual cada comando executado  falado.
Esse comando  til durante a verificao de possveis erros do script.

6.8 Operaes com janelas

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

Espera, no mximo por um certo tempo, que uma janela com ttulo
comeado 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 [TTULO ou ATIVA, CAMPO, FOCO] [variavel]

Captura para uma varivel ou ttulo da janela ativa, o campo ativo
ou o elemento que est com o foco do Windows.

6.9 Aes do teclado e mouse

As aes a seguir so enviadas diretamente para a janela ativa atual do
windows, permitindo o seu uso em "controle remoto".  Esses comandos,
portanto so fundamentais para a criao 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.
So 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 so 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 posio.
O uso da palavra TELA indica que  uma coordenada absoluta de tela.
Se ela for omitida a coordenada  calculada em funo da janela
atualmente ativa no Windows.
