explain.h File Reference

Go to the source code of this file.

Data Structures
struct	explain_chunk_struct
struct	ms_change_struct

Macros
#define	EXPLAIN_CHUNK_STRUCT_NAME_BUFFER_SIZE   256

Typedefs
typedef struct action_struct	action
typedef struct agent_struct	agent
typedef struct backtrace_struct	backtrace_str
typedef char	Bool
typedef struct condition_struct	condition
typedef struct cons_struct	cons
typedef struct explain_chunk_struct	explain_chunk_str
typedef signed short	goal_stack_level
typedef struct ms_change_struct	ms_change
typedef union symbol_union	Symbol
typedef struct wme_struct	wme

Functions
condition *	copy_cond_list (agent *thisAgent, condition *top_list)
condition *	copy_conds_from_list (agent *thisAgent, cons *top_list)
void	explain_add_temp_to_backtrace_list (agent *thisAgent, backtrace_str *temp, cons *grounds, cons *pots, cons *locals, cons *negateds)
void	explain_add_temp_to_chunk_list (agent *thisAgent, explain_chunk_str *temp)
void	explain_chunk (agent *thisAgent, char *chunk_name, int cond_number)
void	explain_cond_list (agent *thisAgent, char *chunk_name)
condition *	explain_find_cond (condition *target, condition *cond_list)
void	explain_full_trace (agent *thisAgent)
Bool	explain_interface_routine (void)
void	explain_list_chunks (agent *thisAgent)
void	explain_trace (agent *thisAgent, char *chunk_name, backtrace_str *prod_list, condition *ground)
void	explain_trace_chunk (agent *thisAgent, explain_chunk_str *chunk)
void	explain_trace_named_chunk (agent *thisAgent, char *chunk_name)
explain_chunk_str *	find_chunk (agent *thisAgent, explain_chunk_str *chunk, char *name)
condition *	find_ground (agent *thisAgent, explain_chunk_str *chunk, int number)
void	free_explain_chunk (agent *thisAgent, explain_chunk_str *chunk)
void	init_explain (agent *thisAgent)
void	reset_backtrace_list (agent *thisAgent)
void	reset_explain (agent *thisAgent)

Variables
char *	help_on_explain []

Macro Definition Documentation

#define EXPLAIN_CHUNK_STRUCT_NAME_BUFFER_SIZE   256

Definition at line 39 of file explain.h.

Referenced by chunk_instantiation(), and explain_add_temp_to_chunk_list().

Typedef Documentation

typedef struct action_struct action

Definition at line 24 of file explain.h.

typedef struct agent_struct agent

Definition at line 28 of file explain.h.

typedef struct backtrace_struct backtrace_str

Definition at line 25 of file explain.h.

typedef char Bool

Definition at line 21 of file explain.h.

typedef struct condition_struct condition

Definition at line 23 of file explain.h.

typedef struct cons_struct cons

Definition at line 26 of file explain.h.

typedef struct explain_chunk_struct explain_chunk_str

typedef signed short goal_stack_level

Definition at line 22 of file explain.h.

typedef struct ms_change_struct ms_change

typedef union symbol_union Symbol

Definition at line 29 of file explain.h.

typedef struct wme_struct wme

Definition at line 27 of file explain.h.

Function Documentation

condition* copy_cond_list	(	agent *	thisAgent,
		condition *	top_list
	)

Definition at line 117 of file explain.cpp.

References copy_condition_list().

Referenced by explain_add_temp_to_chunk_list().

                                                                  {

  condition *new_top = 0;
  condition *new_bottom = 0;

  copy_condition_list(thisAgent, top_list,&new_top,&new_bottom);
  return (new_top);
}

condition* copy_conds_from_list	(	agent *	thisAgent,
		cons *	top_list
	)

Definition at line 130 of file explain.cpp.

References copy_condition(), cons_struct::first, condition_struct::next, NIL, condition_struct::prev, and cons_struct::rest.

Referenced by explain_add_temp_to_backtrace_list().

                                                                  {

condition *top,*cond,*prev,*next;
cons *cc;

  prev = next = top = NIL;

  for (cc=top_list; cc!=NIL; cc=cc->rest) {
    cond = copy_condition(thisAgent, static_cast<condition_struct *>(cc->first));
    cond->prev = prev;
    cond->next = NIL;

    if (prev == NIL)
      top = cond;
    else
      prev->next = cond;

    prev = cond;
  }
  return (top);
}

