Xelagot action script

Symbolic path notation

Symbolic path notation requires xelagot 3.607 or higher

If you are not familiar with the term USBD, or with security restrictions applied by xelagots 3.607 or higher, please read User and Script Base Directory (USBD).

Fully qualified paths have a drive letter, a colon, a backslash followed by the path folder. A backslash may end the path notation. Xelagot requires this trailing backslash to distinguish folder from file. An example of a path to a folder could be:
c:\xelagots\x1\

Xelagot 3.607 introduces symbols representing fully qualified paths to its own folders, without revealing the actual path. They start with $: which stands for the drive, followed by an identifier, ending in a backslash.

Paths to folders outside the USBD not accessible to scripts unless explicitely allowed in the ini file, see Question 2 on the USBD page.
$:application\	path to the xelagot application.
$:chat\	path to the Chat folder, usually the same as $:application\Chat\
$:objects\	path to the Objects folder, usually the same as $:application\Objects\
$:preferences\	path to the preferences folder, usually the same as $:application\Preferences\
$:world\	path to the World folder, usually the same as $:application\World\
$:attributes\	path to the Attributes folder, usually the same as $:application\Attributes\

Paths to folders inside the USBD accessible to scripts.
$:usbd\	path to the USBD folder
$:deejay\	path to the _DeeJay folder, same as $:usbd\_DeeJay\
$:customspeakers\	path to the CustomSpeakers folder (inside the _DeeJay folder), same as $:usbd\_DeeJay\CustomSpeakers\ $:deejay\CustomSpeakers\
$:survey\	path to the _Survey folder, same as $:usbd\_Survey\
$:downloads\	path to the _Downloads folder, same as $:usbd\_Downloads\
$:logs\	path to the _Logs folder, same as $:usbd\_Logs\
$:my\	path to the running script's folder note: defined only within the context of a script, may not be used in the ini file's ScriptAccessPaths key.
$:myfile	path and filename of the running script, no trailing backslash! note: defined only within the context of a script, may not be used in the ini file's ScriptAccessPaths key.

Examples:
$f = "$:downloads\doggy.wav"
refers to file doggy.wav in the _Downloads folder.
$f = "$:myfile"
assigns symbolically the running script's path and filename to $f; if this statement follows
SayConcat $f
the bot will simply say
$:myfile
but will know exactly how to use this symbol in file operations.

Filenames

To load and save data, the application must know where to access the file, i.e. it requires fully specified filenames, with drive, path and the name of the file.

Up to version 3.606, the file is assumed to be in the running script's folder if the path is not fully specified, or in the old Script folder.

As from version 3.607, the following convention is followed when executing a file access command:

The filename is examined for drive specification, symbolic path notation is accepted as valid. If a colon is found, the filename is considered to be fully specified.
Otherwise, the file is considered to be situated someplace relative to the running script's folder. The following symbols may be used at the begining of the filename:
..\  means in the 'parent' folder, ..\..\ means two up, etc
.\  means in the script's folder, and can be omitted
\  should not be used, as it refers to the root directory of the drive
If none of these symbols are present at the begining of the filename, the file is in the script's folder (or a sub-folder, see below)

These symbols define the drive and path of the file, at least partially. The filename can also contain folder specifications, e.g.
$f = "test1\bobby.txt"
indicates file bobby.txt in folder test1 in the current script's folder, and can also be written as
$f = ".\test1\bobby.txt"
$f = "$:my\test1\bobby.txt"

Once the full drive+path+filename is reconstructed and used in a file access statement, the application checks to see if security settings allow accessing the file's folder. If this test fails, the command is not executed.

Program paths and path\file operations

version 2.99987 upwards

The paths used by the program can be retrieved using the statements below. Paths include the final backslash.

As from xelagot 3.607, paths are given a symbolic notation, so as not to reveal the actual path.

