This article is part of a series on using the Understand API.
Interactive Reports are special Perl scripts that create a text-based window in Understand to display information of your choosing. They can reference the entire Project, a given Architecture, or a specific entity, and they can be as simple or complex as your imagination. Here is an IReport that ships with Understand that shows all the API information available for the selected entity. To see it yourself just right click on an entity and select Interactive Reports->API Info
Building a File Complexity Report
Let’s build a sample interactive report to display the most complex functions and files in your project. You can download the completed plugin from here.
To install a plugin, simply drag the .upl file into the Understand GUI, or you can manually place it in one of the following locations:
Windows – e.g. C:\Program Files\SciTools\conf\plugin\User\IReport
Mac – e.g. /Users/username/Library/Application Support/SciTools/plugin/IReport
Linux – e.g. /home/username/.config/SciTools/plugin/IReport
Start by creating a new plugin file fileComplexity.upl, you can start from an empty file, or you can modify the IReport Template which is a simple example with a lot of explanatory comments.
The first part of creating the plugin is some setup. We define as %files hash to store our project files. The required subroutine name defines the name of our report. The three test_ subroutines determine if this iReport will work for entities, architectures, or as a project-wide, global report.
Next we initialize a few options for the person running the report to specify – a complexity threshold, how many files to report, and an option to either show the full path of the file or not.
Refer to IReport Template for more examples on report options.
The next step is to define the generate subroutine. Generate will be called once, after init, and perhaps additional times if the report is regenerated (perhaps with new option settings). The first thing we do is delete any files from a previous report. If we don’t then we may end up with duplicates in our hash. It’s best practice to clear your data structures before using them anyways.
Next we check which kind of report Understand will generate. Reports can run on three different flavors – entities, architectures, and global. An entity is anything in the code that Understand captures information on: i.e. A file, a class, a variable, a function, etc. Architectures would be your file system or folders. Everything else is global. This reports focuses on architectures and global. $arch and $ent are passed into the generate command if the report is created by right clicking on either.
The final line in generate is very important for Understand. Printing a newline character flushes the buffer and the result is actual text on screen. To ensure everything gets on screen, we wrote this line at the end of our main subroutine.
Now lets define generate_global. Because this function was called in global we have to access the database with $report->db() Then we can call $db->ents( "File" ) to get a list of @files. For each $file we save the “MaxCyclomatic” value to a hash of %files.
The next subroutine generate_arch is very similar to generate_global. The key difference here is the recursion to get files from all of the architecture’s children. Entities in an architecture are basically the files. So we call $arch->ents() to get that list of files. $arch->children() returns a list of children in the architecture.
Now let’s define another function eval_and_print. This functions job is to print as many files that are either specified in the number of files to report or the number of files that exists an architecture. We start by initializing a new hash %funcs and then sort the files.
For each $file, we call eval{} or do{} because the $fileCount may be greater than the length of %files to report. If the $fileCount is greater than length of %files then we catch that and print nothing to the screen. Next, the $file is printed then a list of functions is retrieved from the $file. For each function, a cyclomatic complexity value is saved in a hash of function entities.
Finally, the hash of function entities is sorted by cyclomatic value. Then each function is printed.
If you take a look in the two print functions at the bottom of the file you will see something like $report->entity( $func ) or $report->entity( $file ) – this links the following text to the entity. You can then do things like hover or double click the text to navigate to that entity.
That should be it. You should now be able to Select Reports->Interactive Reports ->File Complexity to view your report. If there are any problems or errors you can run the following from the command line to report syntax errors uperl -c fileComplexity.upl. Now you should be able to make your own reports, let us know if you run into any questions or issues, we’re happy to help!
Final Thoughts
These tutorials try to cover some of the high level concepts with the Understand APIs as well as some small examples. However they just scratch the surface of what you can do. We recommend looking at some of the Perl and Python API samples that ship with Understand in the Scripts folder for more ideas and examples. Also more in depth API documentation is available in our manuals section. If you get stuck, just send us an email at support@scitools.com, we’re always happy to help.