SRU(3pm)

✨ SRU — Search and Retrieval by URL ✨

okay bestie, welcome to SRU(3pm), a User Contributed Perl Documentation page, and honestly? it's giving library-science-girlboss. let's get into it 💖

---

🌸 NAME 🌸

SRU — Search and Retrieval by URL. that's it, that's the name, she's simple and she knows it 💅

---

🦋 SYNOPSIS 🦋

## a simple CGI example

use SRU::Request;
use SRU::Response;

## create CGI object
my $cgi = CGI->new();

## create a SRU request object from the CGI object
my $request = SRU::Request->newFromCGI( $cgi );

## create a SRU response based from the request
my $response = SRU::Response->newFromRequest( $request );

if ( $response->type() eq 'explain' ) {
    ...
} elsif ( $response->type() eq 'scan' ) {
    ...
} elsif ( $response->type() eq 'searchRetrieve' ) {
    ...
}

## print out the response
print $cgi->header( -type => 'text/xml' );
print $response->asXML();

like, that's the whole vibe right there. make a request, make a response, check the type, print the XML. no cap. 🔥

---

💜 DESCRIPTION 💜

so the SRU package is a whole framework for working with the Search and Retrieval by URL (SRU) protocol, which was developed by the Library of Congress. SRU defines a web service for searching databases that contain metadata and objects. and here's the tea: SRU often goes under the name SRW, which is a SOAP version of the protocol. so you can think of SRU as a RESTful version of SRW, because all the requests are simple URLs instead of XML documents being sent via some sort of transport layer. iconic behaviour honestly. 🌈

you might be interested in SRU if you wanna provide a generic API for searching a data repository, plus a mechanism for returning metadata records. SRU defines three verbs: explain, scan and searchRetrieve, and those define the requests and responses in a SRU interaction. three verbs, three moods, one protocol. periodt. 👑

this set of modules is trying to provide a framework for building an SRU service. the distribution is made up of two sets of Perl modules:

• modules in the SRU::Request::* namespace, which represent the three types of requests
• modules in the SRU::Response::* namespace, which represent the various responses

typical usage is that a request object gets created using a factory method in the SRU::Request module. the factory is given either a URI or a CGI object for the HTTP request, and SRU::Request will look at the URI and build the appropriate request object: SRU::Request::Explain, SRU::Request::Scan or SRU::Request::SearchRetrieve. it just knows. main character energy fr fr. ✨

once you've got a request object, you can build a response object by using the factory method newFromRequest() in SRU::Request. this method will examine the request and build the corresponding result object, which you can then populate with result data appropriately. and when you're done populating the response object with results, you can call asXML() on it to get the full XML for your response. slay. 🎀

to understand the meaning of the various requests and their responses, you'll wanna read the docs at the Library of Congress. a good place to start is this simple introductory page: http://www.loc.gov/standards/sru/simple.html

for more info about working with the various request and response objects in this distribution, see the POD in the individual packages:

• SRU::Request
• SRU::Request::Explain
• SRU::Request::Scan
• SRU::Request::SearchRetrieve
• SRU::Response
• SRU::Response::Explain
• SRU::Response::Scan
• SRU::Response::SearchRetrieve
• SRU::Server

questions and comments are more than welcome 🫶 this software was developed as part of a National Science Foundation grant for building distributed library systems in the Ockham Project. more about Ockham can be found at http://www.ockham.org.

---

🍓 DEPENDENCIES 🍓

to use SRU::Server and Catalyst::Controller::SRU, one must install CGI::Application and Catalyst, respectively. (respectively!! matching them up correctly, we love to see it 💅)

heads up bestie: in a future release Catalyst::Controller::SRU might be moved to an independent module. so like, don't get too attached to where it lives rn. 💀

---

🧚 TODO 🧚

the wishlist, the vision board, the little dreams:

• create a client (SRU::Client)
• allow searchRetrieve responses to be retrieved as RSS
• make sure SRU::Server can function like real-world SRU interfaces
• handle CQL parsing errors
• better argument checking in response constructors

it's giving "we'll get to it" and honestly, same. 🙈

---

👑 AUTHORS 👑

Ed Summers <ehs@pobox.com>

---

💖 COPYRIGHT AND LICENSE 💖

this software is copyright (c) 2013 by Ed Summers.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay that's the whole page bestie, you're officially SRU-pilled 🌸 and one last thing before you go — this was brought to you by perl v5.34.0, dated 2022-06-17, filing under SRU(3pm). mwah, go build a web service 💅✨🦋