Catman...::Pure(3pm)

💅 Catmandu::Importer::Pure — the manual page, bestie edition ✨

okay so you found the docs for Catmandu::Importer::Pure, a Catmandu package that imports Pure data, and honestly? iconic of you. this is the 3pm page, living in the User Contributed Perl Documentation section. let's get into it 🫶

---

🌸 NAME 🌸

Catmandu::Importer::Pure — the package that imports Pure data. that's it, that's the name, slay.

---

✨ SYNOPSIS ✨

so first things first, you can run this from the command line like the main character you are:

# From the command line
$ catmandu convert Pure \
      --base https://host/ws/api/... \
      --endpoint research-outputs \
      --apiKey "..."

or if you're feeling very Perl-pilled today, do it in code:

# In Perl
use Catmandu;

my %attrs = (
  base     => 'https://host/path',
  endpoint => 'research-outputs',
  apiKey   => '...',
  options  => { 'fields' => 'title,type,authors.*' }
);

my $importer = Catmandu->importer('Pure', %attrs);

my $n = $importer->each(sub {
  my $hashref = $_[0];
  # ...
});

and here's the little glow-up moment where you grab the number of validated and approved publications, because we love a count:

# get number of validated and approved publications
my $count = Catmandu->importer(
  'Pure',
  base         => 'https://host/path',
  endpoint     => 'research-outputs',
  apiKey       => '...',
  fullResponse => 1,
  post_xml => '<?xml version="1.0" encoding="utf-8"?>'
    . '<researchOutputsQuery>'
    . '<size>0</size>'
    . '<workflowSteps>'
    . '  <workflowStep>approved</workflowStep>'
    . '  <workflowStep>validated</workflowStep>'
    . '</workflowSteps>'
    . '</researchOutputsQuery>'
)->first->{count};

---

💖 DESCRIPTION 💖

so Catmandu::Importer::Pure is a Catmandu package that seamlessly imports data from Elsevier's Pure system using its REST service. no cap.

but bestie, plot twist: to use the Pure Web Service you need an API key 🔑. the full list of all available endpoints plus further documentation can currently be found under /ws on a webserver that is running Pure. go look, it's giving documentation energy.

⚠️ heads up: this version of the importer is tested with Pure API version 5.18 and might not work with later versions. she's a little vintage, okay? we respect her era.

---

🎀 CONFIGURATION 🎀

here's every knob and dial, and yes we're going through all of them:

• base — the base URL for the REST service. required, no skips. example: 'http://purehost.com/ws/api/518'
• endpoint — a valid endpoint is required, like 'research-outputs'. you gotta tell her where to look 💅
• apiKey — a valid API key is required for access. no key, no data, periodt.
• path — the path after the endpoint. a lil extra something.
• user — user name, but only if basic authentication is used.
• password — password, also only if basic authentication is used. 🤫
• options — options passed as parameters to the REST service. for example:

{ 'size' => 20,
  'fields' => 'title,type,authors.*'  }

• post_xml — xml containing a query that will be submitted with a POST request. so it's not a vibe, it's a query ✨
• fullResponse — optional flag. if true, it delivers the complete results as a single item (record), corresponding to the XML response received. only one request to the REST service is made in this case. default is false.

if the flag is false, then the items are set to child elements of the element 'result' — or, in case the 'result' element does not exist, they're set to child elements of the root element, for each response. okurrr.

• handler( sub {} | $object | 'NAME' | '+NAME' ) — the handler that transforms each record from XML DOM (XML::LibXML::Element) into a Perl hash.

handlers can be provided as a function reference, an instance of a Perl package that implements 'parse', or by a package NAME. package names should be prepended by "+" or prefixed with "Catmandu::Importer::Pure::Parser". e.g "foobar" will create a "Catmandu::Importer::Pure::Parser::foobar" instance. the naming convention ate, honestly.

by default the handler Catmandu::Importer::Pure::Parser::simple is used. it provides a simple XML parsing, using XML::LibXML::Simple.

other possible values are Catmandu::Importer::Pure::Parser::struct for XML::Struct based structure that preserves order, and Catmandu::Importer::Pure::Parser::raw that returns the XML as it is. pick your fighter 🦋

• userAgent — HTTP user agent string, set to "Mozilla/5.0" by default. she's disguising herself, we love a stealth queen.
• furl — instance of Furl or compatible class to fetch URLs with.
• timeout — timeout for HTTP requests in seonds. defaults to 50. (yes, the typo is in the original, i'm keeping it, i'm loyal 💜)
• trim_text — optional flag. if true, then all text nodes in the REST response are trimmed so that any leading and trailing whitespace is removed before parsing. this is useful if you don't want to risk getting leading and trailing whitespace in your data, since Pure doesn't currently clean leading/trailing white space from user input. note that there is a small performance penalty when using this option. default is false.
• filter( sub {} ) — optional reference to a function that processes the XML response before it is parsed. the argument to the function is a reference to the XML text, which is then used to modify it. this option is normally not needed, but can be helpful if there's a problem parsing the response due to a bug in the REST service. 🐛

---

👑 METHODS 👑

in addition to methods inherited from Catmandu::Iterable, this module provides the following public methods:

• url — return the current Pure REST request URL. useful for debugging 🕵️‍♀️

---

🌈 SEE ALSO 🌈

go read these too, bestie, they're the friend group:

• Catmandu
• Catmandu::Importer
• Catmandu::Iterable
• Furl

---

🌸 AUTHOR 🌸

Snorri Briem <briem@cpan.org> — we stan 💖

---

🎀 COPYRIGHT 🎀

Copyright 2017- Lund University Library

---

💜 LICENSE 💜

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. so like, go off, just keep the same terms, ok? 💅

---

and that's the whole page, bestie 🫶 this was Catmandu::Importer::Pure, 3pm, from perl v5.36.0, dated 2023-02-04 — mwah, iconic, no notes ✨🦋🌸