JavaSc...r::CGI(3pm)

💖 JavaScript::RPC::Server::CGI 💖

okay bestie, so this is a page from the User Contributed Perl Documentation (that's the 3pm manual, iykyk) and it's literally about making remote procedure calls from JavaScript. yes, JavaScript calling your Perl. iconic crossover event.

---

✨ NAME ✨

JavaScript::RPC::Server::CGI — Remote procedure calls from JavaScript 🦋

---

✨ SYNOPSIS ✨

here's the whole vibe, copy-paste ready, no cap:

package MyJSRPC;

use Carp;
use base qw( JavaScript::RPC::Server::CGI );

sub add {
    my $self = shift;
    my @args = @_;
    unless(
        @args == 2 and
        $args[ 0 ] =~ /^\d+$/ and
        $args[ 1 ] =~ /^\d+$/
    ) {
        croak( 'inputs must be digits only' );
    }
    return $args[ 0 ] + $args[ 1 ];
}

sub subtract {
    my $self = shift;
    my @args = @_;
    unless(
        @args == 2 and
        $args[ 0 ] =~ /^\d+$/ and
        $args[ 1 ] =~ /^\d+$/
    ) {
        croak( 'inputs must be digits only' );
    }
    return $args[ 0 ] - $args[ 1 ];
}

package main;

use strict;

my $server = MyJSRPC->new;
$server->process;

like. look at her. subclassing, two methods, process. main character energy fr fr 💅

---

✨ DESCRIPTION ✨

JavaScript::RPC::Server::CGI is a CGI-based server library made to pair with Brent Ashley's JavaScript Remote Scripting (JSRS) client library. it works asynchronously and uses DHTML to deal with the payload. yes queen, DHTML, we love a retro moment 🌸

so the way that this works: in order to add your own custom methods, you have to subclass this module. that's not optional, bestie, that's the whole point. no subclass = no custom methods = sad.

and get this — the most current version (as of when this module was released, so like, don't @ me) of the client library, plus a demo application, have both been included in this distribution. freebies. we love to see it 🎀

---

✨ INSTALLATION ✨

via Module::Build

perl Build.PL
./Build         # or `perl Build`
./Build test    # or `perl Build test`
./Build install # or `perl Build install`

via ExtUtils::MakeMaker

perl Makefile.PL
make
make test
make install

pick your fighter, both paths get you there 🫶

---

✨ METHODS ✨

💜 new()

creates a new instance of the module. and that's it. no further options are available at this time — literally none, don't go looking, there's nothing else there.

💜 query()

gets / sets the query object. ⚠️ side effect alert: this one extracts the env() data. so it's not just a cute getter/setter, it's doing stuff behind the scenes. periodt.

💜 get_new_query()

this method generates a brand new query object. it's used internally by the query() method, so like, it's usually doing its own thing backstage.

you should only reach for this if you want to supply a query object that isn't the standard CGI.pm object. BUT — huge but — it must be a CGI.pm compatible object. them's the rules. here's an example using CGI::Simple:

sub get_new_query {
    require CGI::Simple;
    my $q = CGI::Simple->new();

    return $q;
}

see? compatible. slay.

💜 env()

gets / sets a hash of information related to the currently query. the resulting structure contains four items:

• method - the method called
• params - an array of parameters for the method
• uid - the unique id for this query
• context - the context id

four lil guys, all important 💖

💜 error_message()

get / sets the error message sent to the client if an error occurred. simple as.

💜 process()

this is the big one. processes the current query and either returns the result from the appropriate method, or an error to the client — and it returns either true or false, respectively, to the caller. so: success = true, error = false. got it? 🧚

an error will occur if the method name is blank, or if the method has not been defined. this function takes an optional CGI.pm compatible object as an input.

your subclass' method will be evaled, and it'll either return an error to the caller if it died, or return a valid result payload on success. no cap, that's the whole flow 🔥

💜 error()

returns a valid error payload to the client and false to the caller. it will automatically call error_message() for you. so convenient. we're obsessed.

💜 result()

returns a valid result payload to the client and true to the caller. the happy path. the good ending 🌈

---

✨ SEE ALSO ✨

• http://www.ashleyit.com/rs

---

✨ AUTHOR ✨

• Brian Cassidy <brian@alternation.net>

---

✨ COPYRIGHT AND LICENSE ✨

Copyright 2005 by Brian Cassidy

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie!! 💅 this was perl v5.32.1, dated 2022-01-10, from the User Contributed Perl Documentation. go forth and subclass responsibly, mwah 😭💖