void explain_add_temp_to_backtrace_list	(	agent *	thisAgent,
		backtrace_str *	temp,
		cons *	grounds,
		cons *	pots,
		cons *	locals,
		cons *	negateds
	)

Definition at line 157 of file explain.cpp.

References BUFFER_PROD_NAME_SIZE, copy_condition(), copy_conds_from_list(), agent_struct::explain_backtrace_list, backtrace_struct::grounds, backtrace_struct::locals, backtrace_struct::negated, condition_struct::next, backtrace_struct::next_backtrace, backtrace_struct::potentials, backtrace_struct::prod_name, backtrace_struct::result, and backtrace_struct::trace_cond.

Referenced by backtrace_through_instantiation().

                                                                                                       {

backtrace_str *back;

  back = static_cast<backtrace_str *>(malloc(sizeof (backtrace_str)));
  back->result = temp->result;
  back->trace_cond = copy_condition(thisAgent, temp->trace_cond);
  if (back->trace_cond != NULL)
    back->trace_cond->next = NULL;
  strncpy(back->prod_name,temp->prod_name, BUFFER_PROD_NAME_SIZE);
  back->prod_name[BUFFER_PROD_NAME_SIZE - 1] = 0; /* ensure null termination */

  back->grounds    = copy_conds_from_list(thisAgent, grounds);
  back->potentials = copy_conds_from_list(thisAgent, pots);
  back->locals     = copy_conds_from_list(thisAgent, locals);
  back->negated    = copy_conds_from_list(thisAgent, negateds);

  back->next_backtrace = thisAgent->explain_backtrace_list;
  thisAgent->explain_backtrace_list = back;
/* AGR 564  In last 2 statements, current_agent(...) was added.  2-May-94 */

}

void explain_add_temp_to_chunk_list	(	agent *	thisAgent,
		explain_chunk_str *	temp
	)

Definition at line 191 of file explain.cpp.

References explain_chunk_struct::actions, explain_chunk_struct::all_grounds, explain_chunk_struct::backtrace, explain_chunk_struct::conds, copy_cond_list(), agent_struct::explain_backtrace_list, agent_struct::explain_chunk_list, EXPLAIN_CHUNK_STRUCT_NAME_BUFFER_SIZE, explain_chunk_struct::name, and explain_chunk_struct::next_chunk.

Referenced by chunk_instantiation().

                                                                               {
   
explain_chunk_str *chunk;

  chunk = static_cast<explain_chunk_str *>(malloc(sizeof (explain_chunk_str)));
  chunk->conds   = temp->conds;
  chunk->actions = temp->actions;
  strncpy(chunk->name,temp->name,EXPLAIN_CHUNK_STRUCT_NAME_BUFFER_SIZE);
  chunk->name[EXPLAIN_CHUNK_STRUCT_NAME_BUFFER_SIZE - 1] = 0;

  chunk->backtrace = thisAgent->explain_backtrace_list;
  thisAgent->explain_backtrace_list = NULL;
/* AGR 564  In last 2 statements, current_agent(...) was added.  2-May-94 */

  chunk->all_grounds = copy_cond_list(thisAgent, temp->all_grounds);

  chunk->next_chunk  = thisAgent->explain_chunk_list;
  thisAgent->explain_chunk_list = chunk;
/* AGR 564  In last 2 statements, current_agent(...) was added.  2-May-94 */

}

void explain_chunk	(	agent *	thisAgent,
		char *	chunk_name,
		int	cond_number
	)

Definition at line 456 of file explain.cpp.

References explain_chunk_struct::backtrace, agent_struct::explain_chunk_list, explain_trace(), find_chunk(), find_ground(), and NIL.

                                                                        {

explain_chunk_str *chunk;
condition *ground;

  chunk = find_chunk(thisAgent, thisAgent->explain_chunk_list,chunk_name);
/* AGR 564  In previous statement, current_agent(...) was added.  2-May-94 */

  if (chunk == NULL) return;

  ground = find_ground(thisAgent, chunk,cond_number);
  if (ground == NIL) return;

  explain_trace(thisAgent, chunk_name,chunk->backtrace,ground);
}

void explain_cond_list	(	agent *	thisAgent,
		char *	chunk_name
	)

Definition at line 477 of file explain.cpp.

