soar.hooks

Functions for brains to hook into various elements of Soar.

To make use of a given hook, a brain should import it from here. It will be redefined by the client or controller accordingly.

Treat all hook names as reserved words, and do not use them as arbitrary variable names.

soar.hooks.elapsed()

Get the time that has elapsed running the controller.

Set by the controller before the brain’s on_load() function is called.

Returns:The elapsed time in seconds, as defined in soar.controller.Controller.elapsed.
Return type:float
soar.hooks.is_gui()

Return whether Soar is running in GUI mode.

Set by the client when it first loads.

Returns:True if running in GUI mode, False if headless.
Return type:bool
soar.hooks.raw_print(*args, **kwargs)

Allows a brain to print without the '>>>' prepended.

All arguments and keyword arguments are passed to print().

soar.hooks.sim_completed(obj=None)

Called by the brain to signal that the simulation has completed.

Set by the controller before the brain’s on_load() function is called.

Parameters:obj (optional) – Optionally, an object to log to the logfile after the simulation has completed.
soar.hooks.tkinter_hook(widget, linked=True)

Hook a Tkinter widget created by a brain into Soar, so that the UI is aware of it.

This function is redefined by the client before a brain is ever loaded.

Brains that import this hook can expect that their methods will always run in the main thread when running in GUI mode, as Tkinter is not thread-safe. Otherwise, this is not guaranteed.

If not running in GUI mode, importing and using this hook simply returns its argument unchanged and does nothing.

Parameters:
  • widget – The Tkinter widget to attach to Soar. This may also be some object that supports a destroy() method.
  • linked (bool) – If True, the widget will be destroyed whenever the controller reloads.
Returns:

The window or object that was attached.

soar.hooks.tkinter_wrap(widget, linked=True)

Make Soar’s UI aware of a Tk widget, and wrap its callables so that they run on the main thread.

This function is redefined by the client before a brain is ever loaded.

This is a ‘softer’ version of tkinter_hook–it does not force all brain methods to run on the main thread.

Rather, it attempts to find and wrap widget callables so that, when called, they will execute on the main thread.

If not running in GUI mode, importing and using this hook simply returns its argument unchanged.

Parameters:
  • widget – The Tk widget to attach to Soar. This should support a destroy() method.
  • linked (bool) – If True, the widget will be destroyed whenever the controller reloads.
Returns:

The widget, with its callables wrapped so that they will run on the main thread.