Scripting


XYplorer Scripting, introduced with version 7.00, can truly be seen as the ultimate in file management efficiency. Roll your own custom commands, combine them to scripts, wrap them in an XY Script file (XYS), or a User-Defined Command, and trigger them by just a click or a keystroke. Can't get any better? It can! Share scripts with colleagues, or download them from the internet: Just drop a script file into your app folder and fresh plug-in commands are at your finger tips.

Without doubt, scripting is an advanced feature that only pays off if you take the time to dive into it and explore the ways and possibilities. However, you will eventually find out that it ain't rocket science at all.

What can Scripting do for me anyway?

Before we dig deeper, here are some of the truly wonderful things Scripting can do for you:

Create a fully formatted HTML document containing the list of files you are currently looking at in your file manager, with a single click.
Look up the title of the currently selected file in the IMDB (Internet Movie Data Base), with a single click.
Convert all Umlauts contained in the currently selected text file, with a single click.
Transfer the content of your digital camera SD card in its new folder renamed by today's month, with a single click.
Save all last years .doc files in a zip file named doc_backup_07.zip, with a single click.
Seemless TeraCopy Integration.
Download a specific file from internet without using a browser.
Open the first URL contained in the clipboard.
Copy any file on your computer to "here" (to the current working directory).

A crash course in Scripting

To get you started let's do some easy warm-ups:
Select menu Scripting | Try Script...
Paste msg "Hello world!" into the edit box.
Click OK.

You should see a "Hello world!" message box now. Well done, you just wrote your first XYplorer script!

Okay, now for something a little bit more interesting:

Try msg "%temp%". You should see a message box that displays your TEMP path. %temp% is a standard Windows environment variable.
Try msg "XYplorer.exe runs from <xypath>". <xypath> is a native XYplorer variable that resolves to XYplorer's application path.
Try msg "Press OK to copy the time!"; copytext "<date hh:nn:ss>". When the message box is OKed, the second command copytext is immediately executed and the current time is copied to the clipboard.
Try $a = "<curpath>"; msg $a. You should see a message box displaying the current path. First the variable $a is set to the current path, then it is used in the msg command.
Try $a = "Year " . "<date yyyy>"; msg $a. You should see a message box displaying "Year 2008" (or whatever the year might be when you try this). First the variable $a is set to two strings, one literal and one variable, concatenated by a dot, then it is used in the msg command.

What you have seen so far from XY scripting is:

There are commands consisting of a function name like msg or copytext, and arguments that can contain literals like "Hello!", and variables like %temp% (environment), <curpath> (XYplorer), or $a (user-defined).
An argument can have more than one part. The parts are concatenated by dots ( . ).
A command can have more than one argument. The arguments are separated by commas ( , ).
A script can have more than one command. The commands are separated by semi-colons ( ; ).

Where to put your scripts

Of course, the Try Script... dialog is just for playing and debugging. For everyday usage we need something better than that.

Let's start with Quick Scripting:

Ensure that "Quick Scripting" in Configuration | Advanced is on.
Now paste ::msg "Hello world!" into the Address Bar and press Enter. You should see a "Hello world!" message box.

As you see, Quick Scripting means: Scripts, when prefixed with "::", can be executed directly (i.e. quickly) through any interface in XYplorer that can process locations: Address Bar, Go To, Favorites, Catalog etc. This gives you a lot of choices for usage and storage of scripts.

Now, for mouse users, the Catalog is a very good place for scripts. Using the "::" prefix, scripts can be simply entered into the Location field of a catalog item. They are executed on a single click.

For example:

Add a new category "Scripts" and add a new item to it.
Set item's Location field to ::#1026 (screenshot) and save it. The icon turns into the script symbol.
Now click the item. The Find Files tab on the Info Panel is opened, all search filters are reset, and the cursor is placed into the Name field. Nice!

But how did this work? And what is #1026? In XYplorer almost every function has a fixed number, the function ID, by which it can be referred to in a script. ID #1026 happens to refer to "Miscellaneous / Find Files / Open Find Files and Reset". Open the Customize Keyboard Shortcuts dialog (menu Tools) and find this function in category Miscellaneous. At the bottom of the dialog you'll see a button showing the function's ID (screenshot). Clicking this button will copy the function's ID to the clipboard, making it easy to use it in a script.

Here's another simple but useful script. You could place it e.g. into the Favorite Folders menu by adding it via List Management (screenshot).

::rename "b", "*-<datem yyyymmdd>"
This little script will rename all currently selected items by appending the current date.

Of course, also longer scripts fit in a Catalog item or other location place, for example (screenshot):