References explain_chunk_struct::actions, explain_chunk_struct::all_grounds, COLUMNS_PER_LINE, explain_chunk_struct::conds, agent_struct::explain_chunk_list, FALSE, find_chunk(), get_printer_output_column(), explain_chunk_struct::name, condition_struct::next, NIL, print(), print_action_list(), print_condition(), and print_condition_list().

                                                           {
   
explain_chunk_str *chunk;
condition *cond, *ground;
int i;

  chunk = find_chunk(thisAgent, thisAgent->explain_chunk_list,chunk_name);
/* AGR 564  In previous statement, current_agent(...) was added.  2-May-94 */

  if (chunk == NULL) return;

  /* First print out the production in "normal" form */

  print (thisAgent, "(sp %s\n  ", chunk->name);
  print_condition_list (thisAgent, chunk->conds, 2, FALSE);
  print (thisAgent, "\n-->\n   ");
  print_action_list (thisAgent, chunk->actions, 3, FALSE);
  print(thisAgent, ")\n\n");

  /* Then list each condition and the associated "ground" WME */

  i = 0; 
  ground = chunk->all_grounds;

  for (cond = chunk->conds; cond != NIL; cond = cond->next) {
    i++; print(thisAgent, " %2d : ",i);
    print_condition(thisAgent, cond);
    while (get_printer_output_column(thisAgent) < COLUMNS_PER_LINE-40)
      print(thisAgent, " ");
 
    print(thisAgent, " Ground :");
    print_condition(thisAgent, ground);
    print(thisAgent, "\n");
    ground=ground->next;
  }
}

condition* explain_find_cond	(	condition *	target,
		condition *	cond_list
	)

Definition at line 354 of file explain.cpp.

References conditions_are_equal(), and condition_struct::next.

Referenced by explain_trace().

                                                                      {
   
condition *cond, *match;

  match = NULL;
  for (cond=cond_list; cond!=NULL; cond=cond->next) {
    if (conditions_are_equal (target,cond))
      match = cond;
  }
  return (match);
}

void explain_full_trace

(

agent *

thisAgent

)

Definition at line 541 of file explain.cpp.

References agent_struct::explain_chunk_list, explain_trace_chunk(), and explain_chunk_struct::next_chunk.

                                           {

explain_chunk_str *chunk;

  chunk = thisAgent->explain_chunk_list;
/* AGR 564  In previous statement, current_agent(...) was added.  2-May-94 */

  while (chunk != NULL) {
    explain_trace_chunk(thisAgent, chunk);
    chunk = chunk->next_chunk; 
  }
}

Bool explain_interface_routine

(

void

)

void explain_list_chunks

(

agent *

thisAgent

)

Definition at line 519 of file explain.cpp.

References agent_struct::explain_chunk_list, explain_chunk_struct::name, explain_chunk_struct::next_chunk, and print().

                                            {

explain_chunk_str *chunk;

  chunk = thisAgent->explain_chunk_list;
/* AGR 564  In previous statement, current_agent(...) was added.  2-May-94 */

  if (!chunk)
    print (thisAgent, "No chunks/justifications built yet!\n");
  else {
    print(thisAgent, "List of all explained chunks/justifications:\n");
    while (chunk != NULL) {
      print(thisAgent, "Have explanation for %s\n",chunk->name);
      chunk = chunk->next_chunk;
    }
  }
}

void explain_trace	(	agent *	thisAgent,
		char *	chunk_name,
		backtrace_str *	prod_list,
		condition *	ground
	)

Definition at line 372 of file explain.cpp.

References explain_find_cond(), explain_trace_named_chunk(), FALSE, backtrace_struct::grounds, backtrace_struct::locals, backtrace_struct::negated, backtrace_struct::next_backtrace, backtrace_struct::potentials, print(), print_condition(), backtrace_struct::prod_name, backtrace_struct::result, backtrace_struct::trace_cond, and TRUE.

