home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _79edd7f33a140f40357f75fe3c77e052 < prev    next >
Text File  |  2000-03-23  |  15KB  |  353 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>B<Class::MethodMaker> - a module for creating generic methods</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> B<Class::MethodMaker> - a module for creating generic methods</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#supported method types">SUPPORTED METHOD TYPES</A></LI>
  26.     <UL>
  27.  
  28.         <LI><A HREF="#new">new</A></LI>
  29.         <LI><A HREF="#new_with_init">new_with_init</A></LI>
  30.         <LI><A HREF="#new_hash_init">new_hash_init</A></LI>
  31.         <LI><A HREF="#get_set">get_set</A></LI>
  32.         <LI><A HREF="#get_concat">get_concat</A></LI>
  33.         <LI><A HREF="#grouped_fields">grouped_fields</A></LI>
  34.         <LI><A HREF="#object">object</A></LI>
  35.         <LI><A HREF="#boolean">boolean</A></LI>
  36.         <LI><A HREF="#struct">struct</A></LI>
  37.         <LI><A HREF="#listed_attrib">listed_attrib</A></LI>
  38.         <LI><A HREF="#key_attrib">key_attrib</A></LI>
  39.         <LI><A HREF="#key_with_create">key_with_create</A></LI>
  40.         <LI><A HREF="#list">list</A></LI>
  41.         <LI><A HREF="#hash">hash</A></LI>
  42.         <LI><A HREF="#code">code</A></LI>
  43.         <LI><A HREF="#method">method</A></LI>
  44.         <LI><A HREF="#interface">interface</A></LI>
  45.     </UL>
  46.  
  47.     <LI><A HREF="#addding new method types">ADDDING NEW METHOD TYPES</A></LI>
  48.     <LI><A HREF="#version">VERSION</A></LI>
  49. </UL>
  50. <!-- INDEX END -->
  51.  
  52. <HR>
  53. <P>
  54. <H1><A NAME="name">NAME</A></H1>
  55. <P><STRONG>Class::MethodMaker</STRONG> - a module for creating generic methods</P>
  56. <P>
  57. <HR>
  58. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  59. <UL>
  60. <LI>Linux</LI>
  61. <LI>Solaris</LI>
  62. <LI>Windows</LI>
  63. </UL>
  64. <HR>
  65. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  66. <P>use Class::MethodMaker
  67.   new_with_init => 'new',
  68.   get_set       => [ qw /foo bar baz / ];</P>
  69. <P>
  70. <HR>
  71. <H1><A NAME="description">DESCRIPTION</A></H1>
  72. <P>This module solves the problem of having to write a bazillion get/set
  73. methods that are all the same. The argument to 'use' is a hash whose keys
  74. are the names of types of generic methods generated by MethodMaker and
  75. whose values tell method maker what methods to make. (More precisely, the
  76. keys are the names of MethodMaker methods (methods that write methods)
  77. and the values are the arguments to those methods.</P>
  78. <P>
  79. <HR>
  80. <H1><A NAME="supported method types">SUPPORTED METHOD TYPES</A></H1>
  81. <P>
  82. <H2><A NAME="new">new</A></H2>
  83. <P>Creates a basic constructor.</P>
  84. <P>Takes a single string or a reference to an array of strings as its
  85. argument. For each string creates a method of the form:</P>
  86. <PRE>
  87.     sub <string> {
  88.       my ($class, @args) = @_;
  89.       my $self = {};
  90.       bless $self, $class;
  91.     }</PRE>
  92. <P>
  93. <H2><A NAME="new_with_init">new_with_init</A></H2>
  94. <P>Creates a basic constructor which calls a method named init after
  95. instatiating the object. The <EM>init</EM>() method should be defined in the class
  96. using MethodMaker.</P>
  97. <P>Takes a single string or a reference to an array of strings as its
  98. argument. For each string creates a method of the form listed below.</P>
  99. <PRE>
  100.     sub <string> {
  101.       my ($class, @args) = @_;
  102.       my $self = {};
  103.       bless $self, $class;
  104.       $self->init(@args);
  105.       $self;
  106.     }</PRE>
  107. <P>
  108. <H2><A NAME="new_hash_init">new_hash_init</A></H2>
  109. <P>Creates a basic constructor which accepts a hash of slot-name/value pairs
  110. with which to initialize the object. The slot-names are interpreted as
  111. the names of methods that can be called on the object after it is created
  112. and the values are the arguments to be passed to those methods.</P>
  113. <P>Takes a single string or a reference to an array of strings as its
  114. argument. For each string creates a method of the form listed below. Note
  115. that this method can be called on an existing objec, which allows it to
  116. be combined with new_with_init (see above) to provide some default
  117. values. (Basically, declare a new_with_init method, say 'new' and a
  118. new_hash_init method, for example, 'hash_init' and then in the init
  119. method, you can call modify or add to the %args hash and then call
  120. hash_init.)</P>
  121. <PRE>
  122.     sub <string> {
  123.       my ($class, %args) = @_;
  124.       my $self = {};
  125.       bless $self, $class;
  126.       foreach (keys %args) {
  127.         $self->$_($args{$_});
  128.       }
  129.       $self;
  130.     }</PRE>
  131. <P>
  132. <H2><A NAME="get_set">get_set</A></H2>
  133. <P>Takes a single string or a reference to an array of strings as its
  134. argument. For each string, x creates two methods:</P>
  135. <PRE>
  136.   sub x {
  137.     my ($self, $new) = @_;
  138.     defined $new and $self->{$name} = $new;
  139.     $self->{$name};
  140.   }</PRE>
  141. <PRE>
  142.   sub clear_x
  143.     my ($self) = @_;
  144.     $self->{$name} = undef;
  145.   }</PRE>
  146. <P>This is your basic get/set method, and can be used for slots containing
  147. any scalar value, including references to non-scalar data. Note, however,
  148. that MethodMaker has meta-methods that define more useful sets of methods
  149. for slots containing references to lists, hashes, and objects.</P>
  150. <P>
  151. <H2><A NAME="get_concat">get_concat</A></H2>
  152. <P>Like get_set except sets don't clear out the original value, but instead
  153. concatenate the new value to the existing one. Thus these slots are only
  154. good for plain scalars. Also, like get_set, defines clear_foo method.</P>
  155. <P>
  156. <H2><A NAME="grouped_fields">grouped_fields</A></H2>
  157. <P>Creates get/set methods like get_set but also defines a method which
  158. returns a list of the slots in the group.</P>
  159. <PRE>
  160.   grouped_fields methods
  161.     some_group => [ qw / field1 field2 field3 / ];</PRE>
  162. <P>Its argument list is parsed as a hash of group-name => field-list
  163. pairs. Get-set methods are defined for all the fields and a method with
  164. the name of the group is defined which returns the list of fields in the
  165. group.</P>
  166. <P>
  167. <H2><A NAME="object">object</A></H2>
  168. <P>Creates methods for accessing a slot that contains an object of a given
  169. class as well as methods to automatically pass method calls onto the
  170. object stored in that slot.</P>
  171. <PRE>
  172.     object => [
  173.                'Foo' => 'phooey',
  174.                'Bar' => [ qw / bar1 bar2 bar3 / ],
  175.                'Baz' => {
  176.                          slot => 'foo',
  177.                          comp_mthds => [ qw / bar baz / ]
  178.                         },
  179.               ];</PRE>
  180. <P>This is a hairy one. The main argument should be a reference to an
  181. array. The array should contain pairs of class => sub-argument
  182. pairs. The sub-argument's are further parsed thusly:</P>
  183. <P>If the sub-argument is a simple string or a reference to an array of
  184. strings (as is the case for Foo and Bar above), for each string a get/set
  185. method is created that can store an object of that class. (The get/set
  186. method, if called with a reference to an object of the given class as the
  187. first argument, stores it in the slot. If the slot isn't filled yet it
  188. creates an object by calling the given class's new method. Any arguments
  189. passed to the get/set method are passed on to new. In all cases the
  190. object now stored in the slot is returned.</P>
  191. <P>If the sub-argument is a ref to a hash (as with Baz, above) then the
  192. hash should have two keys: slot and comp_mthds. The value indexed by
  193. 'slot' will be interpreted as the is in (a). The value or values (ref to
  194. an array if plural) indexed by 'comp_mthds' are the names of methods
  195. which should be ``inherited'' from the object stored in the slot. That is,
  196. using the example above, a method, foo, is created in the class that
  197. calls MethodMaker, which can get and set the value of a slot containing
  198. an object of class Baz. Class Baz in turn defines two methods, 'bar', and
  199. 'baz'. Two more methods are created in the class using MethodMaker, named
  200. 'bar' and 'baz' which result in a call to the 'bar' and 'baz' methods,
  201. through the Baz object stored in slot foo.</P>
  202. <P>
  203. <H2><A NAME="boolean">boolean</A></H2>
  204. <PRE>
  205.   boolean => [ qw / foo bar baz / ]</PRE>
  206. <P>Creates methods for setting, checking and clearing flags. All flags
  207. created with this meta-method are stored in a single vector for space
  208. efficiency. The argument to boolean should be a string or a reference to
  209. an array of strings. For each string x it defines several methods: x,
  210. set_x, and clear x. x returns the value of the x-flag. If called with an
  211. argument, it first sets the x-flag to the truth-value of the
  212. argument. set_x is equivalent to <CODE>x(1)</CODE> and clear_x is equivalent to x(0).</P>
  213. <P>Additionally, boolean defines three class method: <EM>bits</EM>, which returns
  214. the vector containing all of the bit fields (remember however that a
  215. vector containing all 0 bits is still true), <EM>boolean_fields</EM>, which returns
  216. a list of all the flags by name, and <EM>bit_dump</EM>, which returns a hash of
  217. the flag-name/flag-value pairs.</P>
  218. <P>
  219. <H2><A NAME="struct">struct</A></H2>
  220. <PRE>
  221.   struct => [ 'foo' => [ qw / foo bar baz / ] ];</PRE>
  222. <P>XXX these docs aren't right yet.</P>
  223. <P>Creates methods for setting, checking and clearing slots in a struct.
  224. All the slots created with this meta-method are stored in a single array
  225. for speed efficiency.  The argument to struct should be a string or a
  226. reference to an array of strings. For each string x it defines two
  227. methods: <EM>x</EM> and <EM>clear_x</EM>. x returns the value of the x-slot. If called with
  228. an argument, it first sets the x-slot to the argument. clear_x sets the
  229. slot to undef.</P>
  230. <P>Additionally, struct defines three class method: <EM>struct</EM>, which returns
  231. the array containing all of the bit fields (remember however that a
  232. vector containing all 0 bits is still true), <EM>boolean_fields</EM>, which returns
  233. a list of all the slots by name, and <EM>bit_dump</EM>, which returns a hash of
  234. the slot-name/slot-value pairs.</P>
  235. <P>
  236. <H2><A NAME="listed_attrib">listed_attrib</A></H2>
  237. <PRE>
  238.   listed_attrib => [ qw / foo bar baz / ]</PRE>
  239. <P>Like <EM>boolean</EM>, <EM>listed_attrib</EM> creates x, set_x, and clear_x
  240. methods. However, it also defines a class method x_objects which returns
  241. a list of the objects which presently have the x-flag set to
  242. true. N.B. listed_attrib does not use the same space efficient
  243. implementation as boolean, so boolean should be prefered unless the
  244. x_objects method is actually needed.</P>
  245. <P>
  246. <H2><A NAME="key_attrib">key_attrib</A></H2>
  247. <PRE>
  248.   key_attrib => [ qw / foo bar baz / ]</PRE>
  249. <P>Creates get/set methods like get/set but also maintains a hash in which
  250. each object is stored under the value of the field when the slot is
  251. set. If an object has a slot set to a value which another object is
  252. already set to the object currently set to that value has that slot set
  253. to undef and the new object will be put into the hash under that
  254. value. (I.e. only one object can have a given key. The method find_x is
  255. defined which if called with any arguments returns a list of the objects
  256. stored under those values in the hash. Called with no arguments, it
  257. returns a reference to the hash.</P>
  258. <P>
  259. <H2><A NAME="key_with_create">key_with_create</A></H2>
  260. <PRE>
  261.   key_with_create => [ qw / foo bar baz / ]</PRE>
  262. <P>Just like key_attrib except the find_x method is defined to call the new
  263. method to create an object if there is no object already stored under any of the keys you give as arguments.</P>
  264. <P>
  265. <H2><A NAME="list">list</A></H2>
  266. <P>Creates several methods for dealing with slots containing list
  267. data. Takes a string or a reference to an array of strings as its
  268. argument and for each string, x, creates the methods: x, push_x, and
  269. pop_x. The method x returns the list of values stored in the slot. In an
  270. array context it returns them as an array and in a scalar context as a
  271. reference to the array. If called with arguments, x will push them onto
  272. the list. push_x and pop_x do about what you would expect.</P>
  273. <P>
  274. <H2><A NAME="hash">hash</A></H2>
  275. <P>Creates a group of methods for dealing with hash data stored in a
  276. slot. Takes a string or a reference to an array of strings and for each
  277. string, x, creates: x, x_keys, x_values, and x_tally. Called with no
  278. arguments x returns the hash stored in the slot, as a hash in an array
  279. context or as a refernce in a scalar context. Called with one argument it
  280. treats the argument as a key and returns the value stored under that key,
  281. or as a list of keys (if it is a reference to a list) and returns the
  282. list of values stored under those keys. Called with more than one
  283. argument, treats them as a series of key/value pairs and adds them to the
  284. hash. x_keys returns the keys of the hash, and x_values returns the list
  285. of values. x_tally takes a list of arguments and for each scalar in the
  286. list increments the value stored in the hash and returns a list of the
  287. current (after the increment) values.</P>
  288. <P>
  289. <H2><A NAME="code">code</A></H2>
  290. <PRE>
  291.   code => [ qw / foo bar baz / ]</PRE>
  292. <P>Creates a slot that holds a code reference. Takes a string or a reference
  293. to a list of string and for each string, x, creates a method <STRONG>x</STRONG> which
  294. if called with one argument which is a CODE reference, it installs that
  295. code in the slot. Otherwise it runs the code stored in the slot with
  296. whatever arguments (including none) were passed in.</P>
  297. <P>
  298. <H2><A NAME="method">method</A></H2>
  299. <PRE>
  300.   method => [ qw / foo bar baz / ]</PRE>
  301. <P>Just like <STRONG>code</STRONG>, except the code is called like a method, with $self as
  302. it's first argument. Basically, you're creating a method which can be
  303. different for each object. Which is sort of weird. But perhaps useful.</P>
  304. <P>
  305. <H2><A NAME="interface">interface</A></H2>
  306. <PRE>
  307.   interface => [ qw / foo bar baz / ]</PRE>
  308. <P>
  309. <HR>
  310. <H1><A NAME="addding new method types">ADDDING NEW METHOD TYPES</A></H1>
  311. <P>MethodMaker is a class that can be inherited. A subclass can define new
  312. method types by writing a method that returns a hash of
  313. method_name/code-reference pairs.</P>
  314. <P>For example a simple sub-class that defines a method type
  315. upper_case_get_set might look like this:</P>
  316. <PRE>
  317.   package Class::MethodMakerSubclass;</PRE>
  318. <PRE>
  319.   use strict;
  320.   use Class::MethodMaker;</PRE>
  321. <PRE>
  322.   @Class::MethodMakerSubclass::ISA = qw ( Class::MethodMaker );</PRE>
  323. <PRE>
  324.   sub upper_case_get_set {
  325.     shift; # we don't need the class name
  326.     my ($name) = @_;
  327.     my %results;
  328.     $results{$name} =
  329.       sub {
  330.         my ($self, $new) = @_;
  331.         defined $new and $self->{$name} = uc $new;
  332.         $self->{$name};
  333.       };
  334.     %results;
  335.   }
  336. </PRE>
  337. <PRE>
  338.  
  339.   1;</PRE>
  340. <P>
  341. <HR>
  342. <H1><A NAME="version">VERSION</A></H1>
  343. <P>Class::MethodMaker v0.92</P>
  344. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  345. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  346. <STRONG><P CLASS=block> B<Class::MethodMaker> - a module for creating generic methods</P></STRONG>
  347. </TD></TR>
  348. </TABLE>
  349.  
  350. </BODY>
  351.  
  352. </HTML>
  353.