Contract
Return type	wob
Parameter key	Default value	Type
add_vector_key	false	boolean
if_exists	"set"	string
lookup	false	boolean

Water Contract
<method cache_instance add_vector_key=false if_exists ="set" lookup =false/>

See also: class, make, to_cxs

In normal programming, a class will not know what instances of it have been created. If you want to reference an instance, you have some application way of referencing the instance, usually by it being stored in a field of some other object that you do have access to. But sometimes, you want to have a place to store instances of a class that you can get to even if you don't have some other object around that is storing the instance. This is the utility of cache_instance. cache_instance is a method typically called in the 'make' method of a class. It stores an instance in the "of" field of the class. cache_instance is a somewhat tricky method but it gives you a lot of functionality. First cache_instance looks up the '_part_name_key' of the parent of the _subject of cache_instance. The _part_name_key of wob is "_name" so that is used if there is no other _part_name_key found. Then the _subject is examined for a field with the key of the _part_name_key, i.e. "_name". If the _subject does not have a field whose key is the _part_name_key, then the _subject is not cached under a part_name_key. Note that no lookup is performed here, the _part_name_key must be directly in the subject for it to have effect. If the _part_name_key is found, the subject will be cached in the "of" field of the parent of subject, or the nearest ancestor of subject that has an "of" field. If there is no "of" field found, then it is created in the parent of the subject using <instances/> . instances is a special class used just for the purpose of storing the cached values, but you should think of it as a "supervector", ie an object that has fields of both integers and string keys. The name that the _subject is to be cached under is retrieved by getting the value of the field within subject whose key is the value of '_part_name_key'. Then the field of the part_name_key is set within the value of "of" to the _subject. Here is how it works;

<class boat>
    <method make> _subject.<cache_instance/> </method>
   </class>
<boat _name="bluebelle"/>

boat.of.bluebelle

The above call returns our new instance since the make method is called and its last expression is a call to cache_instance which returns its subject, in this case the _subject which is our new instance of the boat named "bluebelle". But the important thing is the side-effect. Now boat.of.bluebelle returns our new object. Note that since there was no _part_name_key field in boat, the _part_name_key defaulted to "_name" Since our new instance has a _name of "bluebelle" the instance was cached. We can create an instance without caching it if we like by not giving it a _name such as <boat/> or <boat weight=123/> . We might do this if we were creating a temporary boat. Caching an instance makes it convenient to reference the object via a path of its class name, followed by of followed by the name of the instance. Since you can always make a path to a class, you can alswys make a path to cached instances. Should we want our "name" field to be called something other than _name, we declare a _part_name_key in the class like so:

<class boat licence_plate=req _part_name_key="licence_plate">
     <method make> _subject.<cache_instance/> </method>
   </class>
<boat licence_plate="bluebelle"/>
boat.of.bluebelle.licence_plate

"bluebelle"

a wob
Parameter key Default value Type
add_vector_key false boolean
add_vector_key stores the instance in an integer field in the "of" object. It defaults to false. If this argument is true, an additional key is added to the of object which is the next highest integer key available in the of object. This makes it easy to count the number of instances, maintain the order they were created in and reference them by an integer like so:

<class boat _name=req>
    <method make> _subject.<cache_instance add_vector_key=true/> </method>
  </class>
<boat _name="bluebelle"/>
<boat _name="old paint"/>

boat.of."old paint"

boat.of.<length/>

2

boat.of.0._name

"bluebelle"

boat.of.1._name

"old paint"

add_vector_key functionality happens whether or not there is a part_name_key. You can chose to cache objects only under a vector key simply by them not having a part_name_key. IF you have no real use for a "name" of an object, then using integers is a great cheap way to cache them.

<class boat>
  <method make> _subject.<cache_instance add_vector_key=true/> </method>
</class>
temp.<set my_boat=<boat/>/>
boat.of.0

temp.my_boat

a wob
Parameter key Default value Type
if_exists "set" string
Usually you want only one instance of a given name to exist. Without the cache_instance there is no checking for this uniqueness. With cache_instance, if you create a second instance having a given name, the new instance will overwrite the first instance in the cache is below.

<class boat _name=req>
 <method make> _subject.<cache_instance /> </method>
</class>
<boat _name="bluebelle"/>
<boat _name="bluebelle"/>

boat.of.bluebelle

But sometimes you want to garentee that only one instnce of that name is created. By passing in a if_exists="error" argument to cache_instance. cache_instance will error if it is called a second time with an instance of a given name.

<class boat _name=req>
 <method make> _subject.<cache_instance   if_exists="error"/> </method>
</class>
<boat _name="bluebelle"/>
<boat _name="bluebelle"/>

error

The formatting method to_cxs has special support for cached instances. boat.<to_cxs only_print_instances=true/> turns off the printing of the call to class and the printing of all its attributes. It does however leave on the printing of the of field and all the of fields of all the subclasses of the class you are printing. Use only_print_instances=true when you want to save the instances of a class in a file but not the classes that they came from since you probably load them as part of the loading of your application.