Creating and modifying input structures
---------------------------------------

There are two functions your input routines should use to create and update
input working memory elements on the top state: add_input_wme() and
remove_input_wme().

Add_input_wme() takes an id, an attribute, and a value (each of type Symbol *
and normally obtained as described in Section See Symbols).
Add_input_wme() adds that working memory element to working memory, and
returns a pointer to an object of type wme. Note that if you call
add_input_wme() twice on the same id/attribute/value combination, you'll get
two copies of the same working memory element in working memory. Your code
may discard this pointer or save it for later use---you'll need it if you
want to remove the working memory element from working memory later.

For example, the following C code can be used to create the initial
input-link and then add an object with an attribute ^name fred:

Symbol *top_input_link_id, *obj_id, *input_link_sym,
       *object_sym, *name_sym, *fred_sym;
wme *top_input_link_wme, *name_wme;

/* Create symbols and id's. */
top_input_link_id = get_new_io_identifier ('I');
input_link_sym = get_io_sym_constant ("input-link");
object_sym = get_io_sym_constant ("object");
name_sym = get_io_sym_constant ("name");
fred_sym = get_io_sym_constant ("fred");
obj_id = get_new_io_identifier ('O');

/* Create the input link. */
top_input_link_wme = add_input_wme (top_state,
                                    input_link_sym,
                                    top_input_link_id);

/* Add the object and attr/value. */
add_input_wme (top_input_link_id, object_sym, obj_id);
name_wme = add_input_wme (obj_id, name_sym, fred_sym);

/* Release symbols we won't need any more */
release_io_symbol (input_link_sym);
release_io_symbol (object_sym);
release_io_symbol (name_sym);
release_io_symbol (fred_sym);
/* (but we'll probably still need the two id's) */


In WM, this code will produce something like this:

(S1 ^input-link I7)  
(I7 ^object O14)
(O14 ^name fred)

To remove a working memory element from working memory, use
remove_input_wme(). This function takes one argument, a pointer to a working
memory element object---the pointer that was returned from a previous call to
add_input_wme().  Note that there is no easy way to retrieve working memory
elements from working memory once they have been added, so if you add a
working memory element that you might want to delete later, you *must* save
the pointer returned by add_input_wme().  In the above example, we can remove
the ^name fred attribute from working memory with:

remove_input_wme (name_wme); 

Soar automatically garbage-collects input working memory elements when they
become disconnected from the goal stack.  This means that to remove a whole
input structure, you just have to remove the one "top-level" working memory
element by which it is attached to the top state.  In the above example,

remove_input_wme (top_input_link_wme);

would result in all three input working memory elements being removed from
working memory.

One final note: when the top state is removed, your input function gets
called with the mode parameter set to TOP_STATE_JUST_REMOVED.  At this point,
all input structures have been completely garbage collected, since they're
all disconnected from the top state (it no longer exists).  So your input
routine doesn't need to (and shouldn't) call remove_input_wme() at this
point.  Usually it'll just call release_io_symbol() on a few symbols and do
some cleanup stuff.