Referenced by explain_chunk().

                                                                                                    {
   
int count;
condition *match, *target;
backtrace_str *prod;

  /* Find which prod. inst. tested the ground originally to get   
  it included in the chunk.                                    
  Need to check potentials too, in case they got included      
  later on.                                                  */

  prod = prod_list; 
  match = NULL;
  while (prod != NULL && match == NULL)
  {
    match = explain_find_cond(ground,prod->potentials);
    if (match == NULL) match = explain_find_cond(ground,prod->grounds);
    if (match == NULL) match = explain_find_cond(ground,prod->negated);
    if (match == NULL) prod = prod->next_backtrace;
  }

  if (match == NULL) {
    print(thisAgent, "EXPLAIN: Error, couldn't find the ground condition\n");
    return;
  }

  print(thisAgent, "Explanation of why condition ");
  print_condition(thisAgent, ground);
  print(thisAgent, " was included in %s\n\n",chunk_name);

  print(thisAgent, "Production %s matched\n   ",prod->prod_name);
  print_condition(thisAgent, match);
  print(thisAgent, " which caused\n");

  /* Trace back the series of productions to find which one                   
  caused the matched condition to be created.                              
  Build in a safety limit of tracing 50 productions before cancelling.     
  This is in case there is a loop in the search procedure somehow or       
  a really long sequence of production firings.  Either way you probably   
  don't want to see more than 50 lines of junk....                       */

  target = prod->trace_cond; 
  count = 0;

  while (prod->result == FALSE && count < 50 && match != NULL) {
    prod = prod_list; 
    match = NULL; 
    count++;
    while (prod != NULL && match == NULL) {
       match = explain_find_cond(target,prod->locals);
       /* Going to check all the other lists too just to be sure */
       if (match == NULL) match = explain_find_cond(target,prod->negated);
       if (match == NULL) match = explain_find_cond(target,prod->potentials);
       if (match == NULL) match = explain_find_cond(target,prod->grounds);
       if (match == NULL) prod = prod->next_backtrace;
    }

    if (match == NULL) {
      print(thisAgent, "EXPLAIN : Unable to find which production matched condition ");
      print_condition(thisAgent, target);
      print(thisAgent, "\nTo help understand what happened here and help debug this\n");
      print(thisAgent, "here is all of the backtracing information stored for this chunk.\n");
      print(thisAgent, "\n");
       explain_trace_named_chunk(thisAgent, chunk_name);
    }
    else {
      print(thisAgent, "production %s to match\n   ",prod->prod_name);
      print_condition(thisAgent, match);
      print(thisAgent, " which caused\n");
      target = prod->trace_cond;
    }
  }

  if (prod->result == TRUE)
    print(thisAgent, "A result to be generated.\n");
  if (count >= 50)
    print(thisAgent, "EXPLAIN: Exceeded 50 productions traced through, so terminating now.\n");
}

void explain_trace_chunk	(	agent *	thisAgent,
		explain_chunk_str *	chunk
	)

Definition at line 306 of file explain.cpp.

References explain_chunk_struct::backtrace, backtrace_struct::grounds, backtrace_struct::locals, explain_chunk_struct::name, backtrace_struct::negated, backtrace_struct::potentials, print(), print_condition(), print_list_of_conditions(), print_string(), backtrace_struct::prod_name, backtrace_struct::result, and backtrace_struct::trace_cond.

Referenced by explain_full_trace(), and explain_trace_named_chunk().

                                                                     {

backtrace_str *prod;

  print(thisAgent, "Chunk : %s\n",chunk->name);
  prod = chunk->backtrace;
  while (prod != NULL) {
    print(thisAgent, "Backtrace production : %s\n",prod->prod_name);
    print(thisAgent, "Result : %d\n",prod->result);
    if (prod->trace_cond != NULL) {
      print(thisAgent, "Trace condition : ");
      print_condition(thisAgent, prod->trace_cond);
    }
    else
      print(thisAgent, "The result preference is not stored, sorry.\n");
    print_string (thisAgent, "\nGrounds:\n");
    print_list_of_conditions (thisAgent, prod->grounds);
    print_string (thisAgent, "\nPotentials:\n");
    print_list_of_conditions (thisAgent, prod->potentials);
    print_string (thisAgent, "\nLocals:\n");
    print_list_of_conditions (thisAgent, prod->locals);
    print_string (thisAgent, "\nNegateds:\n");
    print_list_of_conditions (thisAgent, prod->negated);
    prod = prod -> next_backtrace;
    print(thisAgent, "\n\n");
  }
}

void explain_trace_named_chunk	(	agent *	thisAgent,
		char *	chunk_name
	)

Definition at line 338 of file explain.cpp.

References agent_struct::explain_chunk_list, explain_trace_chunk(), and find_chunk().

Referenced by explain_trace().

                                                                   {

explain_chunk_str *chunk;

  chunk = find_chunk(thisAgent, thisAgent->explain_chunk_list,chunk_name);
/* AGR 564  In previous statement, current_agent(...) was added.  2-May-94 */

  if (chunk)
    explain_trace_chunk(thisAgent, chunk);
}

explain_chunk_str* find_chunk	(	agent *	thisAgent,
		explain_chunk_str *	chunk,
		char *	name
	)

Definition at line 264 of file explain.cpp.

