The atchange program

The atchange Program

a brown mouse drawn as an outline with a red circle
around it and a red back slash behind it meaning that one
does not need to use a mouse if one uses the atchange
program. When the atchange program is running, it watches one or more files. When any of those files changes, the atchange program will wake up and do any actions you want. Tasks such as modifying and compiling a program, modifying a data file and using it, or editing a text and typesetting it can be automated with a single typed command such as:
atchange myprogram "compile myprogram"
By setting up atchange once before starting a repetitive task, one can avoid hundreds of mouse movements.

atchange, which stands for "At Change", is a Perl (CPAN) script that runs in a window and watches a single file or a set of files. When any of the files change, atchange performs whatever you would like it to do.

For example, if you are editing a program, atchange can compile (or 'make') the program when you write it to disk. In one window (set to a particular directory) I would type:

atchange  hello.c   "cc hello"
In another window I would edit hello.c. Whenever I save the program, it will automatically be compiled. There will be about a 1 second delay since that is the resolution that atchange looks at the file. (As described in the technical paper, this can be changed. The Perl FAQ provides more information on this topic. Currently this information is at How can I sleep() or alarm() for under a second?. If the FAQ has changed, search for: "If you want finer granularity than 1 second".

Actually, atchange only watches the modification date of the file, so if you just do a unix touch, it will wake up. This could be used to trigger a series of responses.

In the ancient but venerable (and still highly useful) Unix editor vi, one normally saves a program with the command ":w[cr]". However, if you add the line

map , :w^M
to your ~/.exrc file (~/.vimrc for Vi Improved, vim), then a single "," will write the file out, saving even more time. ([cr] means "carriage return" key that you type and "^M" is control M that must be in the .exrc file. To create a control M in vi, type control-v followed by control-m.)

If I want to do several things at once, I type them on one line:

atchange  hello.c   "cc hello; hello"
This would first compile and then run the hello program. (The semicolon ";" separates commands in Unix.) This could also be put into a file, I often name it "automate":
hello.c  cc hello
         hello
Then atchange is started in its own window with:
atchange automate
One can have several compilations in the automate file:
hello.c  cc hello
         hello

bello.c  cc bello
         bello
They MUST be separated by a blank line, to tell atchange to treat them separately. NO SPACES ARE ALLOWED ON THE BLANK LINE!!! If you use spaces the item will become part of the previous item and executed along with that. You can use the rembla.p program to remove the extra blanks. You could also use the Unix version that works with pipes: rb.p.

File Globbing

André R Brodtkorb modified atchange so that it now does file globbing. That is, one can say 'b*' to have atchange respond to all files that begin with the letter 'b'. He says:
My use for the atchange script is to compile latex documents and run xdvi to visualize them. Using a file such as the following:
figures/*.*
  rubber -d -Wall amsart.tex

*.tex
  rubber -d -Wall amsart.tex

amsart.pdf
  xdvi -remote latex_preview -reload
Rubber is a nice python tool that automates the process of running latex, bibtex, +dvipdf, etc. much in the same way as latexmk. http://www.pps.jussieu.fr/~beffara/soft/rubber/
new New as of 2010 July 01 in atchange version 2.10.


Papers about atchange

atchange was originally written as a C shell script, atchange.csh (and helper script waitforchange) (!) by Tom Schneider in December 1995. He told his friend Jeff Haemer about it and Jeff rewrote the program in Perl in early 1996. Jeff Haemer and Jeffrey Copeland have written three papers about atchange.


PostScript on the fly

It's even more fun to have a program compile, run to make a PostScript file, and then to pop that up with ghostview! One can immediately see the function of the program without lots of mousing around. Here's one way:

hello.c  cc hello
         hello > graphic.ps
         ghostview graphic.ps
When you decide to test the hello.c program, touch the "," key and sit back. Three steps occur sequentially: the hello program is compiled, hello writes some postscript graphics into a file (graphic.ps) and then ghostview shows the file. Now if you've arranged the windows just-so, the display will appear over the editor window. All you need to type is "q" to destroy the ghostview, and you then fall right back to the editor for another round.

Doing the same thing in several atchange stages has some advantages:

hello.c    cc hello

hello      hello > graphic.ps

graphic.ps ghostview graphic.ps

parameters hello
One has two windows in vi, one on hello.c and the other on a parameter file that controls how hello will run. Then one can switch between the two editors with a single key stroke (on a Sun workstation, the "Front" key does that). When either the program or the paramter file change, the graphic appears.


Shell Scripts

I automate directories so frequently that I have made a shell script for it, called au. If you already have an automate file in the current directory, au will run atchange on it. If there is no automate file, au will allow you to write one (by dropping you into vi) and then it will run atchange. If there are any parameters on the call line, au will run vi on the automate file, allowing you to update it. The au script calls two other scripts, atc and nw. The scripts and files are:

To use these,
  • Download each file and put a copy of each in a directory.
  • Permit the files to be executable.
  • Set your path to use the directory.


    LaTeX with Atchange: A Typesetting WYSIWYG!

    The big selling point for WYSIWYG (it stands for What You Want Is Not What You Get ;-) is the immediate text feedback. But the price you pay is that the file formats are unreadable. This means that if the company ever goes out of business, you will have a tough time converting to another format.

    In contrast, typesetting languages such as LaTeX store the text in pure ASCII. This means that they can always be edited in the future (an example is the technical paper for atchange which started out in ASCII in the older troff typesetting language. It was easy to convert it to HTML, yet another typesetting language.) Also, it means that it's easy to write programs that create documents or modify them.

    LaTeX does a FANTASTIC job at mathematical and scientific notation. An example is the Information Theory Primer.

    If you are editing a LaTeX document, atchange can typeset your document and display the current version using xdvi As computers become faster, this approaches a WYSIWYG. Now LaTeX completely beats word processors! (As if there was ever any comparison.)

    Just the other day I was writing a LaTeX document in one window, with atchange typesetting it in another window and atchange telling me the current length of the abstract in a third window.

    With more than one page of text, one would like to keep the viewer on one page and "tickle" it to update.

    Here my trick for getting xdvi to update its display of a page automatically. I use several scripts:

    • The l program runs LaTeX on a file. If there are missing references, it runs BiBTeX. When it's done it calls popwindow. It's rather neat to watch a reference appear in the text, first as "(?)" (meaning it's not there) and then as (Smith et al., 1997) - and to know that the bibliography was fully updated at the same time! (Sometimes I watch for the new bibliography entry to appear - without touching the computer at all ...)
    • If one is looking at a paper with xdvi, we would like xdvi to wake up and refresh after the paper has been typeset. I keep one window on the LaTeX document and another open to the page I'm working on. The computer is fast enough to typeset 30 pages in only a few seconds! (And things can only get better.) This is done using a call to the standard xrefresh from within the l script.
    • sss runs xdvi on a paper in a very compact window.
    • atp runs all the above (it uses atp.script ). Typically I create a right type window and then just say atp in it. This sets up the xdvi and will trigger LaTeX and BiBTeX at the appropriate times using the l script. I then use my favorate editor (vi of course! ;-) in a left type window. This way I edit the language on the left and see the results on the right. Although one doesn't work directly on the text, it doesn't take long to get used to it. (A similar effect occurs in getting used to the mouse pointer moving on the screen in correlation with one's hand on the table.)
    • FULL AUTOMATION new 2006 Dec 11.
      There are now enough tools available to fully automate LaTeX! This requires several components:
      • Atchange to trigger scripts when you write out your file.
      • The text editor vim which writes your current location to a file when you write out your file.
      • xdvi which takes that location and displays where you are. Since
      We start with currentline.vim which is a plugin for the text editor vim. You must have a modern version of vim (version 7 or later). When one writes a file out that ends in .tex, the plugin writes another file that contains your current location in the file. At the moment I have several scripts that are not fully developed. Here is the general idea. Suppose the file containing the line is called $paper.lin. Then in a script one uses the file:
       set paperline = `cat $paper.lin`
       if `echo $paperline | grep '-'` != '' then
      
         echo setxdvi $paper.dvi -$paperline
              setxdvi $paper.dvi -$paperline
       else
      
         echo setxdvi $paper.dvi $paperline
              setxdvi $paper.dvi $paperline
       endif
      
      The l script now writes the $paper.lin file. setxdvi is available from our archive. Note: your xdvi must be reasonably modern to use this. As I don't have a modern xdvi on my main computer yet, not all of these scripts are fully developed.
    • Controlling the Skim PDF Viewer new 2010 Apr 22. The Skim PDF Viewer can be set to automatically update the PDF display when the file changes. This is done with a hidden parameter. See my skim script for how to use it. Notes:
      • MacVim - integrate Skim with vim
    • Controlling the any PDF Viewer new 2010 Apr 22. The SSH Filesystem (sshfs) program allows one to mount a directory across an ssh connection. Oleg Katsitadze suggested that "You can try accessing the remote pdf file with sshfs." Note: I have not tried this yet.
    • Controlling the Adobe Reader new 2010 Apr 22. xdotool - integrate Skim with vim Thanks to James Quirk for this posting and also this one. A solution is posted at forums.adobe.com. Note: I have not tried this yet.
    • Controlling PDFs and Editor-Previewer Synchronization Change and show PDF with TeX "immediately," and link I/O, by Uwe Lueck, is a summary page on methods. new 2010 Apr 29.
    • SyncTeX Vim LaTeX/Skim, provides direct control of the skim viewer by the vim editor! new 2010 Apr 29.
    More pointers: Here are instructions on how we use latex in the Schneider Lab.


    Specialized Alternative Solutions for running LaTeX

    The editor emacs can run LaTeX directly, and can have parts typeset. This is an alternative solution if you like emacs.

    On 1997 Jan 13, Stephen Eglen (stephene@cogs.susx.ac.uk) wrote to me:

    I notice one of your applications of atchange is for Latex. This is a good solution. I was just wondering if you had seen another solution: that provided by emacs. Not only can it can do similar things to what you show here, but the big advantage I find is that you can get it to just run latex on a region rather than the whole file or collection of files that you are editing. Rather than wait for latex to run through a thirty page doc, it can just be run on the couple of paras that Im interested on at the moment, cutting down even more on the delay between editing and seeing what the result is.

    Furthermore, if you are using a lot of maths in your docs, you can get it to display most of the maths symbols in the editor window as you type. (But I don't use this aspect.)

    If you are interested, look at http://sunsite.auc.dk/auctex/

    But if you don't emacs (or don't like using it) then no worries!

    (Reprinted with permission.)

    Thanks for the tip!

    A perl script called latexmk can also be used:

    ... Five years later, on 2002 Oct 19 Stephen wrote again to tell about this:

    I recently found the program, latexmk, which is a kind of specialised version of atchange for running latex. The nice thing is though that it only runs latex, bibtex, as many times as needed to make sure your document is correct. It can also then send a signal to xdvi to update itself -- makes latex editing nice and fast for short documents! Plus, of course, the link with atchange is that it watches your latex file for changes (using the -pvc switch). The original source of latexmk, by John Collins, is at http://www.phys.psu.edu/~collins/software/latexmk-jcc/. However, the official copy is at CTAN: http://www.ctan.org/tex-archive/support/latexmk/

    Thanks for another great tip!

    2010 Jan 18:
    google: pdf refresh latex
    Faster and more comfortable LaTeX editing and previewing with latexmk is a discussion of various options.

    To make latexmk work with the xpdf viewer (on a Mac OSX for example), include in a ~/.latexmkrc file these contents:

    $pdf_previewer = "start xpdf -remote %R %O %S";
    $pdf_update_method = 4;
    $pdf_update_command = "xpdf -remote %R -reload";
    
    Then LaTeX will run and the PDF will be updated when you write your file(s) out.


    HTML as a WYSIWYG!

    There is even a way to "tickle" Netscape, so writing HTML can be done without mousing around!

    % netscape -remote 'openURL(http://www.cogs.susx.ac.uk)'
    
    Further information about this is available from Netscape. (Thanks to Stephen Eglen (stephene@cogs.susx.ac.uk) for the tip.) These are the automate lines I've been using to write this text:
    atchange.html
      netscape -noraise -remote 'openURL(http://schneider.ncifcrf.gov/atchange.html)'
    
    EVEN BETTER THAN THAT, one can refresh the page, so Netscape won't keep going to the top of the document:
    atchange.html netscape -noraise -remote 'reload'
    

    The eh shell script

    Tom Schneider wrote a script called vh that starts vi on an html file and makes netscape refresh to that file. Jeff Haemer took the idea of vh and made a better script that solves various problems. It is called eh. You use it by typing:
    eh myfilename
    or
    eh myfilename.html
    eh will point Netscape to 'myfilename.html' and then run your editor (vi by default) on 'myfilename.html'. If myfilename.html does not exist, eh will create a small starter html for you. eh is written in Standard shell (e.g., bash or ksh), so you have to have one to make it work.

    If you type

    eh -long
    it will give longer instructions.

    Jeffreys Copeland and Haemer describe this program in their paper, "We Use vi to Edit Web Pages: How to turn vi into a WYSIWYG HTML editor".


    Automating Medline to BiBTeX Conversion

    The program medlinebib will convert from Medline bibliography format to BiBTeX. Atchange can be used to automate the process. new (New as of 1999 September 3)


    Running Atchange

    Atchange will NOT WORK with earlier versions of Perl. It will fail with perl v4.000. With 5.004_03 it works fine. Please upgrade to the latest Perl before contacting us about problems you have. See the next section on how to obtain Perl.

    To set up atchange, first make sure the atchange script is in your execution path. Then just run it as in the examples given on this page. Unix reads the first line of the Perl code and will automatically start. There is no need to 'compile' the code.

    If atchange does not work and you get this message:

    stty: standard input: Invalid argument
    
    then you need to do the following.

    The problem is that atchange launches a csh, but if you have a .csh that calls stty this will cause trouble for stty. In the current version of atchange is some code that sets an environmental variable called PERLCSH. This allows the .cshrc to know that atchange has called it. To tell your .cshrc not to execute the stty when called from atchange, you need to add two lines to your code:

    if ( (! $?PERLCSH ) && $?prompt) then
       stty erase '^H'
       set prompt = "`uname -n` \!% "
    endif
    
    The top and bottom (blue) lines test whether the .cshrc is being called from perl and if it is an interactive shell. If so, the stty and set prompt are called. You may have other lines in between these two, but the important thing is that the two lines surround the stty call. (Thanks to James W. Haefner (Department of Biology, Utah State University, Logan, UT, jhaefner@biology.usu.edu) for the tip!


    Atchange "Bug" Under Linux

    Atchange could use a slight tweek to run more smoothly under Linux. We will absorb this problem into the code when we have a general solution.

    The problem is that under some operating situations, atchange will give this message:

    stty: standard input: Invalid argument
    However atchange seems to function fine anyway. We have eliminated this effect from Solaris but it still appears under Linux. A "correction" for Linux is noted in a comment in the current version of atchange. Here is some more information about what is happening:
    I have the Redhat 6.0 distribution and am using bash. SHELL is defined as "/bin/bash" and redhat has apparently linked "/bin/sh" to "/bin/bash". With the perl code as originally written $shell gets set to "/bin/bash" (as expected) and (apparently) ".cshrc" is not opened inside the perl script. I removed my fix and still get the error. Since you mentioned errors, I further changed atchange to test if the current shell is bash. if true, then $shell is set to "/bin/sh", if false, the original in-line conditional is used to set $shell. It works now, but I can't claim to fully understand why because of the link between "/bin/sh" and "/bin/bash".
    James W. Haefner
    Department of Biology   Email: jhaefner@biology.usu.edu
    Utah State University   Voice: 435-797-3553
    Logan, UT 84322-5305      Fax: 435-797-1575
    

    You will have no problems if you leave the code alone and just put up with the message until we have learned how to eliminate it.


    Obtaining Perl

    CPAN (http://www.perl.com/CPAN/) or Comprehensive Perl Archive Network is the best source to obtain the language Perl that atchange runs in. It's free!


    Summary

    Of course nothing (other than silly non-multitasking operating systems) prevents you from having many atchange programs running at the same time in different windows all doing different complex things and all set up "on the fly" as you need them.

    There are many other uses of the program. It allows one to "automate" many things one does. Rather than mouse and type repeatedly, atchange allows one to concentrate on the job at hand.

    color bar

    More about Atchange

    Fam: "file alteration monitor" daemon

    (New as of 1997 April 17)


    Atchange Scripts

    new (New as of 1998 March 13) Alan Zaslavsky (zaslavsk@hcp.med.harvard.edu) has kindly sent two scripts that use atchange. I have not tried them yet, but will point to them: atchanges and mailprint.atc. His letter introduces them. Here is the help information:

    atchanges : utilities using the atchange command
    Usage: atchanges [-s|-p] option [file | extension] ...
       atchanges help: print this message
       atchanges show: print a list of currently running atchange processes,
            with PID and arguments.
       atchanges kill: print list as above, then kill all of those processes
            (after a brief pause to let you interrupt).  Then runs start.
       atchanges start: run atchange to start up all files named in the environment
            variable ATCHANGEFILES.
       atchanges backup : start up atchange to watch the named files
            and create a backup each time it is modified so filename is
            copied to filename.0, filename.0 to filename.1, etc.  If the
            first argument after 'backup' is a digit 1-9, it is
            interpreted as the number of the oldest (highest numbered)
            backup that may be created; default value is 5.
       atchanges make : start up atchange to watch all files
            that now exist in the current directory with the given extensions
            (.c and .f by default if no extensions are specified) or filenames
            (anything not beginning with '.').  atchange will run 'make',
            without arguments, whenever one of the files is modified.
            For example:    atchanges make .c
            will run 'make' each time any .c file is modified.
       atchanges html : load filename (a single browsable file,
            typically HTML) into an already-running netscape browser,
            then start up atchange to watch filename and reload into browser
            whenever modified
       atchanges latex : start up atchange to watch filename.tex
            where filename is empty (indicating all .tex files) or one or
            more basenames (without the .tex extension).  Whenever one of
            the files is modified, latex is run on the file and if a
            display is open, a window is briefly popped up to force xdvi
            to redisplay.
       -s: save the command file for make, latex, or backup options,
            so it will be left after exit as /tmp/atchanges-make.nnnn, etc.
       -p: print (do not run) command file for make, latex, or backup options.
    For other file watching functionality, use the atchange command directly.
    

    (The previous version is now kept at atchanges.1997may27.)


    Other Tools

    Webrowse

    new (New as of 1998 August 31)
    Steve Kinzler (kinzler@cs.indiana.edu) writes:
    Also, you might want to check out webrowse(1) -- a generalized, enhanced and simplified front-end for things like "netscape -remote ...". Can be really handy in conjunction with atchange(1).
    http://www.cs.indiana.edu/hyplan/kinzler/home.html#binp/webrowse
    http://www.cs.indiana.edu/hyplan/kinzler/home/doc/webrowse.pdf

    General Computer with Atchange

    Phil Gendreau (phil_gendreau@yahoo.com) suggested that it might be possible to use atchange to build a virtual computer. It turns out that this was pretty easy to do! I just built a set of Boolean variables, a to e and a set of nodes, node1, node2 and node3. When the Booleans change, they touch the nodes. Within a node the logic is performed (using csh language) and then they touch the resulting Booleans. It is incredibly slow but does the sequential logic. I built such an atchange-computer. The computer simulates OR, AND and finally one of the components is a NAND gate. Since one can do ANY Boolean logic with NAND, any computer could be constructed this way. The entire directory is also available for your inspection. Naturally, the thing already shows signs of timing conflicts, where one part of the circuit races and affects another! I found I had to put in a 2 second delay before the final negation. An example result:
    |---------|
    | a = 0 --|
    | b = 1 --|
    | c = 1 --| a+b
    | d = 0 --| a*b
    | e = 1 --| ~d
    |---------|
    

    Atchange on Mac OS X

    APPARENTLY THIS IS NOT NEEDED ANYMORE

    Atchange will run on on Mac OS X if you set the location of perl. To determine this type in a terminal:

    which perl
    It should come back with
    /usr/bin/perl
    The first line of Atchange is
    #!/usr/local/bin/perl
    so just change it to
    #!/usr/bin/perl
    Put the revised atchange in your path and it should work immediately. ALTERNATIVELY, just grab this version:
    atchange.macosx
    change the name to 'atchange' and put it in your path.

    Example I made a postscript program on my mac and automated the process. So while I edited the file cir.ps, I used convert (from the ImageMagick package) to make a gif and the system Preview to view it. But of course it switches to the Previewer, which meant I had to mouse all the time. But it turns out that one can force the re-opening of the terminal and keep one's fingers on the keyboard! This is an automate script:

    cir.ps
     clear
     echo starting conversion
     convert cir.ps cir.gif
     open cir.gif
     open -a Terminal
     echo done
     date
    
    The Preview updates to the new image AND Terminal opens again and I'm still in vi working on the file. One can also convert to pdf (using ps2pdf) but unfortunately the Adobe Reader isn't smart enough to update when the file changes. However, see above on this page for how to use the Skim PDF Viewer instead.

    color bar This page is http://schneider.ncifcrf.gov/atchange.html

    color bar Small icon for Theory of Molecular Machines: physics,
chemistry, biology, molecular biology, evolutionary theory,
genetic engineering, sequence logos, information theory,
electrical engineering, thermodynamics, statistical
mechanics, hypersphere packing, gumball machines, Maxwell's
Daemon, limits of computers


    Schneider Lab

    origin: 1997 January 1
    updated: 2012 Jan 25: remove broken link
    color bar
    National Cancer Institute    National Institutes of Health    Health and Human Services    USA Gov - Official Web Portal    Viewing Files    Accessibility