The scripting commands are documented in help of UltraEdit / UEStudio on page
Scripting commands. Just open the help, switch to the
Index tab, enter
Scripting commands and press RETURN, or use the online version by clicking on the link.
The standard taglist.uet file contains also lots of tags for inserting all the scripting commands with the various parameters. Just click on
View - Views/Lists - Tag List and select the tag group
UE/UES Script Commands to see them. Double clicking on an item in this list inserts the command with the parameters and places the cursor where you have to enter something (first). It is also possible to select a text in the script file before inserting a tag around the selection.
And standard wordfile.uew contains in the Javascript language definition also all special UltraEdit script commands and properties. So if you develop an UltraEdit script, the syntax highlighting, auto-correcting and auto-complete features can also help you to avoid typing mistakes. If you have disabled auto-completion, you can manually use it with Ctrl+Space after typing the first 2-3 characters of a command.
Common mistakes:- Script copied from a forum post does not work
If a script copied from a forum post does not do work, open Output Window by moving the mouse pointer over its tab in case of an auto-hided docked output window, or click in menu Window on Output Window to see it. Does it contain the following lines?
- Code: Select all
An error occurred on line 1:
Script failed.
Yes, then the script file is most likely not an ASCII file. The script file is most likely a Unicode file with a hidden BOM (byte order mark) at top of the file. Javascript interpreter does not support Unicode files. See next post for a step by step introduction on how to create and use a script posted in the forum.
- Backslashes in strings are not escaped
In Javascript the backslash \ in a string has a special meaning, see the Javascript tutorials. Therefore every backslash in a string must be escaped with an additional backslash character, for example "C:\\Temp\\Test.txt". When using a Perl regular expression search and searching also for a backslash, the backslash must be escaped for the Perl regular expression engine and then both backslashes must be escaped additionally with 2 backslashes because of Javascript string interpretation. Example:
- Code: Select all
// Define the Perl regular expression engine to use for regexp searches.
UltraEdit.perlReOn();
// Define once all search parameters (with downwards compatibility code).
UltraEdit.activeDocument.findReplace.matchCase=false;
UltraEdit.activeDocument.findReplace.matchWord=false;
UltraEdit.activeDocument.findReplace.regExp=true;
UltraEdit.activeDocument.findReplace.searchAscii=false;
UltraEdit.activeDocument.findReplace.searchDown=true;
if (typeof(UltraEdit.activeDocument.findReplace.mode) != "undefined")
{
UltraEdit.activeDocument.findReplace.mode=0;
}
if (typeof(UltraEdit.activeDocument.findReplace.searchInColumn) != "undefined")
{
UltraEdit.activeDocument.findReplace.searchInColumn=false;
}
// Find "C:\Temp\*.txt" in the current file (simplified).
UltraEdit.activeDocument.findReplace.find("C:\\\\Temp\\\\.*\\.txt");
- Define the working environment for your scripts
Whenever possible write your scripts without depending on internal defaults of UE/UES/UEm. Define once in your script all find/replace parameters before running the first find/replace. Define also always the regular expression engine once before running any search even when the search is a non regular expression search. And define the editing mode - insert or overstrike mode, normal or column editing mode, hex edit mode on or off.
- Missing round brackets on function call
Many functions do not require a parameter like
if (UltraEdit.activeDocument.isSel())
{
// Whatever should be done when there is a selection.
}
But the round brackets are required for every function call. Using if (UltraEdit.activeDocument.isSel) without the round brackets is valid Javascript code and does not produce an error, but the IF condition is now always true. Why?
Because using just the function name without the round brackets returns the value true or false depending on existence of function isSel which is true for all versions of UE/UES/UE3/UEm/UEM/UEX supporting scripts. In other words a function name without round brackets is a test if the function is defined when executing the current script. This can be used to make script downwards compatible as demonstrated by some of the user contributed scripts like HexCopy.js or MergeTextFiles.js (see script section of Extra Downloads), but missing round brackets after a function name are often just a mistake.
- Passing a number to one of the write functions instead of a string
All write functions (commands) require that the passed parameter is a string. Javascript automatically converts values of number or boolean variables to a string when concatenating a string (defined in the script code or value of a string variable) with the value of a number or a boolean variable. So for example
var nFileCount = 20;
UltraEdit.activeDocument.write("File count is: "+nFileCount);
var sMessage = "Number of files is: ";
UltraEdit.outputWindow.write(sMessage+nFileCount);
is absolutely valid code because the Javascript engine converts the value of the number variable first to a string, then concatenates the two strings and passes the resulting string to function write. But using
var nFileCount = 20;
UltraEdit.activeDocument.write(nFileCount);
does not work because the value of the number variable is passed as integer value and not as string to function write. The solution is to use explicitly the method (function) toString() to convert the value to a string before passing it to the function write as shown below:
UltraEdit.activeDocument.write(nFileCount.toString());
- First element of document array has index 0, but property length is the number of opened documents starting with number 1
Often a script code is executed on all opened files like
for (var nDocIndex = 0; nDocIndex < UltraEdit.document.length; nDocIndex++)
{
// Whatever should be done on all opened files.
}
Important here is that nDocIndex < UltraEdit.document.length is used and not nDocIndex <= UltraEdit.document.length because the document index numbering starts with 0, but the number of elements of an array (= number of opened files for the document array) starts with 1.
- Opening a file already opened from within script does not result in reloading file content and making the file active
When a file is already opened and modified and you open this file again, a message prompt is shown asking you if you want to reload the file and loose all changes. Whatever you choose the result is that the re-opened file is the active one. When a file is opened and not modified and you re-open it, the file just becomes the active one.
But the behavior for opening a file which is already opened using the script command UltraEdit.open(""); is completely different (currently). If the file is already open, nothing is done. The file content is never reloaded and also the file becomes never active. So when your script contains the command UltraEdit.open(""); it should always check before if the file to open is not already opened in UE/UES/UEM/UEP. This can be done using function GetFileIndex and the IF condition in your script:
- Code: Select all
function GetFileIndex (sFullNameOfFile)
{
// Is the passed value not a string because simply nothing passed?
if (typeof(sFullNameOfFile) != "string")
{
// With UltraEdit v16.00 and later there is a property which holds active document index.
if (typeof(UltraEdit.activeDocumentIdx) == "number") return UltraEdit.activeDocumentIdx;
sFullNameOfFile = UltraEdit.activeDocument.path;
}
else if (!sFullNameOfFile.length) // It is a string. Is the string empty?
{
if (typeof(UltraEdit.activeDocumentIdx) == "number") return UltraEdit.activeDocumentIdx;
sFullNameOfFile = UltraEdit.activeDocument.path;
}
// Windows file systems are not case sensitive. So best make all file
// names lowercase before comparing the name of the file to search
// for with the names of the already opened files. Users of UEX should
// use a case sensitive file name comparison and therefore don't need
// toLowerCase() here and in the following loop.
var sFileNameToCompare = sFullNameOfFile.toLowerCase();
// Compare the name of the file to search for with the (lowercase) file
// names of all already opened files. Return the document index of the
// file already opened when found.
for (var nDocIndex = 0; nDocIndex < UltraEdit.document.length; nDocIndex++)
{
if (UltraEdit.document[nDocIndex].path.toLowerCase() == sFileNameToCompare)
{
return nDocIndex;
}
}
return -1; // This file is not open.
}
- Code: Select all
var nActiveDocIndex = GetFileIndex(sFileNameToOpen);
if (nActiveDocIndex < 0) UltraEdit.open(sFileNameToOpen);
else
{
UltraEdit.document[nActiveDocIndex].top();
UltraEdit.document[nActiveDocIndex].setActive();
}
BTW: Function GetFileIndex is just a more general version of getActiveDocumentIndex which returns the same result when calling GetFileIndex without any parameter or with an empty string.
- Closing a file does not make any other file active
When closing a file manually, the last active file or the file with the nearest open file tab left the just closed file or another file according to configuration setting After current tab is closed, move to: (UE v16.20 and later) becomes automatically active. But this does not happen when closing a file from within a script. The command UltraEdit.document[nIndexOfNewActiveFile].setActive(); must be used to make a file active after closing a file.
Extra hint: Avoid closing files with a document index number lower the document index of the active file, especially when the script works with multiple documents at once. The effects on the document array are currently unpredictable.
- UltraEdit.activeDocument.isEof() returns true only when the cursor reaches the end of file
Function UltraEdit.activeDocument.isEof() returns only boolean true when the cursor in the file reaches the end of the file. When using the find/replace command in a loop to do something from top of the file to end of the file, the command UltraEdit.activeDocument.isEof() can't be used as exit condition for the loop because the cursor is not changed when no string is found anymore. Use the result of the find/replace itself to exit the loop when the find/replace could not find a string anymore, see also next point.
- Find/Replace are always only from current cursor position to end/top of file
All searches and replaces from within a script (or macro) are always executed only from current cursor position to end of file (searching downwards) or top of the file (searching upwards). The configuration setting Continue find at End of File and the replace all option Replace All is from top of file are never active for finds/replaces executed from within a script (or macro) to avoid endless loops. If you want to search/replace something in entire file, simply move the cursor first to top of file using script command UltraEdit.activeDocument.top(); respectively UltraEdit.document[x].top();
- UltraEdit.activeDocument.key("DOWN ARROW"); can result in an endless loop
When working on a file with a script line by line using command UltraEdit.activeDocument.key("DOWN ARROW"); in a loop and UltraEdit.activeDocument.isEof() == false as loop condition make sure that the last line of the file has also a line termination or the cursor never reaches the end of the file and therefore the result is an endless loop. You can use following code:
- Code: Select all
// Move cursor to end of the file.
UltraEdit.activeDocument.bottom();
// Is the cursor not at column 1, the last line has no line termination.
if (UltraEdit.activeDocument.isColNumGt(1))
{
// Inserting a line below at end of file inserts the line termination
// character(s) depending on the type of line terminators of this file.
UltraEdit.activeDocument.insertLine();
// If the last line of the file has preceding whitespaces (spaces/tabs)
// and auto-indent feature is enabled, the inserted line has now also
// the same number of spaces/tabs. Those inserted whitespaces must be
// deleted to get just the line termination at end of the file.
if (UltraEdit.activeDocument.isColNumGt(1))
{
UltraEdit.activeDocument.deleteToStartOfLine();
}
}
UltraEdit.activeDocument.top();
while (UltraEdit.activeDocument.isEof() == false)
{
// Whatever should be done on this line.
UltraEdit.activeDocument.key("DOWN ARROW");
}
