Skip to content
SciTools Blog
Menu
  • Home
  • Blog
  • Support
  • Contact
  • Login
  • Pricing
  • Free Trial
Menu
gold and silver round frame magnifying glass

API: Contents vs Value

Posted on October 1, 2021

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.

  • Instagram
  • Facebook
  • LinkedIn
  • Twitter
  • YouTube

Learn more about Understand's Features

  • Dependency Graph
    View Dependency Graphs
  • Comply with Standards
  • View Useful Metrics
  • Team Annotations
  • Browse Depenedencies
  • Edit and Refactor

Related

  • API
  • Architectures
  • Business
  • Code Comparison
  • Code Comprehension
  • Code Navigation
  • Code Visualization
  • Coding Standards
  • Dependencies
  • Developer Notes
  • DevOps
  • Getting Started
  • Legacy Code
  • Licensing
  • Metrics
  • Platform
  • Plugins
  • Power User Tips
  • Programming Practices
  • Uncategorized
  • Useful Scripts
  • User Stories
  • May 2025
  • January 2025
  • December 2024
  • November 2024
  • August 2024
  • June 2024
  • May 2024
  • March 2024
  • February 2024
  • January 2024
  • December 2023
  • November 2023
  • October 2023
  • September 2023
  • August 2023
  • June 2023
  • April 2023
  • January 2023
  • December 2022
  • November 2022
  • September 2022
  • August 2022
  • May 2022
  • April 2022
  • February 2022
  • January 2022
  • December 2021
  • November 2021
  • October 2021
  • September 2021
  • August 2021
  • July 2021
  • June 2021

©2025 SciTools Blog | Design: Newspaperly WordPress Theme