
SV+.

A série sv+ é uma adaptação do interpretador de comandos ScriptVox, que acompanha o DosVox.
Não foram feitas alterações no código original, apenas foram inseridos novos comandos e funções.
Para conhecê-los, procure pela ocorrência de "#>Novos Comandos." (sem aspas),
mais adiante neste texto.

Todos os tópicos são precedidos de #> (number maior), para facilitar a busca.

Iniciaremos a documentação com trechos de uma série que abordou algumas informações 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.

#>Informações Ausentes.

Nessa série, Curiosidades, serão apresentadas matérias não incluídas 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 características do interpretador são omitidas, e algumas aparecem descritas equivocadamente.
A primeira delas, ausente, é o modo interativo.
Se respondermos a solicitação 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, é possível 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 código, gravar num arquivo, e dizer ao interpretador para executá-lo.
Muitos comandos não são possíveis de serem executados, tais como desvia, chama, enquanto, repete, as formas mais elaboradas do comando se, e alguns outros.
Apesar disso, é possível investigar a utilização de muitos comandos através desse modo.
Experimentem e vejam quais comandos podem ser submetidos.

(adendo)
#>Constantes, Variáveis e Strings.
Um conceito bastante comum em programação, e que será utilizado neste texto, é a noção de variáveis e constantes.
Como o próprio nome já diz, constante é um valor que não muda.
O número 5 por exemplo, será sempre 5.
Uma variável, por sua vez, poderá conter muitos valores diferentes durante a execução do programa.
Por uma questão de preferência pessoal, uma seqüência de caracteres será referenciada por seu nome em inglês (string), neste texto, ao invés do termo cadeia utilizado no manual.
No caso, a string "eu sou uma string", também é uma constante, porque o seu valor não poderá ser alterado.

#>Comando Fala.

A curiosidade de hoje é o comando Fala, que também não está documentado no manual.

O comando Fala sintetiza mensagens indicadas logo após o nome do comando.

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

Constantes devem estar entre aspas.

Por ser curto e de fácil digitação, ele é ideal para ser utilizado no modo interativo, para verificar os resultados dos comandos submetidos.

Se por exemplo for atribuída a palavra ok à variável o, basta digitar:
fala o
, para ter uma mensagem de confirmação, que poderá ser utilizada para checar uma determinada condição, como por exemplo:
se a=4 fala o
 .
.

#>Omissões possíveis.

Embora em alguns casos não seja muito elegante, é possível omitir algumas informações ao digitar um código em Scriptvox.

Além do comando escreve, que ao ser digitado sem parâmetros apenas pula uma linha na tela, o comando lê pode prescindir da variável que normalmente o segue.
Exemplos:
escreve "Tecle Enter para prosseguir"
lê
 .
Nesse exemplo, é necessário 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 usuário no processamento, não é necessária a atribuição a uma variável.
Nenhum dos anteriores pode conter as cláusulas mudo, senha ou edita.

Não é obrigatório terminar uma constante alfanumérica com aspas.
Exemplo:
seja a "sem aspas no final
 .
Além de nas atribuições, isso pode ser feito nos comandos escreve, fala e concatena, mas não nas comparações.
.

#>Capacidade de armazenamento das variáveis.

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

Na prática porém...
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 não só na atribuição, mas também na gravação e leitura, as variáveis a e b puderam armazenar um milhão de caracteres.

Não foi tentado um valor maior, apenas por questão de tempo.
A atribuição inicial levou 17 segundos na máquina onde foi testada.

Tentem com valores maiores para descobrir o limite!
.

#>Expressões matemáticas.

No manual do scriptvox, Na sessão:

(6.5) PROCESSAMENTO DE VARIÁVEIS

, onde é abordado o comando seja, se lê:

"Não são permitidas operações aritméticas no comando seja.
Assim seja a=b+c é uma operação inválida".
(ou melhor:
seja, espaço, a, sinal de igual, b, sinal de mais, c, espaço, é uma operação inválida).

No entanto, foi constatado que se colocarmos operações matemáticas entre parênteses, elas são aceitas sem problemas.
Exemplo:
seja a (2+3)
(ou melhor:
seja, espaço, a, espaço, abre parênteses, 2, sinal de mais, 3, fecha parênteses).
, resultando 5 em a.

