Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Class::MethodMaker::EnUser(Contributed Perl DocumClass::MethodMaker::Engine(3)

NAME
       Class::MethodMaker::Engine - The	parameter passing, method installation
       & non-data-structure methods of Class::MethodMaker.

SYNOPSIS
       This class is for internal implementation only.	It is not a public
       API.

       The non-data-structure methods do form part of the public API, but not
       called directly:	rather,	called through the "use"/"import" interface,
       as for data-structure methods.

The Class::MethodMaker Method Installation Engine
   import
       This performs argument parsing ready for	calling	create_methods.	 In
       particular, this	is the point at	which v1 & v2 calls are	distinguished.

       This is implicitly called as part of a "use" statement:

	 use Class::MethodMaker
	   [ scalar => [qw/ foo	bar baz	/],
	     new    => [qw/ new	/]	  ,
	   ];

       is equivalent to

	 Class::MethodMaker->import([scalar => [qw/ foo	bar baz	/],
				     new    => [qw/ new	/]	  ,
				    ]);

       See perldoc -f use for details of this equivalence.

       The methods created are installed into the class	calling	the import -
       or more accurately, the first class up the calling stack	that is	not
       "Class::MethodMaker" or a subclass thereof.

       SYNOPSIS
	     Class::MethodMaker->import([scalar	=> [+{ -type   => 'File::Stat',
						       -forward	=> [qw/	mode size /],
						       '*_foo' => '*_fig',
						       '*_gop' => undef,
						       '*_bar' => '*_bar',
						       '*_hal' => '*_sal',
						      },
						    qw/	-static	bob /,
						   ]
					]);

   parse_options
       Parse the arguments given to import and call create_methods
       appropriately.  See main	text for options syntax.

       SYNOPSIS
	     Class::MethodMaker->parse_options('TargetClass',
					       [scalar =>
						 [{ -type => 'File::stat',
						    -forward =>	[qw/ mode
								     size /],
						    '*_foo' => '*_fig',
						    '*_gop' => undef,
						    '*_bar' => '*_bar',
						    '*_hal' => '*_sal',
						  },
						  qw( -static bob ),
						 ]])},

	     Class::MethodMaker->parse_options('TargetClass2',
					       [scalar =>
						 ['baz',
						  { -type => 'File::stat',
						    -forward =>	[qw/ mode
								     size /],
						    '*_foo' => '*_fog',
						    '*_bar' => '*_bar',
						    '*_hal' => '*_sal',
						  },
						  qw( -static bob ),
						 ]],
					       +{ -type	=> 'Math::BigInt', },
					       +{'*_foo' => '*_fig',
						 '*_gop' => undef,},
					      )},

       ARGUMENTS
	   target_class
	       The class into which to install components

	   args
	       The arguments to	parse, as a single arrayref.

	   options
	       A hashref of options to apply to	all components created by this
	       call (subject to	overriding by explicit option calls).

	   renames
	       A hashref of renames to apply to	all components created by this
	       call (subject to	overriding by explicit rename calls).

   create_methods
       Add methods to a	class.	Methods	for multiple components	may be added
       this way, but create_methods handles only one set of options.
       parse_options is	responsible for	sorting	which options to apply to
       which components, and calling create_methods appropriately.

       SYNOPSIS
	     Class::MethodMaker->create_methods($target_class,
						scalar => bob,
						+{ static => 1,
						   type	  => 'File::Stat',
						   forward => [qw/ mode	size /], },
						+{ '*_foo' => '*_fig',
						   '*_gop' => undef,
						   '*_bar' => '*_bar',
						   '*_hal' => '*_sal', }
					       );

       ARGUMENTS
	   targetclass
	       The class to add	methods	to.

	   type
	       The basic data structure	to use for the component, e.g.,
	       "scalar".

	   compname
	       Component name.	The name must be a valid identifier, i.e., a
	       continuous non-empty string of word ("\w") characters, of which
	       the first may not be a digit.

	   options
	       A hashref.  Some	options	("static", "type", "default",
	       "default_ctor") are handled by the auto-extender.  These	will
	       be invoked if the name is present as a key and the value	is
	       true.  Any other	options	are passed through to the method in
	       question.  The options should be	named as-is; no	leading	hyphen
	       should be applied (i.e.,	use "{static =>	1}" not	"{-static =>
	       1}").

	   renames
	       A list of customer renames.  It is a hashref from method	name
	       to rename.  The method name is the generic name (i.e.,
	       featuring a "*" to replace with the component name).  The
	       rename is the value to rename with.  It may itself contain a
	       "*" to replace with the component name.	If rename is undef,
	       the method is not installed.  For methods that would not	be
	       installed by default, use a rename value	that is	the same as
	       the method name.

	       So, if a	type would normally install methods

		 '*_foo', '*_gop', '*_tom'

	       and optionally installs (but not	by default)

		 '*_bar', '*_wiz', '*_hal'

	       using a renames value of

		 { '*_foo' => '*_fig',
		   '*_gop' => undef,
		   '*_bar' => '*_bar',
		   '*_hal' => '*_sal',
		 }

	       with a component	name of	"xx", then *_foo is installed as
	       "xx_fig", *_bar is installed as "xx_bar", *_wiz is not
	       installed, *_hal	is installed as	"xx_sal", *_gop	is not
	       installed, and *_tom is installed as "xx_tom".

	       The value may actually be an arrayref, in which case the
	       function	may be called by any of	the multiple names specified.

   install_methods
       SYNOPSIS
	     Class::MethodMaker->install_methods
	       ($classname, { incr => sub { $i++ },
			      decr => sub { $i-- },
			    }
	       );

       ARGUMENTS
	   target
	       The class into which the	methods	are to be installed

	   methods
	       The methods to install, as a hashref.  Keys are the method
	       names; values are the methods themselves, as code refs.

