Re: CENTAUR ({variable}:add-tool & co.)

[jmi@columbo.inria.fr (Janet Bertot)]

Okay, to start with i'll paraphase the questions of Guy Durrieu in english.  
(Please note that the mailing list is sent to people in several countries 
and thus all messages should be in english).

Guy Durrieu writes (or this is at least how i interpret what he writes :-) 
=> i can't seem to get the functions {variable}:add-modif, {variable}:get-modif,
=> etc. to work.  Can you tell me how these are usually used?
=> In particular:
=> 1) must one use {variable}:add-tool and what exactly is the tool parameter?

=> 2) what is the modif argument to {variable}:add-modif and is it the same
=>    as the argument modif-path for {changes}:add-modif?

=> 3) if one wants to call to {variable}:add-modif should this be done before
=>    or after the modification is done?  In the latter case when is the 
=>    modification path to be computed?!

=> 4) the function {variable}:modified seems to always return true ...

Okay, so now i'll attack the easier questions first.

4)
The function {variable}:modified returns () when no modifications have been
been made to the tree that is stored in the variable.  That is, when you've
first Read in a program and before any modifications have been done, or
after each "Save" or "Write" of the program and before a modification is made.

2) 
Yes the two arguments are exactly the same.  {variable}:add-modif is a one-line
convenience function :
	(de {variable}:add-modif (var modif)
	    ({changes}:add-modif ({variable}:changes var) modif))
In fact, this is true for all these functions regarding tools and modifications
at the {variable} level, they are just shortcuts to the {changes} level.

1) 
Yes.  The {variable}:add-tool function is, in effect, used to register a tool
with the variable.  The idea is that when changes are made to the variable, i.e.,
when {variable}:add-modif is called, the modification is stored for each tool.
Note this is important since perhaps a tool is not run after each modification.  
Some are, some aren't.  Thus, whenever a tool wants to run it needs to get from 
the variable all the modifications that have happened since the last running of
the tool.  This is done with the {variable}:get-modif function.  You get the
latest modifications, hopefully, your tool can take advantage of this info and 
run incrementally, then after running your tool, you call {variable}:reset-tool
to say that you've run and now you are in sync with the variable.  

Thus, the typically scenario is:
	i.   register a tool using {variable}:add-tool
	ii.  whenever you want to run your tool call {variable}:get-modif
             to see the modifications that have happened since the last time
 	     the tool was run.
	iii. run your tool and call {variable}:reset-tool.
	iv.  when you no longer want to run the tool with this variable call
	     {variable}:del-tool to unregister it.

The tool parameter can be *any lisp form* that you wish.  For example, for the
pretty printers that run when you've a program displayed in an "Editor", we 
store the associated buffer structure.  Why?  Because the same variable, i.e.,
tree structure, may appear in several Editors being displayed using one or more
different pretty printers, this means we can't have the tool name be just the
pretty printer name.  We want to associate, to a given variable, a pretty printing
tool for each Editor, that tool is the pretty printing structure itself.

3)
i left this question until last because i'm not sure that i understand your
question.  If one modifies the variable using the documented functions (i.e.,
{variable}:change, {variable}:insert, {variable}:delete) then these functions
themselves call the {variable}:add-modif function and the tools will all be
informed (i.e., the {variable}:get-modif function will return this modification)
of the change.  If however, one uses lower level vtp primitives then one must
construct the modif and tell of the modification to the variable using this 
primitive.  NB: {variable}:add-modif can be considered a lower-level primitive
since i think that most of the time one would not call this function but rather
the insert, delete, and change functions.  But i may be wrong ... people may
want to do some pretty interesting stuff.  In this case, i should say that 
one constructs the modification path, then one carries out the modification,
then one calls {variable}:add-modif.


Hope this clears things up.  Please feel free to ask for more details, or
clarification.


		cheers
		janet