
SV+.

A srie sv+  uma adaptao do interpretador de comandos ScriptVox, que acompanha o DosVox.
No foram feitas alteraes no cdigo original, apenas foram inseridos novos comandos e funes.
Para conhec-los, procure pela ocorrncia de "#>Novos Comandos." (sem aspas),
mais adiante neste texto.

Todos os tpicos so precedidos de #> (number maior), para facilitar a busca.

Iniciaremos a documentao com trechos de uma srie que abordou algumas informaes ausentes no manual original do ScriptVox,publicada por este que vos escreve, 
no grupo:
programando-em-scripvox@googlegroups.com
, grupo criado e moderado por Fabiano Ferreira.

#>Informaes Ausentes.

Nessa srie, Curiosidades, sero apresentadas matrias no includas no manual do ScriptVox, que pode ser encontrado em:
c:\winvox\manual\scripvox.txt
, desde que voc tenha o DosVox instalado.
Por algum motivo desconhecido, muitas caractersticas do interpretador so omitidas, e algumas aparecem descritas equivocadamente.
A primeira delas, ausente,  o modo interativo.
Se respondermos a solicitao inicial: Digite o nome do arquivo cmd a executar, teclando Enter, entraremos no modo imediato.
^Dever ser ouvido: Modo interativo, que  o mesmo que modo imediato.
Nesse modo,  possvel digitar comandos e verificar os seus resultados imediatamente.
Experimente por exemplo digitar:
escreve "modo interativo"
, ou qualquer outra coisa, e teclar Enter.
Ser ouvida a mensagem solicitada.
Da mesma forma, muitos outros comandos podem ser testados sem a necessidade de escrever um cdigo, gravar num arquivo, e dizer ao interpretador para execut-lo.
Muitos comandos no so possveis de serem executados, tais como desvia, chama, enquanto, repete, as formas mais elaboradas do comando se, e alguns outros.
Apesar disso,  possvel investigar a utilizao de muitos comandos atravs desse modo.
Experimentem e vejam quais comandos podem ser submetidos.

(adendo)
#>Constantes, Variveis e Strings.
Um conceito bastante comum em programao, e que ser utilizado neste texto,  a noo de variveis e constantes.
Como o prprio nome j diz, constante  um valor que no muda.
O nmero 5 por exemplo, ser sempre 5.
Uma varivel, por sua vez, poder conter muitos valores diferentes durante a execuo do programa.
Por uma questo de preferncia pessoal, uma seqncia de caracteres ser referenciada por seu nome em ingls (string), neste texto, ao invs do termo cadeia utilizado no manual.
No caso, a string "eu sou uma string", tambm  uma constante, porque o seu valor no poder ser alterado.

#>Comando Fala.

A curiosidade de hoje  o comando Fala, que tambm no est documentado no manual.

O comando Fala sintetiza mensagens indicadas logo aps o nome do comando.

Sua sintaxe :
fala mensagem
, onde mensagem pode ser uma varivel ou constante, e pode haver mais de uma, assim como no comando escreve.

Constantes devem estar entre aspas.

Por ser curto e de fcil digitao, ele  ideal para ser utilizado no modo interativo, para verificar os resultados dos comandos submetidos.

Se por exemplo for atribuda a palavra ok  varivel o, basta digitar:
fala o
, para ter uma mensagem de confirmao, que poder ser utilizada para checar uma determinada condio, como por exemplo:
se a=4 fala o
 .
.

#>Omisses possveis.

Embora em alguns casos no seja muito elegante,  possvel omitir algumas informaes ao digitar um cdigo em Scriptvox.

Alm do comando escreve, que ao ser digitado sem parmetros apenas pula uma linha na tela, o comando l pode prescindir da varivel que normalmente o segue.
Exemplos:
escreve "Tecle Enter para prosseguir"
l
 .
Nesse exemplo,  necessrio teclar Enter para continuar.
 .
escreve "Tecle algo para continuar"
l &
 .
Nesse exemplo, qualquer tecla retomar o processamento.
Quando for  desejada apenas uma pausa controlada pelo usurio no processamento, no  necessria a atribuio a uma varivel.
Nenhum dos anteriores pode conter as clusulas mudo, senha ou edita.

