EMACS LISP STATIC ANALYSIS AND SYSTEMATIC RENAMING.

The purpose of this tool is to identify all free names of a set of Emacs Lisp definitions.
We mainly care of those free names which are defined outside a given set of definitions
(in one or several source files).  In this context, a free name in some definition D is a
name which is applied in D, but not defined in D. Thus, the definition D depends on its
free names. Many of these names, however, will be present in any Emacs system (because
they are built-in).  The tool allows you (automatically or semi-automatically) to
insert definitions of free names, such that a given source files becomes self-contained.
The tool attemps to identify those free names which are not built into your Emacs system.
In addition the tool can do a systematic renaming of defining and applied names in a set
of files. The renamings are done based on our knowledge of free names in the involved defitions.

This tool may change the content of certain source files.  If at all possible, it is
therefore recommeded that the files which make the analysis code base (see below) are
backed up (or copied) just before you start using the tools.

* Code bases:
A code base is a set of definition from one or more Emacs Lisp source files.  A code base
file enumerates a list of Emacs Lisp source files (either absolute paths, or paths
relative to the location of the code base file). A code base file should contain a
parenthesized list of file paths; Each file path is represented as a text string.  A code
base may also, recursively, be defined in terms of other code base files. A single emacs
lisp source file (a -.el file) may also serve as a code base. We use code bases to keep
track of a number of related source files. The *definition code base* typically identifies
a large set of source files which contain Emacs Lisp stuff. The definition code base
defines our Emacs Lisp universe, from which we may select definitions for potential
insertions in other Emacs Lisp files.  The *analysis code base* identifies a (typically
smaller) set of source file (maybe only a single sourcefile) which we are going to analyse
for free names. If we want, we can make the stuff in the analysis code base
self-contained, and we can do renamings in it.  Code base files should have the file
extension "cbs".

* Preparations:
Before you start analysing a code base, you should delete all compiled Emacs Lisp files
which overlaps with the files to be analyzed. These are files with elc extension.  The
tool assumes that compiled Emacs Lisp definitions are built-in definitions.  Next restart
Emacs in a state where no such elc files are loaded. 

* Defining code bases and analyzing them:
First define the definition code base using the menu "New codebase for definitions..." or
M-x new-definition-code-base.  In order to do that it is typically necessary to create one
or more cbs files, as discussed above. Next define the anlysis code base using the menu "New
codebase for analysis..." or M-x new-analysis-code-base. This causes the code bases to be
analyzed.  The menu item "Show free name analysis of analysis code base" (or M-x
free-names-outside-current-code-base) will inform you about the free names in each
definition of the analysis code base (only those free names which point outside the
analysis code base is listed). It may also be useful to identify duplicated definitions
via the menu entry "Show duplicate definitions in analysis codebase" (or M-x
duplicates-in-current-code-base). If you only want to analyze a code base, without
further actions, it is not necessary to set up a definition code base.

* Making self-contained source files: 
Having analysed the code base, you may now want to create a self-contained Emacs Lisp
source file (or a set of self-contained source files). This can be done by inserting
"remote definitions", taken from the definition code base.  You can use the menu entry
"Insert definitions of free names" or M-x insert-definitions-of-actual-free-names. You
must apply this command on the Emacs Lisp source file which should contain the necessary
extra definitions. (The new definitions are inserted at the current cursor possition).
Notice that this source file must be part of the analysis code base. (If you wish, it can
initially be empty, however). The inserted definitions, may themselves, have free names
which are defined outside the (now greater) analysis code base. Therefore you should
iterate a few times using the menu entry "Reanalyse and insert definitions" (M-x
reanalyse-and-insert).  The re-analysis commands initially save the el file, on which you
apply the command. You will have to iterate until no new definitions can be inserted.  You
may, alternatively, chose "Reanalyse and insert definitions repetitive" which will iterate
until no additional definitions are necessary.  You may finally analyse the extended
codebase again, to see the final result. - The menu entry "Insert remote Emacs Lisp
definition..."  (M-x insert-remote-definition) inserts a single definition from the code
base.

* Systematic renamings:
It is also possible to systematically rename the definitions of the analysis code base, in
such a way that the semantic meaning of the definitions in the codebase remains
unchanged. This is typically (but not necessarily) done after having created a
self-contained file (as described above).  There are several steps involved:

  1. Just before renaming starts, do a "Reanalyse analysis codebase" (this is IMPORTANT to
     remember). The renaming process is driven by the analysis of free names. (It is NOT
     just a simple search/replace).

  2. Next, you should create a name replacement list, which specifies a set of name
     replacements.  Use the menu entry "New name replacement list of analysis code base"
     (or M-x new-name-replacements-of-analysis-codebase) for this purpose.  This command
     will prompt you for a prefix constituent of the replacement name. Notice that, per
     default, the name of interactive functions are not renamed (but you can decide to do
     so, of course).  You can manually edit the name replacement list, but it is not
     necessary to save it to a file.

  3. Finally, use the menu entry "Rename free names in analysis code base" (or M-x
     rename-free-names-in-analysis-code-base) to effectuate the renaming of definitions,
     and the necessary renaming throughout the analysis codebase.  The buffers which are
     affected by the renamings are NOT saved after the renamings. It is up to you to
     decide if the resulting renamings are satisfactory, and to save (or possibly
     overwrite) the original source file.

* Caveats:
The tool knows about a number of name binding constructs, namely: defun, defsubst, defvar,
defconst, defcostum, lambda, let and let*. The tool does not affect macro bodys at
all. Renamings in macro bodys must therefore by done manually. The tool handles
backquotes. Common-lisp style name bindings are NOT supported.

Be sure to indent you code such that only the start of definitions begin in the first
colum.  Thus, write

(defun f ()
  (g))

instead of 

(defun f ()
(g))

There are most likely some aspects in Emacs Lisp that are not yet supported. Please
let me know if you encounter such aspects.

* Miscellaneous
The menu entry "Codebase info" (M-x code-base-info) gives some useful information about
both the definition code base and the analysis code base.


Kurt Normark.
normark@cs.aau.dk