::goto "Desktop|"; sortby "m", "d"; sel 1; focus "List";
This script goes to the Desktop folder (ensuring that the listing is unfiltered), sorts the list by date modified (descending), selects the first item, and moves the focus to the list.

Now, for passionate keyboarders, there are UDCs (User-Defined Commands). Using the "::" prefix, scripts can be simply entered into the Location field of a UDC Go To item (screenshot), which then can be assigned a keyboard shortcut to.

For example:

Click menu User | Manage Commands...
Select the category Go To, and click the New button.
Enter ::text "<clipboard>" into the Location field.
Assign a keyboard shortcut, say Ctrl+Alt+3.
Click Apply and OK.

Now press Ctrl+Alt+3. You should see a small window displaying the current textual contents of the clipboard.


Of course, you don't have to abuse the UDC Go To for scripts. There's also the UDC Run Script which accepts scripts without a prefixed "::", e.g. text "<clipboard>".

Run Script can also handle more advanced stuff like multi-line scripts (see image on the left), and multi-scripts, the rules and possibilities of which will be further explained below under "XYplorer Script Files". Here's just an appetizing preview:

goto "Desktop|"; // sort by modified date, descending sortby "m", "d"; // select first sel 1; focus "List";

What you have learned in this section about XY scripting is:

Scripts, when prefixed with "::", can be executed from anywhere where you also could enter a location term. This could be a Catalog item, or also e.g. a Favorite Folder
You can execute almost any function in XY in a script by referring to its function ID. E.g. #230 will pop up the submenu "New" of menu Edit.

Stepping Through Scripts

Suppose you have an older script #230, and you forgot what #230 refers to. What now? Very simple, enter stepping mode:
Open the Scripting menu and select "Step Through Scripts".
Now execute your mysterious script.

A small dialog will pop up and tell you what is about to happen (screenshot). You can now decide whether to execute the command, or skip it, or cancel the whole script. In stepping mode you are on the safe side. It is highly recommended when writing or debugging scripts!

There's also a toolbar button for toggling the stepping mode. When pressed (stepping is ON) its color changes to red to make the current state very clear.

XYplorer Script Files

Here we are talking popup menus that are user-defined by a text file. Let's make one:

Create a new text file in any editor.
Paste the following:
// some little test scripts "Go to C:\" goto "C:\" "Go to System Folder" goto "%winsysdir%" "Go to XYplorer Folder" goto "<xypath>"
Save the file as "test.xys" (XYplorer Script File) in XYplorer's application data path. In case you don't know that path: this script will bring you there: goto "<xydata>".
Now, in XYplorer, click menu Scripting | Load Script Files... and open test.xys. The following menu should pop up at your mouse cursor:

Now you can choose where you want to go.

A script file is basically a library of scripts. It is nothing more than a simple text file, which can contain one or more scripts. You will be able to either call one of those scripts directly, or simply load the entire file. In such case, XY will create a menu based on the contained scripts in that file and pop it up, allowing you to choose which script to execute.

The syntax for the scripts themselves within script files is exactly the same as for scripts anywhere else in XY since this is just another way to store and execute scripts.

Syntax rules for XYplorer Script Files

Lines starting with // are ignored and can be used for comments.
One script can run over multiple lines. Simply indent the lines after the first line using any number of space or tab characters.
You can have more than one script inside a script file. In that case, loading the script file will pop up a menu presenting all scripts inside the script file by their captions.
To set a script caption simply prefix the desired caption to the script, and wrap it in quotes.
Within a caption you may define a label that allows you to execute a script from a file directly.
Using the command sub in a script file you can execute other scripts inside the same file.
You may hide scripts by prefixing an underscore (_) to their caption.

To Load a Script File do one of the following:

Use menu Scripting | Load Script File...
Use a UDC from category "Load Script File".
Use the script command load [scriptfile].

The existence of a command load, of course, means that one script file can load another. You will get an idea of the potential of scripting by now...

Script Files for the Advanced

Labels

By using labels you can execute a script inside a file directly, avoiding the popup menu. The label is attached to the caption, separated by " : " (space-colon-space). For example:

// some little test scripts, using labels "Go to C:\ : croot" goto "C:\" "Go to System Folder : system" goto "%winsysdir%" "Go to XYplorer Folder : xy" goto "<xypath>"

If the above is saved to a file called "test.xys" in application data path then the following command will directly bring you to the System folder: load "test.xys", "system".

Hiding scripts inside a script file

Hidden scripts can be executed but are not shown in the script file's popup menu. To hide a script simply prefix an underscore to the caption or label (a hidden script does not need a caption anyway).