No  obrigatrio terminar uma constante alfanumrica com aspas.
Exemplo:
seja a "sem aspas no final
 .
Alm de nas atribuies, isso pode ser feito nos comandos escreve, fala e concatena, mas no nas comparaes.
.

#>Capacidade de armazenamento das variveis.

No manual do ScriptVox, que se encontra em:
c:\winvox\manual\scripvox.txt
, h um trecho que se refere  capacidade de armazenamento das variveis, e onde se l:
(se referindo s variveis rpidas e lentas):
"Ambos os tipos de variveis podem conter cadeias de caracteres de at 65000 letras.".

Na prtica porm...
Observe o programa abaixo:
seja a ""
repete n 1000000
concatena a 1
fim repete
seja t tamanho a
fala "antes:"t
remove 1&
abre #1 1&
escreve #1 a
fecha #1
espera 1
abre #1 1
l #1 b
fecha #1
seja t tamanho b
fala "depois:"t
 .
Podemos observar que no s na atribuio, mas tambm na gravao e leitura, as variveis a e b puderam armazenar um milho de caracteres.

No foi tentado um valor maior, apenas por questo de tempo.
A atribuio inicial levou 17 segundos na mquina onde foi testada.

Tentem com valores maiores para descobrir o limite!
.

#>Expresses matemticas.

No manual do scriptvox, Na sesso:

(6.5) PROCESSAMENTO DE VARIVEIS

, onde  abordado o comando seja, se l:

"No so permitidas operaes aritmticas no comando seja.
Assim seja a=b+c  uma operao invlida".
(ou melhor:
seja, espao, a, sinal de igual, b, sinal de mais, c, espao,  uma operao invlida).

No entanto, foi constatado que se colocarmos operaes matemticas entre parnteses, elas so aceitas sem problemas.
Exemplo:
seja a (2+3)
(ou melhor:
seja, espao, a, espao, abre parnteses, 2, sinal de mais, 3, fecha parnteses).
, resultando 5 em a.

Uma sequncia de nmeros ou variveis, e sinais que representam operaes matemticas,  conhecida como expresso matemtica.
Os sinais utilizados para representar as operaes so:
+ (mais), adio.
- (hfen), subtrao.
* (asterisco), multiplicao.
/ (barra), diviso.

Uma expresso matemtica pode conter vrias operaes.
Exemplo:
seja s (2+3*5)
(ou melhor:
seja, espao, s, espao, abre parnteses, 2, sinal de mais, 3, asterisco, 5, fecha parnteses).
, resultando 17 em s.

O resultado acima se deve ao que  conhecido como precedncia de operadores.
Ao invs das operaes serem executadas na ordem de leitura, algumas operaes so executadas antes que outras.

No caso acima, primeiro  calculada a multiplicao de 3 por 5, resultando 15.
Depois  calculada a soma de 2 com 15, resultando 17.

A ordem de precedncia das operaes :
1) Multiplicao e diviso so executadas primeiro.
2) Soma e subtrao so executadas depois.

Nos casos em que houver operaes com o mesmo nvel de precedncia, por exemplo soma e subtrao, a ordem  a de leitura, ou seja: da esquerda para a direita.

Uma expresso matemtica pode conter variveis e constantes.
Exemplo:
seja a 5
seja b 2
seja c (3+a*b-b)
(ou melhor:
seja, espao, c, espao, abre parnteses,3, sinal de mais, a, asterisco, b, hfem, b, fecha parnteses).
, resultando 11 em c.

As expresses matemticas podem ser usadas tanto em atribuies, quanto em comparaes.
Exemplo, aproveitando o clculo anterior:
seja a 5
seja b 2
se (3+a*b-b)=11 escreve "Correto."
 .
.

#>Comparadores de trechos.

O comparador asterisco  igual a asterisco (*=*), tem um engano na sua
definio, no manual do ScriptVox.
L est escrito:
"existe como subcadeia em"
, quando na verdade o correto :
"contm"
, ou se for para usar o termo:
"tem como subcadeia!
 .
Vejamos.
Se x for "abcd", e y for "cd", a comparao:
x*=*y
ou seja: x asterisco  igual a asterisco y,
resultar verdadeiro, o que pode ser confirmado pelos comandos:
seja x "abcd"
seja y "cd"
se x*=*y fala "verdadeiro"
 .
