Obtaining a list of user-defined programs

[Federico Bindi]

Dear Statalisters,

I would like to obtain a list of user-defined programs currently in memory (programs defined with program define, to be clear), to check it against a list of programs I plan to define and warn the user if there is any overlap. However, program dir simply displays program names, but doesn't store them anywhere (at least, to my understanding). Is there a way around this?
Best (and thanks for the great work!),

Federico

[daniel klein]

First, let me remind you (me, and others) that many (probably most) of Stata Corp's commands are defined in ado-files with program define.

Let me also remind you (me, and others) that inside an ado-file, we can have multiple program define statements. However, there is no risk of "overlap" or conflicting names because the second and later program define commands define programs that are treated as subroutines of the main program. Here is how that looks like:

--- begin foo.ado
program define foo
    display "foo"
    bar
end

program bar
    display "bar"
end
--- end foo.ado

After calling foo, I get the following

. program list

foo:
  1.     display "foo"

foo.bar:
  1.     display "bar"

Note the program foo.bar, which means that (1) I cannot call the program/command bar outside of foo.ado, and (2) I can, therefore, define a new program bar, and both, bar and foo.bar could happily coexist and Stata would not confuse them.

One of the implications is that it really matters how you are planning to define your programs, within a do-file or within an ado-file.

Anyway, there is no need to "warn" the user; Stata does that for you. Watch what happens when I try to define a program foo (which I have already defined in foo.ado, and which I have loaded into memory by calling foo).

. program define foo
program foo already defined
r(110);

If you still wanted to warn the user, you can

capture program list foo

and read the return code. If the return code is 0, then the program already exists in memory. If the return code is 111, the program does not exist and you can define it. More generally, instead of obtaining a complete list of all programs in memory, just check whether the ones you want to define already exist.

[Federico Bindi]

Thank you Daniel for your precise and helpful answer.

In fact, I plan to insert the command I'm writing in an .ado file, to make it available across my organization; hence, most subroutines will be stored as foo.bar. As regards the main program, Stata's default warning for conflicting program names will suffice.

Have a great day!

[daniel klein]

In fact, I plan to insert the command I'm writing in an .ado file, to make it available across my organization; hence, most subroutines will be stored as foo.bar. As regards the main program, Stata's default warning for conflicting program names will suffice.

I should have been more explicit. What I wrote about Stata's behavior applies (mostly) to programs in do-files or interactively defined, not to programs defined in ado-files. Sorry.

With ado-files, things are more complicated. Say, I write a program, tabulate, and store it in tabulate.ado. Stata will never even (try to) define the program. Because tabulate is (one of a few) built-in commands when you type

tabulate ...

Stata will not even start looking for tabulate.ado. Stata will always execute built-in commands before commands defined in ado-files.

What happens if I call my program describe? Perhaps surprisingly, StataCorp's describe is not built-in but implemented as an ado-file. Thus, if I define my own describe and save it in describe.ado, Stata might actually execute it. Whether Stata executes StataCorp's describe or my own describe depends on where I store my ado-file and on my ado-path settings. Usually, I store my commands in the PERSONAL or PLUS directory. Occasionally, I will store it in the current working directory. StataCorp typically store their ado-files in the BASE directory. In it's default ado-path setting, Stata searches for ado-file in BASE before searching in PERSONAL, PLUS, or the current working directory. Thus, Stata will typically find StataCorp's describe first and execute it. I could change the ado-path settings and force Stata to find my ado-files before finding StataCorp's ado-files. That is not advisable.

A long (long) story short: if multiple ado-files with the same name exist, it is hard to keep track of which will be executed. It is therefore advisable to choose a name for your program that has not been chosen by StataCorp and is unlikely to be chosen in the future.


Addendum:

I have used the terms program, command, and ado-files interchangeably. These are not the same but they are related. An ado-file defines one command that might consist of one or more programs. Moreover, an ado-file must have the same name as the first program that it defines.