For example, create a script file "date.xys" in application data path with the following contents:

// this is in script file "date.xys" "_date" msg "<date yyyy-mm-dd>" "_time" msg "<date hh:nn:ss>" "Show Date : date" sub _date; "Show Date && Time : datetime" sub _date; sub _time

Now execute the script load "date.xys". The popup menu will show only two of the four contained scripts. Select either and see what happens.

Now run the script load "date.xys", "date". The script with the label "date" will be executed directly. It has only one command: sub "_date";. The sub command is a special command to call a script inside the same script file. In this case the hidden script with the label "_date" is called and executed. Its command msg "<date yyyy-mm-dd>" produces the message box showing the current date.

User-Defined Variables

Advancing in script writing, you will soon feel the need for variables. XYplorer allows you to define and use as many variables as you want, using a number of commands like set, input, replace, etc. The script $a = "Hi!"; msg $a; will define a new variable $a and assign the string "Hi!" (without the quotes) to it; then a message box will display "Hi!".

Variables are resolved wherever they are found in the arguments of all subsequent commands of the script, even if they are found inside quoted strings; for example:

$name = "Ted"; msg "Hi, I'm uncle $name!";

will display the message "Hi, I'm uncle Ted!".

Variables have to conform to the following rules:

Variables are represented by a dollar sign ($) followed by the name of the variable.
Names start with a letter or underscore, followed by any number of letters, numbers, or underscores.
Letters are a-z and A-Z.

Variable names are case-sensitive. The scope and lifetime of a variable begins and ends with the script where it has been defined.

Some Sample Scripts

backupto "D:\Archives\XY\<srcver>_<date yyyy-mm-dd>", "<xypath>\XYplorer.exe"
This little script backups the current XYplorer.exe to D:\Archives\XY\6.80.0080_2008-02-17. You can assign a keyboard shortcut to it, and/or add it to a drop-down menu with a caption of your choice.
"Super Reviews" moveto "D:\Archives\Reviews\Super" "Good Reviews" moveto "D:\Archives\Reviews\Good" "Completely Uninspired Trash (CUT)" moveto "D:\Archives\Reviews\Bad" - "Cancel"
This script will move all currently selected items to one of three locations, which are presented to you in a popup menu:

Just click and the move will reliably happen. No need to remember long paths anymore, to locate them on your hard disk, to drag'n'drop or copy'n'paste.
En passent, you see how to add a Cancel item to your script file menu.
input $q, "Query to replace."; input $t, "Text to replace Query with."; // rename of type search & replace, case-insensitive, and with preview rename "s", "$q/$t", "p"
Mass renaming deluxe. This script will prompt you for two strings and then replace one with the other in all currently selected file names.

Use Scripting for Reports

writefile("Report_<date yyyymmdd_hhnnss>.htm", report("<tr><td>{Name}</td> <td align=right>{Size B} {dir [DIR]|bytes|}</td> <td>{Created}</td><td>{Modified}</td></tr><crlf>", , "<table cellpadding=4>", "</table>"));
Generate an HTML table of the current folder and save it to Report_20081106_204344.htm (current date/time).

Sample output:

FindTemplates [DIR]2008-10-15 08:17:33
NewItems [DIR]2008-10-15 08:17:33
Scripts [DIR]2008-10-15 08:17:33
catalog.dat4.612 bytes2008-11-04 10:33:34
CatalogDefault.dat4.612 bytes2008-10-15 11:00:00
fvs.dat92 bytes2008-11-04 10:33:34
ks.dat8.224 bytes2008-11-04 10:33:34
LicenseXY.txt4.120 bytes2008-10-15 11:00:00
ReadmeXY.txt5.535 bytes2008-10-15 11:00:00
TipOfTheDay.htm20.120 bytes2008-10-16 07:51:58
udc.dat36 bytes2008-11-04 10:33:34
Uninstall.exe69.872 bytes2008-11-04 10:32:53
XYplorer.cnt1.244 bytes2008-10-15 11:00:00
XYplorer.exe3.096.576 bytes2008-11-04 10:32:18
XYplorer.hlp293.040 bytes2008-10-15 11:00:00
XYplorer.ini25.038 bytes2008-11-04 10:33:34
XYplorer.url49 bytes2008-11-04 10:32:53

Scripting Commands Reference

For a complete reference of all scripting commands see the Help file.

Scripting Resources

Here is a places where you can find free scripts to use and learn:

This page has been written 2008-03-06. The screenshots don’t reflect the current look of the application. Some of the functionality might have been changed or enhanced in the current version.