Se a definio no manual estivesse correta, a"abcd" existiria como
subcadeia em "cd", o que no  possvel.
Lembrem-se tambm de que os trs comparadores que lidam com trechos de
strings, so sensveis a maisculas.
Recapitulando, so eles:
smbolo, extenso entre parnteses, definio do comparador.
=*, ( igual a asterisco),  iniciada por,
*=, (asterisco  igual a),  terminada por,
*=*, (asterisco  igual a asterisco), contm...
.

#>Funo palavra.

Outra informao ausente no manual,  a funo PALAVRA.

A funo palavra copia uma substring delimitada por espaos, e indicada pela posio em que aparecer na string.
Sua sintaxe :
seja varivel palavra posio string
, onde:
varivel, ir receber a substring,
posio,  a posio em que a substring aparece na string,
e string,  a string principal, onde a busca ocorrer.
Exemplo:
seja $string "ameixa, banana-da-terra, caqui damasco"
seja $substring palavra 1 $string
, resultar em "ameixa," (com vrgula e tudo), em $substring.
seja b palavra 2 $string
, resultar em "banana-da-terra," (tambm com vrgula), em, b.
Note os hifens ligando a banana, ao da, e  terra.
seja x palavra 3 $string
, resultar em "caqui" (sem vrgula), em x.
A subbstring caqui apareceu sem vrgula, porqu em $string ela no tem.
No importa o contedo da string, a funo palavra s levar em conta os espaos antes e depois de uma substring, para consider-la como palavra.

Outro exemplo:
* numa string com vrias palavras,
seja x "primeiro segundo terceiro quarto quinto"
escreve "Tecle um nmero de 1 a 5, Escape=termina."
desvia @outra
@erro
bipa
@outra
l mudo n&
se n="#27" termina
se n<"1" desvia @erro
se n>"5" desvia @erro
* a funo palavra retorna uma substring delimitada por espaos, indicada pelo nmero de ordem fornecido.
seja y palavra n x
escreve y
desvia @outra
*

#>Novos comandos.
Veja tambm os comentrios nos scripts de exemplos.
A lista deles est em ndice.txt.

#>Clusula TECLA para o comando l.
A clusula tecla para o comando l, retorna uma string contendo o cdigo da tecla acionada.
Sua sintaxe :
l TECLA varivel[&]
, onde:
varivel, poder ser rpida ou lenta, e receber o cdigo da tecla acionada.
& ( comercial),  opcional, e indica que dever ser acionada apenas uma tecla.
Podero ser utilizadas tambm as clusulas mudo ou senha.
Como se trata de apenas uma tecla, a clusula edita no faz sentido.
Se ela for utilizada, ao teclar o primeiro caracter, o comando l terminar.
O valor retornado  uma string iniciada por trs caracteres fixos, que podero ser 0 ou 1, indicando:
Na primeira posio, 1 se a tecla Shift foi acionada, 0 se no.
Na segunda posio, 1 se a tecla Control foi acionada, 0 se no.
Na terceira posio, 1 se a tecla Alt foi acionada, 0 se no.
O restante da string conter:
Se a tecla acionada for uma tecla de controle, o respectivo cdigo.
Se a tecla acionada contiver um caracter, o cdigo ASCII correspondente.
Para mais informaes sobre cdigos ASCII, veja doc\ASCII.txt.
Os cdigos sero precedidos do sinal # (number).

#>Funo ASC para o comando l.
A funo ASC retorna o cdigo ASCII de um caracter.
Sua sintaxe :
seja varivel ASC caracter
, onde:
varivel, poder ser rpida ou lenta, e receber o resultado da converso, ou uma string vazia.
caracter, poder ser uma constante ou uma varivel, que contenha um nico caracter.
O cdigo retornado por ASC ser uma string contendo o caracter #(#number), seguido dos dgitos que representam um valor numrico de 0 a 255.
Caso a funo no possa realizar a converso, ela retornar uma string vazia.