Uma sequência de números ou variáveis, e sinais que representam operações matemáticas, é conhecida como expressão matemática.
Os sinais utilizados para representar as operações são:
+ (mais), adição.
- (hífen), subtração.
* (asterisco), multiplicação.
/ (barra), divisão.

Uma expressão matemática pode conter várias operações.
Exemplo:
seja s (2+3*5)
(ou melhor:
seja, espaço, s, espaço, abre parênteses, 2, sinal de mais, 3, asterisco, 5, fecha parênteses).
, resultando 17 em s.

O resultado acima se deve ao que é conhecido como precedência de operadores.
Ao invés das operações serem executadas na ordem de leitura, algumas operações são executadas antes que outras.

No caso acima, primeiro é calculada a multiplicação de 3 por 5, resultando 15.
Depois é calculada a soma de 2 com 15, resultando 17.

A ordem de precedência das operações é:
1) Multiplicação e divisão são executadas primeiro.
2) Soma e subtração são executadas depois.

Nos casos em que houver operações com o mesmo nível de precedência, por exemplo soma e subtração, a ordem é a de leitura, ou seja: da esquerda para a direita.

Uma expressão matemática pode conter variáveis e constantes.
Exemplo:
seja a 5
seja b 2
seja c (3+a*b-b)
(ou melhor:
seja, espaço, c, espaço, abre parênteses,3, sinal de mais, a, asterisco, b, hífem, b, fecha parênteses).
, resultando 11 em c.

As expressões matemáticas podem ser usadas tanto em atribuições, quanto em comparações.
Exemplo, aproveitando o ´cálculo 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
definição, no manual do ScriptVox.
Lá está escrito:
"existe como subcadeia em"
, quando na verdade o correto é:
"contém"
, ou se for para usar o termo:
"tem como subcadeia!
 .
Vejamos.
Se x for "abcd", e y for "cd", a comparação:
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 definição no manual estivesse correta, a"abcd" existiria como
subcadeia em "cd", o que não é possível.
Lembrem-se também de que os três comparadores que lidam com trechos de
strings, são sensíveis a maiúsculas.
Recapitulando, são eles:
símbolo, extenso entre parênteses, definição do comparador.
=*, (é igual a asterisco), é iniciada por,
*=, (asterisco é igual a), é terminada por,
*=*, (asterisco é igual a asterisco), contém...
.

#>Função palavra.

Outra informação ausente no manual, é a função PALAVRA.

A função palavra copia uma substring delimitada por espaços, e indicada pela posição em que aparecer na string.
Sua sintaxe é:
seja variável palavra posição string
, onde:
variável, irá receber a substring,
posição, é a posição 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 vírgula e tudo), em $substring.
seja b palavra 2 $string
, resultará em "banana-da-terra," (também com vírgula), em, b.
Note os hifens ligando a banana, ao da, e à terra.
seja x palavra 3 $string
, resultará em "caqui" (sem vírgula), em x.
A subbstring caqui apareceu sem vírgula, porquê em $string ela não tem.
Não importa o conteúdo da string, a função palavra só levará em conta os espaços antes e depois de uma substring, para considerá-la como palavra.

Outro exemplo:
* numa string com várias palavras,
seja x "primeiro segundo terceiro quarto quinto"
escreve "Tecle um número 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 função palavra retorna uma substring delimitada por espaços, indicada pelo número de ordem fornecido.
seja y palavra n x
escreve y
desvia @outra
*

#>Novos comandos.
Veja também os comentários nos scripts de exemplos.
A lista deles está em índice.txt.

#>Cláusula TECLA para o comando lê.
A cláusula tecla para o comando lê, retorna uma string contendo o código da tecla acionada.
Sua sintaxe é:
lê TECLA variável[&]
, onde:
variável, poderá ser rápida ou lenta, e receberá o código da tecla acionada.
& (é comercial), é opcional, e indica que deverá ser acionada apenas uma tecla.
Poderão ser utilizadas também as cláusulas mudo ou senha.
Como se trata de apenas uma tecla, a cláusula edita não faz sentido.
Se ela for utilizada, ao teclar o primeiro caracter, o comando lê terminará.
O valor retornado é uma string iniciada por três caracteres fixos, que poderão ser 0 ou 1, indicando:
Na primeira posição, 1 se a tecla Shift foi acionada, 0 se não.
Na segunda posição, 1 se a tecla Control foi acionada, 0 se não.
Na terceira posição, 1 se a tecla Alt foi acionada, 0 se não.
O restante da string conterá:
Se a tecla acionada for uma tecla de controle, o respectivo código.
Se a tecla acionada contiver um caracter, o código ASCII correspondente.
Para mais informações sobre códigos ASCII, veja doc\ASCII.txt.
Os códigos serão precedidos do sinal # (number).

