PURPOSE

Allows you set up your module so it can easily provide a standard interface as well as an object-oriented interface to its users.

DESCRIPTION

Class::OOorNO helps your module handle the input for its subroutines whether called in object-oriented style (as object methods or class methods with the arrow syntax ->), or in functional programming style (as subroutines imported to the caller's namespace via Exporter).

The bulk of this module comprises a lightweight, pure-Perl emulation of the Devel::Caller library's called_as_method() routine which is written in C.

Devel::Caller dives deep into the internals of of the Perl interpreter (see perlguts) to trace stack frames and can get the input for any call in the stack. It's really handy for Devel::opment and debugging.

This module is much more lightweight and focuses more on your module's Class:: methods themselves.

EXPORT

None by default.

EXPORT_OK

EXPORT_TAGS

:all (exports all of @EXPORT_OK)

METHODS

myself()

Syntax:myself(@_)

If your subroutine has been called as an object method, a reference to the object will be returned. If your subroutine has been called as a class method, the name of class itself will be returned as a string. Otherwise, a value of undef is returned.

OOorNO()

Syntax:OOorNO(@_)

If your subroutine has been called as an object method or as a class method, a value of 1 will be returned, otherwise a false value (an empty string, eg- '') will be returned.

myargs()

Syntax:myargs(@_)

This method retrieves the input sent to your class methods and returns it untouched, with the exception that if a blessed object reference from the same namespace as the caller is found in $_[0], it will be not be included with the rest of the arguments when they are returned. Make note that the special variable "@_" for your routine is not altered in any way by calling this method. You can still use and manipulate it as you normally would.

Purpose of OOorNO::myargs

This simply allows the methods in your class to get their argment list quickly without having to check if they were called procedurally or with object-oriented notation.

Caveat:

If you are expecting a blessed object reference from your package to be in $_[0] regardless of the way your method was called -don't use this method to get your arguments; that reference you're expecting will obviously be excluded from the list you get back from myargs if you do.

coerce_array()

Syntax:coerce_array(@array/(list))

This method retrieves input sent to your class methods when called with name-value pairs and returns an anonymous hash reference whose keys and values correspond to the input argument names and their respective values. If nothing is passed to it, an empty hash reference will be returned, eg- { }

It's common practice for Perl modules to accept name-value pairs for their methods, and because @_ is an array it is easy to encounter warnings and errors when this isn't handled correctly. An example of what this kind of call would look like is shown below in the imaginary subroutine "Your::Class::method()"

Quite often a class method will use code such as this to handle name-value paired input:

sub foo {
my($class) = shift;
my(%args) = @_; ...

-and/or-

sub bar {
my($args) = { @_ }; ...

What's Wrong With That?

While this practice is not evil, it can be error-prone in situations where:

Your class method is called in procedural style and expects that the first element in @_ is a blessed object reference.

Your class method is errantly called with an unbalanced set of name-value pairs, or one or more named arguments get passed with undefined values.

You want to give your module the ability to export any or all of its methods by using the Exporter module, but still want to maintain an object-oriented interface to your module as well. An example of a well known module which does this is CGI.pm. It is written to provide both a standard procedural interface as well as an object-oriented one. You can call its methods either way:

When these situations occur, class methods sorting out name-value paired input using the common problematic technique (demonstrated above in "Pitfalls)" encounter problems such as undesired program behavior, general errors, and warnings -both fatal and non-fatal. Problems include:

Argument sets that get reversed; the argument names become the hash values and the argument values become the hash keys which is exactly the opposite of the desired behavior.

The entire arument hash/hashref gets turned into a mess of mixed up keys and values that don't reflect the actual input at all. Instead, you get hash keys containing both argument names and argument values.

The argument hash/hashref is created with an uneven number of elements and/or uninitialized values.

Warnings (see perldiag) resulting from the above mentioned situations could include any the following (Some of these don't apply unless you run your program under the warnings pragma) like you should.

Can't coerce array into hash

This is a fatal warning, eg- if you see it your program failed and execution aborted.)

Odd number of elements in hash assignment

non-fatal.

Not a %s reference

-where %s is probably "HASH", though it could be complaining about a non-reference to any data type that your routine may be attempting to treat as a reference. This is often the result of a class method being called in procedural style rather than in the object-oriented style using the arrow -\> syntax. The class method expects the first argument to be an object reference, when it is clearly not. (This warning is fatal as well.)

Can't call method %s on unblessed reference

This is another a fatal warning, and will occur under the same circumstances that surround the warning described immediately above. The class method expects the first argument to be an object reference when it's not.

PREREQUISITES

None.

BUGS

This documentation isn't done yet, as you can see. This is being rectified as quickly as possible. Please excercise caution if you choose to use this code before it can be further documented for you. It is present on CPAN at this time despite its unfinished condition in order to provide support for the File::Util module which lists Class::OOorNO among its prerequisites. Please excuse the inconvenience.