#>Funo CHR para o comando l.
A funo CHR retorna o caracter correspondente a um cdigo ASCII.
Sua sintaxe :
seja varivel CHR cdigo
, onde:
varivel, poder ser uma varivel rpida ou lenta, e receber o caracter correspondente ao cdigo fornecido, ou uma string vazia.
cdigo, poder ser uma constante ou uma varivel, que contenha o cdigo desejado.
O cdigo a ser convertido, dever ser uma string iniciada por um sinal de #(number), seguido dos dgitos que representam um valor numrico de 0 a 255.
Se a converso no for possvel, a funo retornar uma string vazia "".

A funo CHR tem tambm a habilidade de converter um cdigo retornado pela clusula tecla do comando l.
Se o cdigo no corresponder a um caracter, a funo retornar uma string vazia.
.

#>comando MIDI.
Para mais informaes sobre MIDI, veja doc\MIDI.txt.

#>MIDI Inicia.
O comando MIDI Inicia, inicia as operaes com o sistema MIDI.
Antes de qualquer outro comando MIDI, ele dever ser usado.
A tentativa de usar qualquer comando MIDI antes dele, gerar um erro.
Se deve us-lo apenas uma vez, no incio da sesso, e a tentativa de us-lo novamente, antes de usar o comando MIDI Termina, gerar um erro.
Sua sintaxe :
MIDI Inicia
.
Este comando no tem parmetros.

#>MIDI Termina.
O comando MIDI Termina, encerra as operaes com o sistema MIDI.
Ele deve ser usado ao final do processamento.
Se ele for usado sem que o sistema esteja iniciado, gerar um erro.
Sua sintaxe :
MIDI Termina
.
Este comando no tem parmetros.

#>MIDI Nota Ligada.
O comando MIDI Nota Ligada, abreviado por NL, ativa uma nota em um determinado canal, com un certo volume.
Ele  o correspondente em Portugus do Note On.
Sua sintaxe :
MIDI NL canal nota volume
, onde:
canal, poder ser um valor de 1 a 16,
nota e volume podero  ser de 0 a 127.
Canal, Nota e Volume, podero ser constantes, variveis ou expresses, mas devero ser necessariamente um valor numrico.
Um valor fora da faixa indicada, ou a falta de algum parmetro, resultar em erro.
Todo comando MIDI Nota Ligada, dever, em algum momento, ser seguido do comando MIDI Nota Desligada.

#>MIDI Nota Desligada.
O comando MIDI Nota Desligada, abreviado por ND, desliga, silencia uma nota em um determinado canal.
Sua sintaxe :
MIDI ND canal nota
,onde:
canal, poder ser um valor de 1 a 16,
e nota, poder ser de 0 a 127.
Ambos podero ser variveis, constantes ou expresses, mas devero necessariamente ser um valor numrico.
Um valor fora da faixa indicada, ou a falta de algum parmetro, resultar em erro.
Um comando MIDI Nota Desligada, que no for precedido por um comando MIDI Nota Ligada, ser ignorado.

#>MIDI Troca Timbre.
O comando MIDI Troca Timbre, abreviado por TT, altera o timbre do canal indicado, para um valor tambm fornecido.
Sua sintaxe :
MIDI TT canal timbre
, onde:
canal, poder ser de 1 a 16,
e timbre, poder ser de 0 a 127.
Ambos podero ser constantes, variveis ou expresses, mas devero ser necessariamente um valor numrico.
Um valor fora da faixa indicada, ou a falta de algum parmetro, resultar em erro.

#>MIDI Pane.
O comando MIDI Pane desliga todas as notas de todos os canais, de uma vez s, silenciando o instrumento.
Sua sintaxe :
MIDI Pane
.
Este comando no tem parmetros.

#>funo PARAMS para o comando seja.
A funo PARAMS retorna uma string com a quantidade e a lista de parmetros recebidos na linha de comando, e a serem passados ao script.
Sua sintaxe :
seja varivel PARAMS
,onde:
varivel pode ser rpida ou lenta (precedida de $), e receber uma string com as seguintes caractersticas:
Todos os elementos da string so separados por um espao, para que possam ser tomados individualmente pela funo palavra.
O primeiro elemento  a quantidade de parmetros recebidos pelo script.
A seguir estaro cada um dos parmetros recebidos.
A string ento conter o nmero de parmetros passados, mais um, (o primeiro) que indica a quantidade deles.
Se no houver nenhum, a varivel receber 0.
Veja mais informaes e exemplos nos comentrios em bin\param.cmd.

#
