How to Find a Specific Text in ObjectScript

You probably know this situation:
Some time ago, you found a very special $ZU function for a very specific type of problem. Some kind of mystical formula. It became popular and was used by many developers throughout your code and across all your installations.

Several versions and updates later, you are informed by ISC that your mystical $ZU is deprecated and no longer supported. You are advised to replace it with a new $something().

So, how do you find and document the usage of this mysterious code?
It might be located in classes, in MAC, INT, or INC code.
It can also be spread across multiple namespaces.
In the past, Studio was not yet complete: it was poorly suited, slow, and inaccurate.

I have encountered this situation more than once in different installations.
Source Control was not available at the time, and was only rarely used when it was eventually introduced.

Since ObjectScript was the only possible choice to tackle this challenge, I wrote my own utility.
My solution evolved over the years, and once the migration to IRIS was planned, I checked once again how useful it still was.
And because it was written in pure ObjectScript, it worked in IRIS without a single character needing to be changed.
As you may know, the problem of searching for a specific piece of text in ObjectScript has not changed.

My personal goals for this utility were:

• ObjectScript only
• no fancy, miraculous, or fragile constructions
• as few $advanced functions as possible
• favor readability over elegance for the sake of future maintenance
• display the number of occurrences counted per namespace and per code element
• for classes, also distinguish between:
  • parameters
  • properties (if calculated)
  • methods
  • indices
• an option to show the line containing the occurrence
• no concern for listing output:
  • any terminal program can write a log
  • bash has STDOUT for that purpose

This utility is therefore available to you on Open Exchange and GitHub.
I also created a video to demonstrate the tool in action.
It is also available on the Demo Server.

Simply start it from the terminal:
user>DO ^rcc.find

You will then be prompted with a few questions:

• what text are you searching for?
• Verbose?
  • do you want to see every full line containing your text?
  • warning: this can become a very large listing
  • a recent test found more than 90,000 matches
  • with verbose=1, you will get more than 90,000 lines
• Uppercase only?
  • this solves the problem of functions being written
  • in uppercase, lowercase, or mixed case
  • "Uppercase=1" ensures you do not miss any occurrence
• Which code type do you want to scan? (CLS, MAC, INT, INC, ALL)
• Which namespace do you want to search?
  • a specific namespace from your list or ALL
  • for ALL, you get a condensed list of namespaces and types
  • (not visible in the video)

Selecting the namespace starts the scan.
Let’s dance!

USER> do ^rcc.find
----------------

enter search string [$ZU] <blank> to exit: RCC
          Verbose? (0,1) [0]:
          Force UpperCase? (1,0) [1]:

enter code type (CLS,MAC,INT,INC,ALL) [ALL]: CLS

select namespace (ALL,%SYS,DOCBOOK,ENSDEMO,ENSEMBLE,SAMPLES,USER) [USER]:

** Scan Namespace: USER **

** CLS **
** 2      User.ConLoad
** 15     User.Main
** 3      csp.form
** 3      csp.winner
** 2      dc.rcc.Contest
** 37     dc.rcc.Main
** 1      dc.rcc.Prize
** 63 CLS **
----------------

I hope you enjoyed my story.
I tried to avoid boring code listings, that’s what Open Exchange and GitHub are for.

And please excuse my rusty French.
I learned it at school many years ago, where the focus was on literature (Molière, Sartre, Queffélec, Anouilh, Ionesco) rather than technology.