Using Scripts in BinNavi
Overview
To execute scripts written in languages like Python or Ruby, BinNavi provides a simple dialog where you can enter and execute these scripts. This dialog is accessible both from the main menu of the main window and from the main menu of each open graph window.
The scripting dialog has two modes that behave differently. The first mode is the so called console mode. In this mode the scripting dialog provides an input field that behaves like a console. The second mode is the edit mode. In this mode the script input field behaves like a text editor.
Furthermore, the scripting dialog provides features like the ability to load and save scripts, the ability to undo/redo changes, and the ability to work with the system clipboard.
How to use the scripting dialog
By default the scripting dialog opens with a single console mode scripting tab. In console mode you can enter one or more lines which are executed as soon as you hit CTRL-ENTER.
Executing scripts in edit mode is a bit different from executing scripts in console mode. To execute a script in edit mode, you have to click the Execute Script button in the lower right corner of the dialog.
It is important to know that by default there is an object called navi available in the scripting console. This object is used to access BinNavi. The following other pre-defined objects are also available in scripts executed from the scripting dialog.
- dbs: A shortcut for navi.getDatabaseManager().getDatabases()
- cdb: Database where the current graph is stored (only available in scripting dialogs started from a graph window)
- cg: View2D object that can be used to access the current graph (only available in scripting dialogs started from a graph window)
- cf: GraphFrame object that represents the graph window from where the scripting dialog was started (only available in scripting dialogs started from a graph window)
To find out exactly what BinNavi functions and objects are available from scripts, please refer to the Plugin API documentation. All parts of the plugin API are available from scripts too.
Standalone Scripting
Since BinNavi 2.1 it is also possible to write stand-alone scripts that can be run from the commandline without having to start BinNavi itself. An example (standalone_skeleton.px) of a standalone Jython script can be found in the BinNavi/scripts directory.
In theory it is also possible to write stand-alone scripts in languages other than Jython (especially JRuby) but this was never tested.
Additional Information
It is possible to define scripts that are automatically executed whenever a console mode script tab is opened. This is useful to automatically import files or classes that are often used in the scripting console. These initialization scripts can be found in the scripts/lib subdirectory of your BinNavi installation. Please read the readme.txt file in that directory to find more information about this feature.
Notes on writing Ruby scripts
- The plugin interface object is not called navi but $navi
- Java methods like set*/get* have their get/set dropped from the name. E.g. use $navi.databaseManager instead of $navi.getDatabaseManager
Notes on writing Python scripts
Since the Jython engine does not redirect output automatically all BinNavi scripts written in Python that are supposed to display output in the Scripting dialog must redirect output manually. This can be done using the following two lines at the beginning of a script:
import sys sys.stdout = SCRIPT_CONSOLE
- Java methods like set*/get* are available without get/set prefixes. Parentheses are optional too. This allows the use of navi.databaseManager instead of navi.getDatabaseManager()
Examples
Please refer to the scripts subdirectory of your BinNavi installation for sample scripts.