Stem Cookbook - World3
NAME
World2 - A simple object level Stem cell.
DESCRIPTION
This cell is an extension of the World1 cell. In this example, instead of a single class cell with a fixed response value, we now can create multiple cells (registered objects) each with their own private data. The world_cmd method will return the planet's name stored in the cell.
CREATING THE CELL
This cell illustrates the basic way to construct objects in Stem.
A specification table is required to describe the allowed attributes of the object. This is a list of hashes with each hash describing one attribute. It is usually defined in a file lexical variable commonly named $attr_spec which is assigned an anonymous list of attribute descriptions. The fields that describe the attributes are defined in the Stem::Class module.
An object constructor is called and is passed a list of key value arguments. This class method can be called via a configuration (which uses default name of 'new') or from any Stem code. The constructor passes its attribute specification table and the passed arguments to the Stem::Class::parse_args routine which returns the new object The constructor method checks if an error happened by seeing if that returned value is an object (ref is true) or else it must be an error string. Any error string is returned to the caller of this constructor. This is the standard way Stem handles errors, references are good values and scalars (error strings) are bad. This propogation of error strings up the call stack is consistantly used in all Stem modules. After a successful construction of an object, the constructor method can do additional work and then it returns the object. The caller of the constructor will also check for an object or error string. The common case of a configuration file constructing a Stem object cell with register a good cell or print the error string and die.
ATTRIBUTE SPECIFICATION
Object cells require an attribute specification that describes the information we want to exist independently in each object cell when it is created. The following is the attribute specification used in World2:
$attr_spec = [ { 'name' => 'planet', 'default' => 'X',
},];
This specification indicates that this cell has an attribute named planet. It will default to the value of X if this attribute is not specified in the configuration arguments for this cell. Some of the attribute specification tags are name, type, default, required, class, and help. For more information on cell configuration please see Stem Object and Cell Creation and Configuration Design Notes and Stem Cell Design Notes.
OBJECT CONSTRUCTOR
This is a minimal Stem constructor with the usual name new. you can invoke any other method as a constructor from a configuration by using the 'method' field:
sub new {
my ( $class ) = shift;
my $self = Stem::Class::parse_args( $attr_spec, @_ );
return $self unless ref $self ;
return ( $self );}
To create a Stem object cell we call the Stem::Class::parse_args routine and pass it the object cell attribute specification and the rest of the arguments passed into this constructor. The rest of the arguments come from the args field in the configuration for this cell. The parse_args function then returns the newly created object to the caller, which is usually the configuration system but it could be any other code as well. An important observation to make here is the Stem error handling technique. Errors, in Stem, are propagated up the call stack bu returning an error string rather than a reference. This is the typical Stem way of determining whether of not an error condition had occurred. Constructors or subroutines which normally return objects or references will return a string value as an error message. This is always checked by the caller and will usually be passed up the call stack until a top level subroutine handles it.
CREATING THE CONFIGURATION FILE
The following Stem configuration file is used to bring a World2 object level cell into existance in the Stem environment.
[ class => 'Console', ],
[ class => 'World2', name => 'first_planet', args => [],
],
[ class => 'World2', name => 'second_planet', args => [ planet => 'venus',
],],
As explained in World1.pm, we create a Stem::Console cell to allow for the creation of a Stem console to manually send command messages and display their responses. We also create two object level World2 cells. The first, we name first_planet and it defaults to having its planet attribute set to 'first_planet'. The second, we name second_planet and set its planet attribute to 'venus'.
Using the args specifier in the cell configuration indicates that we are creating an object cell rather than a class cell. It indicates to the Stem cell creation environment that we wish to execute the constructor of the specified class to create an object of the class rather than using the Stem module as a class itself. Using object cells allow us to instantiate multiple objects with unique values, addressed and subsequent behavior.
USAGE
Execute run_stem world2 from the command line to run this configuration. You will be greeted with the Stem> prompt. It is now possible to send a message manually into the system.
Type the following at the Stem prompt:
reg status
This will show the status of the local Stem hub. You will notice the two entries for the object cells created by the configuration file under the object cell section.
Now execute the same command as you did in World1:
first_planet hello
Hello, World! (from X)
second_planet hello
Hello, World! (from venus)
As in World1, the above triggers the hello_cmd method. However, now we are triggering the hello_cmd method on separate object cells rather than a single class cell.
SEE ALSO
Stem Cookbook Part 1
Stem Cookbook Part 3
World2 Module