XYplorer scripting, introduced with version 7.00, offers the ultimate in file management efficiency. Roll your own custom commands, combine them into scripts, wrap them into an XY Script file (XYS) or a User-Defined Command, and execute them with a single click or keystroke. Can't get better than that? Sure it can! Share scripts with colleagues or download them from the web: Just drop a script file into your application folder and you have fresh plug-in commands at your fingertips.

Without a doubt, scripting is an advanced feature that only pays off if you take the time to dive in and explore the possibilities. However, you'll find that it's not rocket science at all.

What can scripting do for me anyway?

Before we go any further, here are some of the truly wonderful things that scripting can do for you:

Create a fully formatted HTML document containing the list of files you are currently viewing 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 in the currently selected text file with a single click.
Transfer the contents of your digital camera's SD card to the new folder, renamed with today's month, with a single click.
With a single click, you can back up all of last year's .doc files to a zip file named
Seamless TeraCopy / FastCopy / etc integration.
Download a specific file from the Internet without using a browser.
Open the first URL 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 simple warm-ups:
Select menu Scripting | Try Script...
Paste msg "Hello world!"; into the edit box.
Click OK.

You should now see a "Hello world!" message box. Congratulations, you have just written 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 OK'd, 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 with the current path. First, the $a variable 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 that says "Year 2024" (or whatever the year is when you try this). First, the $a variable is set to two strings, a literal and a variable, concatenated by a period, and then used in the msg command.

What you have seen so far of XY scripting is:

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

Where to put your scripts

Of course, the Try Script... dialog is only for playing and debugging. For everyday use, we need something better.

Let's start with Quick Scripting:

Type ::msg "Hello world!"; in the address bar and press Enter. You should see a "Hello world!" message box.

As you can 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 options for using and storing scripts.

For mouse users, the catalog is a very good place for scripts. Using the "::" prefix, scripts can simply be entered in the location field of a catalog element. They are executed with a single click.

For example:

Create a new category "Scripts" and add a new item to it.
Set the item's Location field to ::#1026 (screenshot) and save it. The icon changes to the script icon.
Now click on the item. The Find Files tab of the Info Panel will open, all search filters will be reset and the cursor will be placed in 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 or command 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 (Tools menu) and find this function in the Miscellaneous category. At the bottom of the dialog you'll see a button with the function's ID (screenshot). Clicking this button copies the function ID to the clipboard for easy use in a script.

Here's another simple but useful script. You could place it in the Favorite Folders menu, for example, by adding it from the List Management dialog (screenshot).

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

Of course, longer scripts can also fit into a catalog item or other location (screenshot):

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

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

User menu showing the newly added command.

Another 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 text content of the clipboard.

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

Run Script can also handle more advanced stuff like multi-line scripts, 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";

The above script in a screenshot.

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

Scripts with a "::" prefix can be executed from any location where you could also enter a location term. This could be a catalog item, or even a favorite folder.
You can perform almost any function in XY in a script by referring to its function ID. For example, #230; will display the New submenu of the Edit menu.

Stepping Through Scripts

Suppose you have an older script #230; and you forgot what #230 refers to. What do you do now? Simple, go into step mode:

Open the Scripting menu and check "Step Mode".
Now execute your mysterious script.

The Scripting menu, Step Mode checked.

A dialog will pop up telling you what is about to happen (screenshot). You can now decide whether to execute the command, skip it, or abort the entire script. In step 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.

Step Mode off.

Step Mode on.

XYplorer Script Files

We are talking about 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>".
In XYplorer, click on the Scripting | Load Script Files... menu and open test.xys. The following menu should appear at your 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 that can contain one or more scripts. You can either call one of these scripts directly or just load the whole file. In the latter case, XY will create a menu based on the scripts contained in this file and pop it up, allowing you to choose which script to execute.

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

Syntax rules for XYplorer Script Files

Lines starting with // are ignored and can be used for comments.
A script can run across multiple lines. Just indent the lines after the first line with any number of spaces or tabs.
You can have more than one script in a script file. In this case, loading the script file will display a menu that lists all the scripts inside the script file by their titles.
To set a script caption, simply prefix the script with the desired caption and enclose it in quotation marks.
Within a caption, you can define a label that allows you to run a script directly from a file.
You can use the sub command in a script file to run other scripts within the same file.
You can hide scripts by prefixing their names with an underscore (_).

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].

Of course, the existence of a load command means that one script file can load another. You should be getting an idea of the potential of scripting by now...

Script files for the advanced


You can use labels to execute a script directly inside a file, bypassing the pop-up menu. The label is appended 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 in a file named "test.xys" in the application data path, the following command will take you directly to the System folder: load "test.xys","system".

Hiding scripts inside a script file

Hidden scripts can be executed, but are not displayed in the popup menu of the script file. To hide a script, simply prefix the caption or label with an underscore (a hidden script does not need a caption anyway).

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

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

Now run the script load "date.xys". The popup menu will only show two of the four scripts it contains. Select one of them and see what happens.

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

User-Defined Variables

As you progress in writing scripts, 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 occur in the arguments of all subsequent commands in the script, even if they occur within quoted strings; for example

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

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

Variables must conform to the following rules:

Variables are represented by a dollar sign ($) followed by the variable name.
Names begin 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 in which it is 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 moves all currently selected items to one of three locations presented in a pop-up menu:

One click and the move is done. No more remembering long paths, finding them on your hard drive, drag'n'drop, or copy'n'paste.
In passing, you will see how to add a Cancel item to your script file menu.
$q = input("Query to Replace:"); $t = input("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 ask you for two strings and then replace one with the other in all currently selected filenames.

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, refer to the Help file.

Scripting Resources

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

This page was last updated on 2024-01-11. Screenshots do not necessarily reflect the current look and feel of the application. Some of the functionality may have been changed or enhanced in the current version.