view release on metacpan or  search on metacpan

lib/Acme/RPC.pm  view on Meta::CPAN

                reg( $node->{$k}{chr(0)} = $p->{$k} );  # have to do this after assigning in from the recursie call
            }
        } elsif( ! ref($object) ) {
            # XXX how could we represent constant data, as in the case of our $foo = "hi there", or instance data fields, or...?
        }
        return $node;
    }->('main::');
}

sub tryunref {
    my $ob = shift;
    my $request = shift;
    for(1..4) {
        $ob = $$ob if(ref $ob) eq 'REF';
    }
    ref($ob) eq 'REF' and do {
        $request->print("REF derefs to REF four times; probably circular");
        return;
    };
    return $ob;
}

sub tryunobject {
    my $ob = shift;
    my $request = shift;
    if( blessed($ob) and UNIVERSAL::isa($ob, 'HASH') ) {
        $ob = { %$ob };
    } elsif( blessed($ob) and UNIVERSAL::isa($ob, 'ARRAY') ) {
        $ob = [ @$ob ];
    } elsif( blessed($ob) and UNIVERSAL::isa($ob, 'SCALAR') ) {
        $ob = \ ${$ob};
    } elsif( blessed($ob) ) {
        $request->print("object not blessed hash, array or scalar... no logic for converting to JSON, sorry"); 
        return;
    }
    return $ob;
}

END { $continuity->loop }


1;

=head1 NAME

Acme::RPC - Easy remote function and method call and more

=head1 SYNOPSIS

  use Acme::RPC;
  our $test2 = t2->new();

  package t2; 
  sub new { bless {  one => 1 }, $_[0] }; 
  sub add { ($_[1] + $_[2]); }'

Then go to:

  http://localhost:7777/?path=%24test2/add()&action=call&arg0=10&arg1=15

The C<path> part, decoded, reads C<< $test2/add() >>.

=head1 DESCRIPTION

By my estimate, there are over 10,000 RPC modules on CPAN.  Each one makes RPC more
difficult than the one before it.  They all want you to pass tokens back and forth,
register handlers for which methods may be called, create sessions, and so.
With L<Acme::RPC>, there's only one required step:  GET or POST to your method.
And if you don't know which methods are available, L<Acme::RPC> will help you find them.
Even if they're hidden away in objects referenced from inside of closures.

The RPC daemon starts after the program finishes, or whe it does C<< Event::loop >>.

=head2 CGI Parameters

=over 4

=item C<< / >>

(No parameter.)

=item C<< action=dump >>

Gives an index of packages, subroutines, variables in those subroutines, closures in those variables, and so on.

=item C<< output=json >>

Output a JavaScript datastructures (JSON) instead of Perl style L<Data::Dumper> or HTML.
The main index page otherwise prints out HTML (under the assumption that a human will be digging through it)
and other things mostly emit L<Data::Dumper> formatted text.

=item C<< oid=(number) >>

=item C<< path=/path/to/something >>

There are two ways to specify or reference an object:  by it's C<oid> or by the path to navigate to it from the 
main index screen.
JSON and HTML output from the main index screen specifies the oids of each item and the paths can be derived from
the labels in the graph.
With no action specified, it defaults to C<dump>.

=item C<< action=call >>

Invokes a method or code ref.
It does I<not> invoke object references.
Requires either C<oid> or C<path> be specified.
You may also set C<arg0>, C<arg1>, C<arg2> etc GET or POST parameters to pass data into the function.
There's currently no way to pass in an arbitrary object (see TODO below).

=item C<< action=method >>

Used with C<< method=[method name] >> and either an C<< oid=[oid] >> or C<< path=[path] >> to an
object reference, it calls that method on that object.
As above, takes argument data from C<arg0>, C<arg1>, C<arg2>, etc.

=item C<< lazy=1 >>

Avoid rebuilding the entire object graph to speed things up a bit.

=head2 TODO