ArcaneWooD
A l p h a S c r i p t
Reference File
Version 2.00
version name: Bloom

AlphaScript is an easy scripting language that allows you to do whatever you need. We costantly update AlphaScript with new functions, but only if you ask us to add them: if you're using AlphaScript and you need a function that isn't included, just send me an E-Mail and I'll see what I can do.
The best feature of this script is that you can make a TXT file, write anything you want and after the text lines you can add AlphaScript functions. AlphaScript is also integrated within InfoBook.

This file briefly describes all the functions and the commands within AS. I hope I can be understandable with my bad English. See Technical Infos for more detailed infos or Scripting Tips for some useful hints.

AlphaScript can execute also commands passed to the command line, just typing the function after the executable name (Example: alphascript !msg('Ok') ).

Functions (FXs) Table:

FX to handle other FXs outputs:

Internal Vars (also FXs outputs):

Important:
The strings in ASv2 are handled in a special way. If the text is between two "..." then all the variables will be substituted with their value. Instead if it's between two '...' then even if there are special chars and variables, they wouldn't be translated. If there aren't variables into the string, is better if you use '...' because it's a bit faster (even if I don't know how much) than "..." (there int's the var examining routine).
In this file, I usually use "..." instead then '...' to be more readable.

!exe(file [,parameters])

