From: Dave Rolsky <autarch@houseabsolute.urth.org> Date: Tue, 17 Mar 2009 17:24:53 +0000 (-0500) Subject: Docs for CMOP::Package X-Git-Tag: 0.78_02~18 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b3d2484f6cb8c2a5caa190eb242449f0c6289ab6;p=gitmo%2FClass-MOP.git Docs for CMOP::Package --- diff --git a/lib/Class/MOP/Package.pm b/lib/Class/MOP/Package.pm index 8e67889..4057138 100644 --- a/lib/Class/MOP/Package.pm +++ b/lib/Class/MOP/Package.pm @@ -287,83 +287,84 @@ Class::MOP::Package - Package Meta Object =head1 DESCRIPTION -This is an abstraction of a Perl 5 package, it is a superclass of -L<Class::MOP::Class> and provides all of the symbol table -introspection methods. - -=head1 INHERITANCE - -B<Class::MOP::Package> is a subclass of L<Class::MOP::Object> +The Package Protocol provides an abstraction of a Perl 5 package. A +package is basically namespace, and this module provides methods for +looking at and changing that namespace's symbol table. =head1 METHODS =over 4 -=item B<meta> +=item B<< Class::MOP::Package->initialize($package_name) >> + +This method creates a new C<Class::MOP::Package> instance which +represents specified package. If an existing metaclass object exists +for the package, that will be returned instead. + +=item B<< Class::MOP::Package->reinitialize($package_name) >> -Returns a metaclass for this package. +This method forcibly removes any existing metaclass for the package +before calling C<initialize> -=item B<initialize ($package_name)> +Do not call this unless you know what you are doing. -This will initialize a Class::MOP::Package instance which represents -the package of C<$package_name>. +=item B<< $metapackage->name >> -=item B<reinitialize ($package_name, %options)> +This is returns the package's name, as passed to the constructor. -This removes the old metaclass, and creates a new one in it's place. -Do B<not> use this unless you really know what you are doing, it could -very easily make a very large mess of your program. +=item B<< $metapackage->namespace >> -=item B<name> +This returns a hash reference to the package's symbol table. The keys +are symbol names and the values are typeglob references. -This is a read-only attribute which returns the package name for the -given instance. +=item B<< $metapackage->add_package_symbol($variable_name, $initial_value) >> -=item B<namespace> +This method accepts a variable name and an optional initial value. The +C<$variable_name> must contain a leading sigil. -This returns a HASH reference to the symbol table. The keys of the -HASH are the symbol names, and the values are typeglob references. +This method creates the variable in the package's symbol table, and +sets it to the initial value if one was provided. -=item B<add_package_symbol ($variable_name, ?$initial_value)> +=item B<< $metapackage->get_package_symbol($variable_name) >> -Given a C<$variable_name>, which must contain a leading sigil, this -method will create that variable within the package which houses the -class. It also takes an optional C<$initial_value>, which must be a -reference of the same type as the sigil of the C<$variable_name> -implies. +Given a variable name, this method returns the variable as a reference +or undef if it does not exist. The C<$variable_name> must contain a +leading sigil. -=item B<get_package_symbol ($variable_name)> +=item B<< $metapackage->has_package_symbol($variable_name) >> -This will return a reference to the package variable in -C<$variable_name>. +Returns true if there is a package variable defined for +C<$variable_name>. The C<$variable_name> must contain a leading sigil. -=item B<has_package_symbol ($variable_name)> +=item B<< $metapackage->remove_package_symbol($variable_name) >> -Returns true (C<1>) if there is a package variable defined for -C<$variable_name>, and false (C<0>) otherwise. +This will remove the package variable specified C<$variable_name>. The +C<$variable_name> must contain a leading sigil. -=item B<remove_package_symbol ($variable_name)> +=item B<< $metapackage->remove_package_glob($glob_name) >> -This will attempt to remove the package variable at C<$variable_name>. +Given the name of a glob, this will remove that glob from the +package's symbol table. Glob names do not include a sigil. Removing +the glob removes all variables and subroutines with the specified +name. -=item B<remove_package_glob ($glob_name)> +=item B<< $metapackage->list_all_package_symbols($type_filter) >> -This will attempt to remove the entire typeglob associated with -C<$glob_name> from the package. +This will list all the glob names associated with the current +package. These names do not have leading sigils. -=item B<list_all_package_symbols (?$type_filter)> +You can provide an optional type filter, which should be one of +'SCALAR', 'ARRAY', 'HASH', or 'CODE'. -This will list all the glob names associated with the current package. -By inspecting the globs returned you can discern all the variables in -the package. +=item B<< $metapackage->get_all_package_symbols($type_filter) >> -By passing a C<$type_filter>, you can limit the list to only those -which match the filter (either SCALAR, ARRAY, HASH or CODE). +This works much like C<list_all_package_symbols>, but it returns a +hash reference. The keys are glob names and the values are references +to the value for that name. -=item B<get_all_package_symbols (?$type_filter)> +=item B<< Class::MOP::Package->meta >> -Works exactly like C<list_all_package_symbols> but returns a HASH of -name => thing mapping instead of just an ARRAY of names. +This will return a L<Class::MOP::Class> instance for this class. =back