The merits of an example main program

When I write a new routine in IDL—a procedure or a function or a class—I like to include a main program at the bottom of the file. I use the main program to

• demonstrate the calling syntax of the routine
• give an example of how the routine is used
• define a simple unit test (or tests)

I first saw this idea used in Python and I’ve copied it for my work in IDL. For example, here’s the full code listing for a simple function, FLATTEN (which converts a multidimensional array into a vector) along with an example main. The programs are saved in the file flatten.pro, in a directory in IDL’s path.

; docformat = 'rst' 
;+ 
; A convenience routine that flattens/linearizes a 
; multidimensional array. 
; 
; :params: 
;  x : in, required, type=any array 
;   An array of any type to be converted to a vector. 
; 
; :author: 
;  Mark Piper, VIS, 2011 
;-
function flatten, x
   compile_opt idl2

   nx = n_elements(x)
   return, nx gt 0 ? reform(x, nx) : 0
end

; Example
a = indgen(5, 7)
b = flatten(a)
c = reform(a, n_elements(a))
help, a, b, c
print, 'Equivalent results? ', array_equal(b, c) ? 'Y' : 'N'
end 

By examining the main program, you can see how FLATTEN works; here, it’s used to convert a 5 x 7 array into a 35-element vector. To use the main program as an example, I execute it from the command line with the .run executive command:

IDL> .r flatten
% Compiled module: FLATTEN.
% Compiled module: $MAIN$.
A               INT       = Array[5, 7]
B               INT       = Array[35]
C               INT       = Array[35]
Equivalent results? Y

The .run command compiles both routines and executes the main program. We’d get the same behavior from the Run button (or the F8 keyboard shortcut) in the IDL Workbench. Note that—and this is important—the calling mechanism still resolves the FLATTEN function (by itself) correctly:

IDL> .reset
IDL> x = indgen(2,3)
IDL> print, x
      0       1
      2       3
      4       5
IDL> y = flatten(x)
% Compiled module: FLATTEN.
IDL> print, y
      0       1       2       3       4       5

This means that (as intended) FLATTEN can be used as a library routine independent of its example main program. I find this technique of including an example main to be especially useful with functions, which won’t execute with the Run button on the Workbench. (This may be a topic for another post, where I'd like to argue for an implicit redirect to !null for functions; e.g., FLATTEN could be called like this:

IDL> flatten(x)

without throwing a syntax error.) Note: ENVI 5 was released this week. It has a new UI and a new API. The API still uses IDL, but with an object-oriented interface. Though I'm not a heavy ENVI user, I'd like to show some examples of using the new API over the next few weeks and months.