view release on metacpan or  search on metacpan

ObjectivePerl.pm  view on Meta::CPAN

without all the mess.  Keeps things clean.


=head2 Uses

There are currently two ways to use ObjectivePerl.  The
easiest way is to just say

   use ObjectivePerl;

and everything after that in your source file
will be parsed for ObjectivePerl declarations.  It won't touch
anything else.

Otherwise, you can instantiate the parser and do it yourself:

   use ObjectivePerl::Parser;

   my $parser = ObjectivePerl->new();
   $parser->initWithFile("somePerlFile.pl");
   $parser->dump();

to see what's going on.

=head1 HOW DOES IT WORK?

Well, this version is a bit of a kludge.  It works as a
perl source filter, which means it actually rewrites your
perl code on the fly.  This is not in itself a bad thing;
generating perl code from some non-perl source is pretty
common.  However, it has some disadvantages, which you
can read about below in the B<BUGS> section.

The parser sifts through your code first looking for class
declarations.  If it finds one, it parses it and translates it
into perl.  If it notices that the class descends from an
as-yet-unparsed class, it suspends parsing until that 
super-class is imported (and parsed), and then resumes
parsing where it left off.  This is to enable it to import
the symbols (well, instance variable declarations chiefly)
from the parent class B<before> processing the current class;
it has to do this in order to determine which instance variables
can be used in methods in the current class.  After
that, it locates and rewrites method definitions from
the ObjectivePerl syntax into regular perl subs, locates
any instance variables that are used in methods, and writes out
some perl to import those into the method.  After that, perl
returns control to the newly rewritten program and if all goes well,
your code will be executing.

=head2 Message Dispatch

If you define methods using the -/+ syntax, ObjectivePerl will
translate those method definitions into regular perl subs with
names based on the method name and its arguments.  You can then
invoke those methods using obj-c style messages.  However,
there are often times when you need to call older perl code that
does not list its arguments in its signature, or perhaps you wish
to invoke a method across the PerlObjCBridge in OSX.  To do
this transparently, the ObjectivePerl runtime uses a method lookup
cascade that works as follows:

    1. It tries to find the correctly-defined method
       for the invocation using ObjectivePerl syntax
    2. (NEW in 0.03 for CamelBones Compatibility) 
       It tries to find a method whose name corresponds
       to the message name and its argument list, separated
       by underscores, so for this invocation:

       ~[$myObject appendToResponse:$response inContext:$context];

	   it will try to find a perl sub called "appendToResponse_inContext".
    3. It tries to find a method whose name corresponds to the
       message name and its argument list, so for this invocation:

      ~[$myObject appendToResponse:$response inContext:$context];

       it will try to find a perl sub called "appendToResponseInContext".
    4. It will try to find a method with the same name
       as step 2 but with a single underscore appended for each
       argument (so in the case of the example, it will search
       for "appendToResponseInContext__").
    5. Failing all of these, it checks if the receiver of the
       message has a method called "handleUnknownSelector", and
       if it does, it invokes that method with the message name
       and selector array as arguments.


=head2 DEBUGGING

Right now one of the trickiest things is debugging the ObjectivePerl
code, because the line numbers reported by the perl runtime correspond
to the translated line numbers, not the line numbers in your source.
Moreover, the messaging runtime is a bit obtuse, so it's often very nice
to be able to see a trace of messages being passed.  To make both of
these debugging problems a bit easier, I've added a "debug" option...

   use ObjectivePerl debug => MASK;

where MASK is made up of:

	$DEBUG_SOURCE    = 0x0001;
	$DEBUG_MESSAGING = 0x0002;
	$DEBUG_ALL       = 0xffff;

so to turn on message and source debugging, use

	use ObjectivePerl debug => 0x0003;

and so on.  If you turn on message debugging, you'll see all the messages
fly by as they're sent.

To use "source" debugging, wrap your source with these:

   #OBJP_DEBUG_START
   ...
   #OBJP_DEBUG_END

and when it's translated, the translated source will be dumped out for you.
Yeah, it's a nasty kludge.  A better solution awaits.