Getting Started with the Perl API
Understand includes a PERL API which allows you to directly query the Understand database. If you want to create your own report, or gather information in a manner that we didn’t foresee in Understand, you can access the information yourself via the API. The API can be accessed in several different ways: most of the scripts are designed to be run from Understand’s GUI on the currently opened database. They can also be run from the command line, and some plugins are designed to interact directly with Understand.
Run Scripts in Understand
To run a script from inside of Understand, use Tools->Run a Command, configure any necessary parameters, and hit run. The resulting output can then be double-clicked to visit the referenced source.
Run Scripts from the Command Line
Scripts can be run from the command line using uperl, a special PERL executable included in Understand’s bin directory. To run a script from the command line, specify the script, the database and any options:
uperl scriptName.pl -db myproject.udb [Options]
So to run this same script from the command line, you could use the following command:
Using your own Perl Installation
If you would rather access the Understand API from your own customized Perl 5.28.0 installation, just add <SciTools>/bin/pc-win32/Perl/STI to your Perl include path, on OSX the default path to uperl is /Applications/Understand.app/
Use Understand Plugins
Plugins are special Perl scripts written specifically to interact with the Understand GUI. You can quickly tell them apart by the file extension: regular scripts use .pl while plugin scripts use .upl. Plugins give you the power to interact with specific entities inside of Understand, for example you can right click on an entity and run a custom (interactive) report on it, or generate your own graph.
Plugins are installed by dragging and dropping them into the Understand GUI or placing them in the Scitools/conf/plugins folder. Once installed they will show up in the context menu or in the main menu depending on the type of plugin.
Several of the graphs included in Understand are actually plugin scripts as well, including the control flow graph and the butterfly graph. They can be customized, or used as a starting point for creating your own graphs.
Write Your Own Scripts
We have many tutorials for helping get started with the API:
- Part 1: Writing Your First Script
- Part 2: Entities and References
- Part 3: Lexers and Lexemes
- Part 4: Custom Graphs
- Part 5: Interactive Reports
For more details, refer to the Perl API documentation under the Help menu in Understand, or here.
Sample Scripts
The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/scripts/perl folder.