1Object(3) User Contributed Perl Documentation Object(3)
2
6 none
7
9 David A. Parker, dparker@nocpulse.com
10
12 FreezeThaw, Config::IniFiles, perlobj, perltoot
13
15 NOCpulse:: Object - an abstract PERL class that tries and fails to
16 cover up the ugliness that is OO in Perl, amongst other things.
17
19 package MyClass;
20 use NOCpulse::Object;
21 @ISA qw(NOCpulse::Object);
22 ...
23
25 NOCpulse::Object is an attempt to simplify the task of building class
26 hierarchies under Perl. It has a few "extras" that make writing
27 applications a bit easier as well. Specifically, NOCpulse::Object...
28 ...defines a protocol for instance creation
30 ...defines a protocol for instance variable creation
31 ...defines a protocol for accessing instance variables
32 ...defines a protocol for "dumping" the contents of an object
33 ...defines a protocol for "Class Instance" variables
34 ...wraps the FreezeThaw mechanism to help facilitate very primitive persistence
35 ...provides global class-side access to a user-specified .INI file a la Config::IniFiles
36
38 Perl 5.004, Carp, Config::IniFiles, FreezeThaw
39
41 nothing
42
44 $config - holds an Config::IniFiles instance if one was created with
45 SystemIni() $DEBUGOBJECT - holds the default debug instance
46
48 $classvars - holds hashes of "class instance" variables
49
51 SystemIni($inifile)
52 This method accepts the name of an .ini file (a la
53 Config::IniFiles) and initializes the module $config variable with
54 an instance of Config::IniFiles based on that file. Note that this
55 is a global change - it applies to all subclasses and their
56 instances for the execution of the current program.
57
59 ClassBasename()
60 Class or object method to return just the last part of a
61 PERL class name (i.e. gets rid of leading path parts (e.g. Something::Basename)
62 Config()
64 Returns a pointer to the Config::IniFiles instance that was created
65 when SystemIni() was called.
66 ConfigValue($name[,$item])
68 Retrieves the value of the item $name in the section ref($class) of
69 the .ini file specified when SystemIni() was called. This is
70 analogous to putting your class variables in an .ini file (and is
71 very handy).
72 This method includes a mechanism for dealing with individual per-
74 class .ini files as well as follows:
75 * you must include an entry in the SystemIni (above) within the
77 section
78 for this class called "ini" (e.g. ini=MyOther.ini).
79 * when you call ConfigValue, you must pass both a section name and
81 an item
82 name ($item) as opposed to just an item name.
83 If you do these things, an Config::IniFiles instance will be
85 created and stored as a class instance variable for the class in
86 question whose name is "config", and this method will defer any
87 section,item requests to that instance rather than to the instance
88 created for the file specified with SystemIni.
89 getClassInstVar($name)
91 Returns the value of the "class instance" variable whose name is
92 $name (if any). Walks up the inheritance tree to find the value in
93 question.
94 getClassVar($name)
96 Returns the value of the class variable whose name is $name (if
97 any).
98 setClassVar($name,$value)
100 Sets the value of the class variable whose name is $name to the
101 value $value. You can retrieve the value of $name via either
102 getClassVar or getClassInstVar (see above).
103 setDebugObject(<NOCpulse::Debug instance>)
105 Set the debug object for the entity in question. NOTE that how
106 this is called has tremendous bearing on what it does. If you call
107 it from the perspective of an instance, a private debug instance
108 will be stored for the instance in question. If you call it from
109 the perspective of a class, a class variable will be stored which
110 will be retrieved via the class instance variable mechanism
111 (meaning that 'inheritance' will occur).
112 defaultDebugObject()
114 Returns the default debug object. You can override this. By
115 default it returns an instance that was built when the
116 NOCpulse::Object module was loaded. The module in question will
117 have a single level 1 literal stream in it.
118 debugObject()
120 Returns the debug object (if any) for the entity in question. This
121 can be called from either a class or an instance perspective. If
122 called in an instance perspective, a check is performed to see if
123 the instance in question has its own debug object (and returns it
124 if true). Otherwise or if the calling context is from that of a
125 class, attempts to retrieve a class instance version of a debug
126 object (see setDebugObject and getClassInstVar). Failing all of
127 that it returns defaultDebugObject().
128 dprint(<$level>,<@msgs>);
130 Prints @msgs via $self->debugObject (regardless of whether $self is
131 an instance or a class) at level $level.
132 new()
134 Creates a new instance of the class, ensuring that all instance
135 variables are built via the instVarDefinitions() method (below).
136 newInitialized(@parameters)
138 Creates a new instance of the class via a call to new(), then calls
139 its initialize() method, passing anything that you passed as a
140 parameter on to it.
141 Your override must return whatever you want the result of the call
143 to the constructor to be - THIS IS VERY IMPORTANT!! Default
144 behavior is to return the instance, and usually that is what you
145 will want to do as well
146 fromStoreString()
148 Re-creates an instance of an arbitrary class from a string created
149 by the storeString() method. Uses the FreezeThaw thaw() method.
150
152 instVarDefinitions()
153 Subclasses that wish to define instance variables should override
154 this method. The override implementation should contain a call to
155 $self->SUPER::instVarDefinitions followed by one or more calls to
156 $self->addInstVar().
157 NOTE: it is possible to bypass this step and make calls to
159 addInstVar() or even just make calls to set_xxx or set() methods
160 (described below) in an ad-hoc fashion. The reasoning behind the
161 instVarDefinitions() mechanism is that explicit definitions of
162 instance variables adds substantially to code clarity.
163 addInstVar($name[,$value])
165 Defines an instance variable for the instance whose name is $name
166 and whose (optional) value is $value. Variables defined in this
167 manner can be accessed via the get_ and set_ methods that get
168 "AUTOLOADed" as described below.
169 initialize(@parameters)
171 Subclasses who wish to have an initialization sequence beyond what
172 happens in instVarDefinitions() should override this. This method
173 will recieve any parameters that might have been passed to
174 ref($self)->newInitialized(), so your override can use that
175 information as necessary. Your override should return whatever you
176 want the result of the constructor call to be if you're calling
177 this via newInitialized()!! Usually you'll want this to be the
178 instance, which is what the default behavior is here
179 printString()
181 Returns a string that expresses the contents of the object. This
182 method does a dump of every instance variable in a given instance,
183 and and in addition will descend into any other classes that it
184 finds along the way. The abstract implementation is useful as a
185 diagnostic. Smalltalk fans may wish to override this in class-
186 specific ways.
187 asString()
189 Calls printString() (above)
190 storeString()
192 Returns a "frozen" version of the current instance in the form of a
193 string via the FreezeThaw freeze() method. The string can be
194 stored in a file for later "thawing" via a call to
195 NOCpulse::Object->fromStoreString() (above).
196 NOTE: No clamping is performed - if you have self-referential
198 instances you will get EVERYTHING when you call this. If you are
199 planning on doing object persistence with this mechanism, do some
200 sort of hash table lookup reference instead.
201 configValue($name[,$item])
203 Calls the class side ConfigValue() method (above) and returns its
204 result.
205 has($name)
207 Returns true if an instance variable called $name exists for the
208 instance in question. Calls to this method can be constructed as
209 "$self->has_name()"; see AUTOLOAD below
210 get($name)
212 Returns the value of the instance variable called $name. Calls to
213 this method can be constructed as "$self->get_name()" see AUTOLOAD
214 below
215 set($name,$value)
217 Sets the value of the instance variable called $name to $value.
218 Calls to this method can be constructed as
219 "$self->set_name($value)" see AUTOLOAD below
220 delete($name)
222 Removes the the instance variable called $name from the instance in
223 question. Calls to this method can be constructed as
224 "$self->delete_name()" see AUTOLOAD below
225 doesNotUnderstand($class,$message,@params)
227 Called by AUTOLOAD (see below) if the message sent to the object
228 cannot be resolved. This method gives you a chance to catch these
229 things and provide AUTOLOAD like behavior, but with inheritance.
230 The fallthrough behavior is to croak with an informative message.
231 One of the really nice things about NOCpulse::Object is that you
233 will not have to worry about goofy hash dereferencing to get at
234 your variables. NOCpulse::Object uses the doesNotUnderstand
235 mechanism to generate has_, get_, set_, and delete_ methods for
236 you.
237 As an example, if you defined instance variables thusly...
239 sub instVarDefinitions
241 {
242 my $self = shift();
243 $self->addInstVar('foo');
244 $self->addInstVar('bar');
245 }
246 ..., your instance will (from that point on) behave as if a number
248 of accessor methods had been defined for it as well, so...
249 my $object = MyClass->newInitialized;
251 $object->set_foo('a value');
252 $object->set_bar('another value');
253 print $object->get_foo." ".$object->get_bar."\n";
254 ...will work nicely.
256
258 Hey! The above document had some coding errors, which are explained
259 below:
260 Around line 545:
262 You forgot a '=back' before '=head1'
263 Around line 686:
265 You forgot a '=back' before '=head1'
266perl v5.12.0 2009-02-18 Object(3)