Creating a Unit Instance

Creating a Unit Instance

Blackboard objects in GBBopen are called unit instances. Each unit instance is a member of a unit class. The unit class defines the structure of all instances of the unit class, such as the slots in each unit instance. At a more precise Common Lisp level, every GBBopen unit instance is member of a (possibly non-direct) subclass of GBBopen's unit class, standard-unit-instance, which is itself a subclass of Common Lisp's standard-object class. Even more technically, the metaclass of each GBBopen unit class is an instance of the GBBopen metaclass, standard-unit-class, which is a subclass of Common Lisp's standard-class metaclass. In other words, GBBopen classes and unit instances fit naturally into the CLOS (the Common Lisp Object System) and MOP (Metaobject Protocol) hierarchies. Fortunately, understanding such details is not required to put GBBopen to use.

The word “unit” is used in GBBopen because it has a very neutral meaning that is unlikely to be confused with programming terminology, such as “object,” or with application-domain concepts, such as “location” or “goal”. When someone refers to “unit instances,” it is clear that they are talking about GBBopen's blackboard objects. Thus, “unit instance” always refers to an instance of a particular unit class, and “unit class” refers to a class of unit instances.

So let's start using them...

This exercise shows you how to:

Define a unit class
Create a unit instance
Display a description of a unit instance
Find a unit instance by its name
Read and write slot values

Prerequisites

If you ended the Common Lisp session used in the last exercise, begin a new session and evaluate the following forms:

  cl-user> (load "<install-dir>/initiate.lisp")
     ...
  cl-user> :gbbopen-user
     ...
  gbbopen-user>

ASDF, clbuild, and Quicklisp users

Remember to (asdf:operate 'asdf:load-op 'gbbbopen) or (require :gbbopen) in place of loading <install-dir>/initiate.lisp.

Step 1: Define the `location` unit class

We begin by defining a unit class location that has two slots, named x and y.

  gbbopen-user> (define-unit-class location ()
                  (x y))
  #<location>
  gbbopen-user>

This unit-class definition instructs GBBopen to:

Define initialization argument :x for the x slot and :y for the y slot. You will use these initialization arguments in the next step, to specify initial slot values for an instance.
Define reader and writer methods for the x-of and y-of generic slot-accessor functions, used to reading and modifying the x and y slot values.

Step 2: Create a unit instance

Next, you can create a unit instance for the location unit class. To simplify access to the unit instance during subsequent activities, first define a global variable called ui by entering the following form:

  gbbopen-user> (defvar ui)
  ui
  gbbopen-user>

Now, create a unit instance and assign it to the variable ui by entering the form:

  gbbopen-user> (setf ui (make-instance 'location :x 40 :y 60))
  #<location 1>
  gbbopen-user>

This creates a unit instance of the location class, initializes the instance's x and y slots with the values specified by the :x and :y initialization arguments. The created unit instance is then assigned to the variable ui.

Step 3: Display a description of the unit instance

Now, display a description of the unit instance by using GBBopen's describe-instance function. Enter the following form:

  gbbopen-user> (describe-instance ui)
  Location #<location 1>
    Instance name: 1
    Space instances: None
    Dimensional values: None
    Non-link slots:
      x:  40
      y:  60
    Link slots: None
  gbbopen-user>

Note that you didn't specify a name for the unit instance when you created it. In fact, there is often no natural reason to name each unit instance you create. By default, GBBopen names unit instances by giving it a sequentially increasing number. (For example, the unit instance you just created is named 1.) GBBopen requires that each instance of a unit class is uniquely named within the class and the accessor instance-name-of can be used to access this name:

  gbbopen-user> (instance-name-of ui)
  1
  gbbopen-user>

Step 4: Find a unit instance by its name

You can look up a particular unit instance by its name. For example, to find the location 1 unit instance by name, enter the form:

  gbbopen-user> (find-instance-by-name 1 'location)
  #<location 1>
  gbbopen-user>

Of course, we assigned the location unit instance to the global variable ui, but it is nice to know that we can always find our unit instance using its name.

Step 5: Change the `x` slot value

Use the x-of reader and writer methods GBBopen defined for the x slot (in Step 3 above) to get the value of the x slot of the unit instance:

  gbbopen-user> (x-of ui)
  40
  gbbopen-user>

change the slot value to 50:

  gbbopen-user> (setf (x-of ui) 50)
  50
  gbbopen-user>

and then get the (new) value of the x slot:

  gbbopen-user> (x-of ui)
  50
  gbbopen-user>

Display the description of the location unit instance again, observing the changed x slot value:


  gbbopen-user> (describe-instance ui)
  Location #<location 1>
    Instance name: 1
    Space instances: None
    Dimensional values: None
    Non-link slots:
      x:  50
      y:  60
    Link slots: None
  gbbopen-user>

The GBBopen Project