API: Contents vs Value

Abstract: A bug displaying macro text in the Compare Entities window is fixed by recognizing the difference between the contents() and value() API calls.

Did you know we have a compare entities window? You can find it under the top-level Compare menu and it looks like this (with the Fastgrep sample project).

The compare Entities window, available from Compare->Compare Entities

It looks pretty boring on the first open, but it can be interesting. For example, FastGrep actually has three main functions. Is this a case of duplicated code? You can check by easily comparing them side by side!

Comparison of two of the main functions in FastGrep

Turns out they’re not duplicates. But, if you start playing around with the feature, you might notice a problem. All those macros in the initial list (ALTSIZE, ANY, ANYBUT, and so on) are blank in build 1080. What was wrong?

To answer that question, let’s take a look at the Perl/Python APIs. The text for the entity is retrieved with the equivalent of the entity.contents() function. If you don’t feel like running your own script, you can see what the API would return with the interactive report “API Info”. This report is crucial for anyone using our APIs, it shows the exact information the APIs will return for any entity in your project.

Let’s look at the API information for a macro.

Accessing the API Info report
Result of the interactive report “API Info” for the macro FAIL in FastGrep

The contents section is blank. No wonder nothing shows up. What we actually want for macros is the value (the last line) instead of the contents. It turns out we were using the wrong field ourselves in the Compare Entities window! We fixed this with Build 1081 so you can compare macros like the other functions and files.

Macro comparison in the FastGrep project

You can also apply this new wisdom in your own scripts. Entities like files and functions have contents. Entities like macros and variables have values. Why the distinction? Contents are calculated on-demand from begin and end references, so if you delete the file on disk, you can’t retrieve the contents for an entity. Values are stored in the database.