Non-data-structure components
   new
	 use Class::MethodMaker
	   [ new => 'new' ];

       Creates a basic constructor.

       Takes a single string or	a reference to an array	of strings as its
       argument.  For each string creates a simple method that creates and
       returns an object of the	appropriate class.

       The generated method may	be called as a class method, as	usual, or as
       in instance method, in which case a new object of the same class	as the
       instance	will be	created.

       Options

       -hash
	   The constructor will	accept as arguments a list of pairs, from
	   component name to initial value.  For each pair, the	named
	   component is	initialized by calling the method of the same name
	   with	the given value.  E.g.,

	     package MyClass;
	     use Class::MethodMaker
	       [ new	=> [qw/	-hash new /],
		 scalar	=> [qw/	b c /],
	       ];

	     sub d {
	       my $self	= shift;
	       $self->{d} = $_[0]
		 if @_;
	       return $self->{d};
	     }

	     package main;
	     # The statement below implicitly calls
	     # $m->b(1); $m->c(2); $m->d(3)
	     # on the newly constructed	m.
	     my	$m = MyClass->new(b => 1, c => 2, d => 3);

	   Note	that this can also call	user-supplied methods that have	the
	   name	of the component.

	   Instead of a	list of	pairs, a single	hashref	may also be passed,
	   which will be expanded appropriately.  So the above is equivalent
	   to:

	     my	$m = MyClass->new({ b => 1, c => 2, d => 3 });

	   Advanced Users: Class::MethodMaker method renaming is taken into
	   account, so even if the "*" method is renamed or removed, this will
	   still work.

       -init
	   This	option causes the new method to	call an	initializer method.
	   The method is called	"init" (original, eh?) by default, but the
	   option may be given an alternative value.  The init method is
	   passed any arguments	that were passed to the	constructor, but the
	   method is invoked on	the newly constructed instance.

	     use Class::MethodMaker
	       [ new =>	[qw/ -init new1	/, { -init => 'bob' } => 'init2' ]];

	   Constructing	with new1 involves an implicit call to "init", whilst
	   constructing	with new2 involves an implicit call to "bob" (instead
	   of "init").

	   It is the responsibility of the user	to ensure that an "init"
	   method (or whatever name) is	defined.

       -singleton
	   Creates a basic constructor which only ever returns a single
	   instance of the class: i.e.,	after the first	call, repeated calls
	   to this constructor return the same instance.  Note that the
	   instance is instantiated at the time	of the first call, not before.

   abstract
	 use Class::MethodMaker
	   [ abstract => [ qw /	foo bar	baz / ]	];

       This creates a number of	methods	that will die if called.  This is
       intended	to support the use of abstract methods,	that must be
       overridden in a useful subclass.

   copy
	 use Class::MethodMaker
	   [ copy => [qw/ shallow -deep	deep /]	];

       This creates method that	produce	a copy of self.	 The copy is a by
       default a shallow copy; any references will be shared by	the instance
       upon which the method is	called and the returned	newborn.  One option
       is taken, "-deep", which	causes the method to create deep copies
       instead (i.e., references are copied recursively).

       Implementation Note:

       Deep copies are performed using the "Storable" module if	available,
       else "Data::Dumper".  The "Storable" module is liable to	be much
       quicker.	 However, this implementation note is not an API
       specification: the implementation details are open to change in a
       future version as faster/better ways of performing a deep copy become
       available.

       Note that deep copying does not currently support the copying of
       coderefs, ties or XS-based objects.

AUTHOR
       Martyn J. Pearce	<fluffy@cpan.org>

perl v5.24.1			  2015-03-31	 Class::MethodMaker::Engine(3)

NAME | SYNOPSIS | The Class::MethodMaker Method Installation Engine | Non-data-structure components | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Class::MethodMaker::Engine&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help