Macros Overview

Several Hex Editor Neo components can be controlled automatically. Application programming interfaces they expose can be utilized by scripts running inside Hex Editor Neo.

This section describes macro support in the editor, also known as “internal scripting”. Hex Editor Neo also supports so-called external scripting, which allows external code to execute basic file editing algorithms without launching Hex Editor Neo.

Application Programming Interfaces (APIs) exposed for internal scripting and external scripting are not compatible between each other. External APIs must be compatible with OLE Automation and must support old version of JavaScript (pre-ES5) and therefore are quite limited. Internal APIs, on the other hand, are used by controlled environment inside the Hex Editor Neo, support latest versions of TypeScript and asynchronous execution.

The terms “scripts” and “macros” will be used interchangeably in this documentation section and will refer to scripts running inside the Hex Editor Neo.

Macro Support

Currently scripts running inside Hex Editor Neo may do the following:

• Control the general application tasks through the methods and properties of the Global Object. For example, the user may create new documents, open documents, activate and close windows, open settings pages and import or export application configuration settings.
• Control the opened documents through the methods and properties of the Document Object and Document View Object. Almost all document and editing actions may be performed using scripting.
• Control the Find in Files feature.

The unique Macros » Start Recording command may be used to start automatic recording of user actions. When Macros » Stop Recording/Playback command is later executed, a new macro is created. The user may give a name to macro, set its hotkey and optionally open the macro' script for editing.

Editor Support

The built-in script file editor allows the user to open script files and edit them. The editor provides full syntax coloring. It also supports automatic method completion, displays brief method and parameter documentation and lists all possible overloads, if any. The editor also supports placing and controlling break points.

Debugging

Hex Editor Neo contains a built-in Script Debugger which will greatly simplify macro development. It supports asynchronous script breaking and breakpoints. When in break state, Debug Watch Tool Window and Debug Call Stack Tool Window may be used to study the current execution state.

Asynchronous Execution

Many methods may potentially execute for a very long time, if they are instructed to operate on very large data block or complex multiple selection object.

By convention, names of all such methods end with Async and return a TypeScript Promise object. You generally has to await a result of an asynchronous operation before continuing.

Promise completion can either be successful (and optionally provide a result, unless it is Promise<void>) or erroneous, in which case an exception is thrown.

User script may use the await keyword to wait for completion and get the result of an asynchronous operation, or use the Promise.then or Promise.catch methods to schedule a continuation or error handler.

Awaiting Promises

async function foo()
{
    // await allows the control flow to be nice and "synchronous"
    try
    {
        var occurrences = await activeView.findAllAsync(...);
        alert(occurrences + " occurrences found");
    } catch(e)
    {
        alert("Error occurred: " + e);
    }
}

function bar()
{
    // traditional, "callback" style
    var operation = activeView.findAllAsync(...);
    operation.then(occurrences => {
        alert(occurrences + " occurrences found");
    }).catch(e => {
        alert("Error occurred: " + e);
    });
}