| | | Creating a Space Instance | |
In GBBopen, space instances serve as containers for unit instances. As we saw in the last exercise, unit instances need not be placed in a space instance. They are perfectly useful on their own. In this exercise we will create a space instance and add and remove unit instances from it. A unit instance can also be contained in multiple space instances at the same time. Although containment “in” a space instance is a more technically correct phrase, historically developers talk of unit instances being “on” a space instance or of adding a unit instance “to” a space instance. Whichever preposition is used, the meaning is the same.
As with unit instances, each space instance is a member of a space
class. The space class defines the structure of all instances of the space
class, such as any slots associated with each space instance. Unlike unit
instances, however, the standard GBBopen space class,
standard-space-instance
Space instances can be organized into hierarchical structures, much like the directories in a hierarchical file system. A useful, but not exact, analogy is to think of unit instances as being similar to files and space instances as similar to directories. Stretching this analogy one step further, adding a unit instance to a space instance is akin to creating a symbolic link to a file in a directory. Removing the unit instance from the space instance is like removing the symbolic link: the unit instance itself, like the file, is not deleted by the removal.
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> (define-unit-class location ()
(x y))
#<location>
gbbopen-user> (defparameter ui (make-instance 'location :x 40 :y 60))
ui
gbbopen-user>
|
Create a space instance named known-worldsi by entering the following form:
gbbopen-user> (defvar si) si gbbopen-user>
Now, create the space instance and assign it to the variable si by
entering the form:
gbbopen-user> (setf si (make-space-instance '(known-world))) #<standard-space-instance (known-world)> gbbopen-user>
The argument to the known-world(known-world)
Display a description of the blackboard repository, which now contains the
known-world
gbbopen-user> (describe-blackboard-repository)
Space Instance Contents
-------------- --------
known-world Empty
Unit Class Instances
---------- ---------
location 1
standard-space-instance 1
---------
2 instances
gbbopen-user>
The description indicates that:
known-world, exists in the repository
known-world space instance is empty; there are no unit
instances stored in it
locationstandard-space-instance, our
known-worldYou can look up a particular space instance by its space-instance path:
gbbopen-user> (find-space-instance-by-path '(known-world)) #<standard-space-instance (known-world)> gbbopen-user>
We assigned the known-world space instance to the global variable
si, but it is nice to know that we can always find it again using its
path.
Now, add the location
gbbopen-user> (add-instance-to-space-instance ui si) #<location 1> gbbopen-user>
Display the description of the blackboard repository again:
gbbopen-user> (describe-blackboard-repository)
Space Instance Contents
-------------- --------
known-world 1 instance (1 location)
Unit Class Instances
---------- ---------
location 1
standard-space-instance 1
---------
2 instances
gbbopen-user>
This time the description indicates that the known-worldlocation
Display the description of the location
gbbopen-user> (describe-instance ui)
Location #<location 1>
Instance name: 1
Space instances: ((known-world))
Dimensional values: None
Non-link slots:
x: 50
y: 60
Link slots: None
gbbopen-user>
Now that the locationknown-world:all is a very basic retrieval
pattern specifying that all unit instances on the known-world
gbbopen-user> (find-instances 'location '(known-world) :all) (#<location 1>) gbbopen-user>The list of found unit instances is returned. (In this case, there is only one in the list.)
This is a very simple retrieval; however, GBBopen can perform extremely complex searches as well. We will use more complex retrieval patterns in upcoming exercises.
Create a second instance of the locationx and y slot values 80 and 90, respectively, and add it to the
known-world
gbbopen-user> (add-instance-to-space-instance
(make-instance 'location :x 80 :y 90)
si)
#<location 2>
gbbopen-user>
This time we did not assign the new location
gbbopen-user> (find-instance-by-name 2 'location) #<location 2> gbbopen-user>
As you would expect, we can retrieve both locationknown-world
gbbopen-user> (find-instances 'location '(known-world) :all) (#<location 2> #<location 1>) gbbopen-user>
Display the description of the blackboard repository again:
gbbopen-user> (describe-blackboard-repository)
Space Instance Contents
-------------- --------
known-world 2 instances (2 location)
Unit Class Instances
---------- ---------
location 2
standard-space-instance 1
---------
3 instances
gbbopen-user>
This time the description indicates that the known-worldlocation
Now, remove the first locationknown-world
gbbopen-user> (remove-instance-from-space-instance ui si) #<location 1> gbbopen-user>As you would expect, only the second
locationknown-worldgbbopen-user> (find-instances 'location '(known-world) :all) (#<location 2>) gbbopen-user>and describing the
location
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
| | | Creating a Space Instance | |