Scripting #

Scripts can be used to automate certain tasks with Dynamo-Browse. They can also be used to define new commands or key bindings.

Scripting Basics #

Dynamo-Browse scripts are written using the Tamarin scripting language, which looks a lot like Go. All features of the language are available in Dynamo-Browse.

The typical “hello world” script for Dynamo-Browse is below:

ui.print("Hello, world")

This uses the ui package, which is the package used to interact with the Dynamo-Browse user interface. A full list of supported packages can be found in the Script API reference, along with the builtins and packages supported by Tamarin itself.

Note: the ext package is only available to Extension Scripts.

To execute this script, use the run-script command:

run-script /path/to/script/hello.tm

You’ll see that the message “Hello, world” will appear in the status bar of Dynamo-Browse.

Any print or printf messages will be written to the debug log with the prefix script <filename>. The debug log is turned off by default, but it can be enabled using the -debug flag on launch.

Scripts loaded using the run-script command are for ad-hoc automation tasks that are not necessarily designed for repeated use. These ad-hoc scripts are executed, then immediately unloaded, and are not generally allowed to extend Dynamo-Browse. In order to do so, you will need to write an Extension Script.

Extension Scripts #

Extension scripts are scripts designed to extend Dynamo-Browse in some way, such as with new commands or key bindings. They are traditionally loaded on startup and exist in the predefined “script” directory. They are usually designed for repeated operations, including those that can be bound to command name or keys.

The following is an example script which will define a “goto” command. When invoked, the script will prompt the user for the value of the partition key. It will then perform a query over the currently viewed table for any rows with that partition key. If no error occurred, the results of the query will be shown to the user.

// Define a new "goto" command, which can be invoked when the user presses ':' and types in 'goto'
ext.command("goto", func() {
    // Use the information of the current table to get the name of the partition key.
    pkName := session.current_table().keys["partition"]

    // Prompt the user for the value to go to.  The user can press Esc, which will cancel
    // the input and return 'nil'.
    keyVal := ui.prompt(pkName + "? ")
    if keyVal == nil {
        return nil
    }

    // Run a query over the DynamoDB table for any rows with the partition key.  Notice
    // the use of the 'args' option, and the presence of both the name prefix (':key')
    // and value prefix ('$val').
    res := session.query(":key = $val", {
        args: {
            key: pkName,
            val: keyVal,
        },
    })
    
    // The query method will return either an error or a result.  If it's an error, print
    // a notice and exist.
    if res.is_err() {
        ui.print("Can't goto: " + res.err_msg())
        return nil
    }

    // If no error, unwrap the result object to get the result-set returned from the query.
    // Then change the current result-set to this one.  This will change the result-set the
    // user is currently seeing.
    session.set_result_set(res.unwrap())
})

To load an extension script, use the load-script command:

load-script script.tm

The script must exist in the “script” directory, which by default is:

$HOME/.config/audax/dynamo-browse/scripts