References explain_chunk_struct::name, explain_chunk_struct::next_chunk, and print().

Referenced by explain_chunk(), explain_cond_list(), and explain_trace_named_chunk().

                                                                                      {

  while (chunk != NULL) {
    if (strcmp(chunk->name,name) == 0) 
       return(chunk);
    chunk = chunk->next_chunk;
  }

  print(thisAgent, "Could not find the chunk.  Maybe explain was not on when it was created.");
  /* BUGBUG: this doesn't belong here!  changed for bug 608 */
  print (thisAgent, "\nTo turn on explain: save-backtraces --enable before the chunk is created.\n");

  return (NULL);
}

condition* find_ground	(	agent *	thisAgent,
		explain_chunk_str *	chunk,
		int	number
	)

Definition at line 285 of file explain.cpp.

References explain_chunk_struct::all_grounds, condition_struct::next, NIL, and print().

Referenced by explain_chunk().

                                                                               {

  condition *ground, *cond;

  ground = NIL;  /* unnecessary, but gcc -Wall warns without it */
  for (cond = chunk->all_grounds; cond != NIL; cond = cond->next) {
    number--;
    if (number == 0) 
     ground = cond; 
  }
  if (number > 0) {
    print(thisAgent, "Could not find this condition.\n");
    return (NIL);
  }
  return (ground);
}

void free_explain_chunk	(	agent *	thisAgent,
		explain_chunk_str *	chunk
	)

Definition at line 221 of file explain.cpp.

References explain_chunk_struct::actions, explain_chunk_struct::all_grounds, explain_chunk_struct::backtrace, explain_chunk_struct::conds, deallocate_action_list(), deallocate_condition_list(), and free_backtrace_list().

Referenced by reset_explain().

                                                                    {

  /* First free up all the traced productions */
  free_backtrace_list(thisAgent, chunk->backtrace);

  deallocate_condition_list(thisAgent, chunk->conds);
  deallocate_action_list(thisAgent, chunk->actions);
  deallocate_condition_list(thisAgent, chunk->all_grounds);

  /* Then free up this structure */
  free(chunk);
}

void init_explain

(

agent *

thisAgent

)

Definition at line 58 of file explain.cpp.

References agent_struct::explain_backtrace_list, agent_struct::explain_chunk_list, agent_struct::explain_chunk_name, EXPLAIN_SYSPARAM, FALSE, and set_sysparam().

Referenced by init_soar_agent().

                                     {

/* "AGR 564" applies to this whole function */

  thisAgent->explain_chunk_name[0] = '\0';
  thisAgent->explain_chunk_list = NULL;
  thisAgent->explain_backtrace_list = NULL;
  /* added in this initialization, not sure why removed...  KJC 7/96 */
  /* thisAgent->explain_flag = FALSE;
   */
  /*  should we be re-initializing here??  */
  set_sysparam (thisAgent, EXPLAIN_SYSPARAM,FALSE);

/*
 * add_help("explain",help_on_explain);
 * add_command("explain",explain_interface_routine);
 *
 * explain_chunk_list = NULL;
 * explain_backtrace_list = NULL;
 * thisAgent->explain_flag = FALSE;
 */
}

void reset_backtrace_list

(

agent *

thisAgent

)

Definition at line 105 of file explain.cpp.

References agent_struct::explain_backtrace_list, and free_backtrace_list().

Referenced by chunk_instantiation(), and reset_explain().

                                             {

  free_backtrace_list(thisAgent, thisAgent->explain_backtrace_list);
  thisAgent->explain_backtrace_list = NULL;
/* AGR 564  In both statements, the current_agent(...) was added.  2-May-94 */

}

void reset_explain

(

agent *

thisAgent

)

Definition at line 238 of file explain.cpp.

References agent_struct::explain_chunk_list, free_explain_chunk(), explain_chunk_struct::next_chunk, and reset_backtrace_list().

Referenced by reinitialize_soar().

                                      {
   
  explain_chunk_str *top, *chunk;

  top = thisAgent->explain_chunk_list;
/* AGR 564  In previous statement, current_agent(...) was added.  2-May-94 */

  while (top != NULL) {
    chunk = top;
    top = top->next_chunk;
    free_explain_chunk(thisAgent, chunk);
  }

  thisAgent->explain_chunk_list = NULL;
/* AGR 564  In previous statement, current_agent(...) was added.  2-May-94 */

  reset_backtrace_list(thisAgent);
}

Variable Documentation

char* help_on_explain[]