#>Função ASC para o comando lê.
A função ASC retorna o código ASCII de um caracter.
Sua sintaxe é:
seja variável ASC caracter
, onde:
variável, poderá ser rápida ou lenta, e receberá o resultado da conversão, ou uma string vazia.
caracter, poderá ser uma constante ou uma variável, que contenha um único caracter.
O código retornado por ASC será uma string contendo o caracter #(#number), seguido dos dígitos que representam um valor numérico de 0 a 255.
Caso a função não possa realizar a conversão, ela retornará uma string vazia.

#>Função CHR para o comando lê.
A função CHR retorna o caracter correspondente a um código ASCII.
Sua sintaxe é:
seja variável CHR código
, onde:
variável, poderá ser uma variável rápida ou lenta, e receberá o caracter correspondente ao código fornecido, ou uma string vazia.
código, poderá ser uma constante ou uma variável, que contenha o código desejado.
O código a ser convertido, deverá ser uma string iniciada por um sinal de #(number), seguido dos dígitos que representam um valor numérico de 0 a 255.
Se a conversão não for possível, a função retornará uma string vazia "".

A função CHR tem também a habilidade de converter um código retornado pela cláusula tecla do comando lê.
Se o código não corresponder a um caracter, a função retornará uma string vazia.
.

#>comando MIDI.
Para mais informações sobre MIDI, veja doc\MIDI.txt.

#>MIDI Inicia.
O comando MIDI Inicia, inicia as operações 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 início da sessão, e a tentativa de usá-lo novamente, antes de usar o comando MIDI Termina, gerará um erro.
Sua sintaxe é:
MIDI Inicia
.
Este comando não tem parâmetros.

#>MIDI Termina.
O comando MIDI Termina, encerra as operações 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 não tem parâmetros.

#>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 Português do Note On.
Sua sintaxe é:
MIDI NL canal nota volume
, onde:
canal, poderá ser um valor de 1 a 16,
nota e volume poderão  ser de 0 a 127.
Canal, Nota e Volume, poderão ser constantes, variáveis ou expressões, mas deverão ser necessariamente um valor numérico.
Um valor fora da faixa indicada, ou a falta de algum parâmetro, 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 poderão ser variáveis, constantes ou expressões, mas deverão necessariamente ser um valor numérico.
Um valor fora da faixa indicada, ou a falta de algum parâmetro, resultará em erro.
Um comando MIDI Nota Desligada, que não 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 também fornecido.
Sua sintaxe é:
MIDI TT canal timbre
, onde:
canal, poderá ser de 1 a 16,
e timbre, poderá ser de 0 a 127.
Ambos poderão ser constantes, variáveis ou expressões, mas deverão ser necessariamente um valor numérico.
Um valor fora da faixa indicada, ou a falta de algum parâmetro, 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 não tem parâmetros.

#>função PARAMS para o comando seja.
A função PARAMS retorna uma string com a quantidade e a lista de parâmetros recebidos na linha de comando, e a serem passados ao script.
Sua sintaxe é:
seja variável PARAMS
,onde:
variável pode ser rápida ou lenta (precedida de $), e receberá uma string com as seguintes características:
Todos os elementos da string são separados por um espaço, para que possam ser tomados individualmente pela função palavra.
O primeiro elemento é a quantidade de parâmetros recebidos pelo script.
A seguir estarão cada um dos parâmetros recebidos.
A string então conterá o número de parâmetros passados, mais um, (o primeiro) que indica a quantidade deles.
Se não houver nenhum, a variável receberá 0.
Veja mais informações e exemplos nos comentários em bin\param.cmd.

#