This function executes the specified file. Can also execute documents and files linked to other programs (a file shoud be linked to a program when it has an icon different from the Windows' standard one) and can open URLs.
This is the pure Windows' API to execute files. This is the command used by all (in my experience) the Windows and Explorer's excution routines.
If the execution has succeded, then @out.exe will be >0 (the hWnd).

Only for executables: you can specify command line parameters separating them with a "," from the exe path (ie: !exe("C:\Windows\Notepad.exe","C:\Example.txt") ).

To send an E-Mail, use this syntax: !exe("mailto:user@server?subject=Text")

!let(var = value)

This functions allows the creation of user defined vars.
All the vars declared with the !let function begins with "@".
The !let function allows also math evaluations (+,-,*,/,^). Thanks to Richard Browne for the source.
If value is written between "..." or '...' then value will be treated as a string, otherwise it will be evaluated.

!if(expression), !then(...), !else(...)

This functions evaluates an expression specified. The valid operators are "==" (equal), "!=" (not equal), ">=", "<=", ">", "<". If the expression is True, then the !then label will be executed otherwise (False) the !else label will be executed.
You can do up to 50 nested IF, within !then or !else.

!dlg(title,mask)

This command opens a windows common dialog of the "open" type. The title is the text displayed in the window titlebar, the mask idicates which file extensions have to be used. This parameter has the following syntax (without quotes): "text displayed 1|*.ext|text displayed 2|*.ext" (i.e.: "Text Files (TXT)|*.txt|Document Files (DOC)|*.doc|All Files|*.*").
The output of this statement is stored within the @out.dlg var.

!copy(origin,destination)

Just copies the specified file to the specified destination. You can use wildcards like * or ? to copy multiple files. With this command you can also rename a file (one only).

!del(file)

This statement deletes the file specified, if it has no Read Only or System attributes.

!dir(path)

This function retrieves the files contained in a single folder. The first time you call it you've to specify the path, and !dir retrieves the first file (within @out.dir). To retrieve the other files you've to use !dir without arguments (ie: dir(). See Example).

!msg(text [,title [,type]])

In this function you can leave both the type and the title parameters. If you do this !msg displays a message box only with the "Ok" button.
The chars "!n" (without quotes) within the text parameter means like a return char.
The output of this function is stored into the var called @out.msg. This var has the value identical to the button pressed. If the button is "Ok" then @msg.out="ok".

There's a simple way to add icons/buttons (string-flag mode). You can make the sum as shown beyond, or use the selection string:

For example, for a message with yes, no and a question icon, use:
!msg("...","...","?yes") or !msg("...","...","?yesno")
Note: you can use the first character without the others (ie: "!")

This table explain the numbers valid for the type parameter:

!input(text [,title [,default]])

With this function you can display a inputbox, where the user can insert some kind of text. The output for this command is defined in the var @out.input.
The chars "!n" (without quotes) within the text parameter means like a return char.

!list(title [,x ,y])

This command opens a list using the items specified with the !listadd function. In this function there are no required parameters. By default the window will be placed in the middle of the screen. The output for this function is defined in the var @out.list.

!listadd(item)

Adds an item (string) to the list. After all the strings are added you can call the !list command and display the list on the screen.

!listclear

Clears the previously memorized list (with the !listadd function).

!winwait(window title)

Stops the execution of the script until the specified window appears on the screen. Supports the wildcards ?, * and # (the last one is used for single digits).

!winkill(window title)

Kills the program that has opened the specified window. This is a hard killing method, and don't allow the application to save its data Supports wildcards like !winwait.

!winactivate(window title)

Sets the window with the type title with focus, on foreground. Supports wildcards like !winwait.

!winpos(window title,left,top,width,height)

Sets the position and the size of the specified window (in pixels). Supports wildcards like !winwait.

!skeys(keys)

This command sends a sequence of keys to the current foreground window.
This is a list of some special characters.

!regread(key,value), !regwrite(key,value,new), !regcreate(key)

These three statements have the "key" value. This is the string copied directly from Regedit.
The output of !regread is placed into @out.reg to be used within the script.

!goto(label), !#label

Jumps to the line that begins with !# and has the same name of the label parameter. This is case-sensitive, means that "MENU" is different from "menu" or "Menu" or "meNu".

!delay(n)

Make a pause for n milliseconds.

!waituntiltime(time)

This command waits until the specified time is reached. This command uses the international settings of your computer (ie: !waituntiltime("21:00:00") ).

!exist(path)

Check if the specified file exist. If not, @out.exist will be =="0", otherwise =="1".

!setclipboard(text)

Set the specified text string into the clipboard. You can get the contenent of the clipboard with the internal var @sys.cliptext.

!quit

Stops the execution of the script. This closes AS if the Log Window isn't open, otherwise you've been able to check the Log Window.

!doevents

This command should be placed in a sequence of statements (long loops or between two long operations) that use a lot of CPU, to allow other applications make multitasking.

!about

Opens the AlphaScript about box.

!clearallvars

Clears all the user - defined vars. This command should be used when all the user - defined vars has been used but you need to set some new ones.

!##showtokens

This function works only if it's written just after the line containing the AS tag (!##AAS). This command shows all the tokens in which the script has been divided (see Technical Infos).

!##debuglog.open

This function opens a windows that shows all the commands executed in real time. When the script execution ends, you have to close this window to fully terminate the script. Obviously this function slows down the script execution.

Scripting Tips

Versions

This is the code to limit the execution of your script only to the right versions of the AlphaScript Compliler, in this example has been used the Build 71 (with !n, be aware that if it's read on an older release, !n will be written as !n, not as a new-line char):

!if(@build>=0071), !then(BEGIN)
!msg(Error Wrong Version!!n!nMade for AlphaScript v1.01.0071!nCurrent AS version @ver^AlphaScript Version Check^64)
!quit
!#BEGIN
<here starts your AlphaScript v1.01>

<here ends your AlphaScript v1.01>
!quit
!##AAS
<here starts your AlphaScript v2.00>

With this you can handle multiple AS versions.

!Dir

Check this source code to see a simple way to use the !dir function. This source also don't have the problem related with big loops using !if and !then (wrong nesting count), in fact this counts just 1 nest.

!##debuglog.open
let(i=0)
!dir("C:\*.*")
!#LP
!let(i=@i+1)
!msg("@out.dir")
!dir()
!if("@out.dir"=='') !then(!goto(OUTX))
!goto(LP)
!#OUTX

For others tips and user scripts, visit my homepage!
If you want to send your script to me please add a lot of comments and a Readme, all zipped in one file. Thanks!

Technical Infos

AlphaScript first loads all the script lines within the file into an array: this allows you to edit the original script file at runtime.

AS at first puts all the script into a single string (max chars: 2^31, two milliards), deleting comments ( ' ' ' text...) and new-line chars, and then splits it into a lot of pieces "tokens" (viewable adding !##showtokens just after !##AAS) and analyzes in sequence all of them from the first to the last one.
The maximum number of tokens allowed is equal to a Single (32 bit) variable, equal to more than a million tokens.

The maximum number of user defined variables is 100, the labels have a maximum of 50 and the !list command items have a maximum of 20. You can also have a maximum of 100 levels of nesting !if.

Every AAS file is executed as a separate task, even if it's called within an AAS file.

Be also aware that AS don't make a full compilation of the script, but analyzes only the functions that it's reading and executing.

File made by Folletto Malefico "@ - Freeware (C) 1999-2000 ArcaneWooD Software [Mail] [Home]