GetMyFile $a
the current script file
3.607 Symbol: $:myfile
3.607: $a will contain the symbolic path $:usbd\ plus the relative path from the USBD to the current script file, if the file is inside the USBD, and the name of the script file. The symbolic notation $:myfile is not used here.
If the file is outside of the application path, the full path will be retrieved, even if Security is ON.
GetMyDir $a
the path of the current script file
3.607 Symbol: $:my\
3.607: $a will contain the symbolic path $:usbd\ plus the relative path from the USBD to the current script's folder, if the folder is inside the USBD. The symbolic notation $:my\ is not used here. If the file is outside of the application path, the full path will be retrieved, even if Security is ON.
GetDeeJayDir $a
3.607 Symbol: $:deejay\
GetSurveyDir $a
3.607 Symbol: $:survey\
GetCustomSpeakersDir $a
3.607 Symbol: $:customspeakers\
GetDownloadsDir $a
3.607 Symbol: $:downloads\
xelagot 3.607
GetLogsDir $a
3.607 Symbol: $:logs\
GetScriptDir $a
3.607 Symbol: $:usbd\
xelagot 3.607
GetUSBD $a
3.607 Symbol: $:usbd\
GetChatDir $a
3.607 Symbol: $:chat\
3.607 Security: not in USBD
GetObjectsDir $a
3.607 Symbol: $:objects\
3.607 Security: not in USBD
GetPreferencesDir $a
3.607 Symbol: $:preferences\
3.607 Security: not in USBD
GetWorldDir $a
3.607 Symbol: $:world\
3.607 Security: not in USBD
GetAttributesDir $a
3.607 Symbol: $:attributes\
3.607 Security: not in USBD
xelagot 3.607
GetApplicationDir $a
3.607 Symbol: $:application\
3.607 Security: not in USBD

A script to test this notation can be downloaded here. It can be used with older xelagots too.

Example 1: you wish to access a text file called "Mars.xsp" in the CustomSpeakers folder. This folder is a standard one for the program (and is since 3.607 in the USBD), so you can build the full path and file name easily:

   GetCustomSpeakersDir $q
   Concat $f $q "Mars.xsp"

or you could write for xelagots 3.607 and higher:

   $f = "$:customspeakers\Mars.xsp"

$f will now contain the required full path and filename.

Example 2: you wish to access a text file called "data.txt" in the Mars folder you made in the standard USBD folder:

   GetScriptDir $q
   Concat $f $q "Mars\data.txt"

or for xelagots 3.607 or higher

   $f = "$:usbd\Mars\data.txt"

$f contains the required full path and filename.

These path\file operations are possible:

GetParentDir $d $f	Gets the parent directory (including the final '\') of a file or directory, if $f includes a path, and stores it in $d. If $f does not include a path or if an error occurs, $d is empty.
ExtractFileDir $d $f	Gets the directory (including the final '\') of file $f if $f contains a path, and stores it in $d.
ExtractFileName $n $f	Gets the name part of a file, i.e., the 'name.ext', dropping the path, and stores it in $n.
ExtractFileBody $b $f	Gets the name of a file without the extension or the path, and stores it in $b.
ExtractFileExt $e $f	Gets the extension of a file including the period character and stores it in $e. If there is no extension, $e is empty.
ForceDirectories $d	xelagot 3.607 If $d is a full valid path, it will attempt to create the directories specified in the path $d if they don't already exist. If $d is a relative path, it will attempt to create the directories relative to the directory of the running script. For example: ForceDirectories "test" ForceDirectories "..\mars\test1" would create if possible a folder called "test" in the same folder as the script, and folders called "mars\test1" one directory up (assuming all is within the permitted area, by default within the USBD). older xelagots If $d is a full valid path, it will attempt to create the directories specified in the path $d if they don't already exist.
IfFileExists $f statement1 Else statement2	Executes statement1 if file $f exists, otherwise (optional) statement2. xelagot 3.607 or newer $f follows the rules set up in section Filenames. If Security is ON, the file must be within the allowed regions, otherwise it will not be seen. xelagot 3.606 or older $f must have a fully qualified path.
IfDirectoryExists $d statement1 Else statement2	Executes statement1 if directory $d exists, otherwise (optional) statement2. xelagot 3.607 or newer $d follows the rules set up in section Filenames. If Security is ON, the directory must be within the allowed regions, otherwise it will not be seen. xelagot 3.606 or older $d must have a fully qualified path.
DeleteFile $f [%rc]	xelagot 3.607 Attempts to delete file $f. Optional parameter %rc contains 0 if the operation succeeds, otherwise -1. $f follows the rules set up in section Filenames.
RenameFile $f $n [%rc]	xelagot 3.607 Attempts to rename file $f with new name $n. Optional parameter %rc contains 0 if the operation succeeds, otherwise -1. $f follows the rules set up in section Filenames. $n does not need a path specification (it will be removed if it has one).

Index