Evergreen DokuWiki

User Tools

Site Tools

You are here: start » newdevs » perl
newdevs:perl

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
newdevs:perl [2023/01/18 16:45] – created tmccannanewdevs:perl [2024/01/18 10:11] (current) – fix headings, add a link sandbergja
Line 1: Line 1:
 **New Developers Working Group** **New Developers Working Group**
 ====== The Perl Logic Layer ====== ====== The Perl Logic Layer ======
 +
 +===== Structure =====
 +
 +
 +Most of Evergreen's business logic can be found in perl modules.  In the git repository, these can be found at Open-ILS/src/perlmods/lib.  Perl modules typically have the .pm file extension.
 +
 +Evergreen's business logic is tested by the tests in Open-ILS/src/perlmods/t (which do not require the concerto data set to be running in the database) and Open-ILS/src/perlmods/live_t (which do).  Perl tests have the .t file extension.  The perl code is also exercised indirectly by the end-to-end tests for the Angular staff client.
 +
 +There are many Perl scripts throughout the project.  Perl scripts generally have the .pl file extension.
 +
 +===== Dependencies =====
 +
 +Evergreen's Perl code relies on many packages from CPAN.  They are installed by your operating system's package manager and cpan itself when you run the Open-ILS/src/extras/Makefile.install Makefile.  When you need to add or remove a dependency, do so for all of the operating systems listed in the Open-ILS/src/extras/install directory.
 +
 +===== Checking your work =====
 +
 +Here are some things you can do to check your work while working with Evergreen's perl code:
 +
 +  * If it is in an OpenSRF method: Build it, install it, and restart your services.  Then call the method (through the UI, or directly using the srfsh).  Confirm that the behavior is what you expected.
 +     * To build and install the perl code, you can run ''make'' as opensrf then ''make install'' as root.  Alternatively, you can build and install the perl code in a single step with ''cd Open-ILS/src/perlmods && ./Build install'' as root.
 +  * Write some tests to confirm that your code is working as intended, without any unintended side effects.
 +  * Run ''perl -cw [name of file]'' to check your syntax and check for warnings.
 +  * Run perlcritic on your code to check for common gotchas and readability.  You can paste your code directly into [[http://perlcritic.com/|the online PerlCritic checker]] or install the command line tool from CPAN.  This is not a requirement (most perl code in Evergreen violates these rules), but it can be very instructive.
 +  * Temporarily adding print or logging statements to your work.  If you'd like to print an array or hash, try using Data::Dumper.
 +
 +===== Using Cstore to interact with the database =====
 +
 +A lot of the Perl code uses a Cstore editor to create, retrieve, update, delete, and search records in the database.  The following examples are loosely based on the Carousel Perl module:
 +
 +  use strict;
 +  use warnings;
 +  use OpenILS::Utils::CStoreEditor qw/:funcs/;
 +  use OpenILS::Utils::Fieldmapper;
 +  
 +  #########
 +  # Setup #
 +  #########
 +  
 +  # Create a new Cstore editor
 +  my $e = new_editor(authtoken => $auth);
 +  
 +  # Check that the auth token is valid
 +  return $e->event unless $e->checkauth;
 +  
 +  # Check that the user has the ADMIN_CAROUSEL permission.
 +  # CStore doesn't perform any permission checks by itself,
 +  # so your Perl code needs to explicity do these checks.
 +  return $e->event unless $e->allowed('ADMIN_CAROUSEL');
 +  
 +  #########################
 +  # Create a new carousel #
 +  #########################
 +  
 +  # Assemble a new fieldmapper object in memory
 +  my $carousel = Fieldmapper::container::carousel->new;
 +  $carousel->name('My carousel');
 +  $carousel->type(1);
 +  $carousel->owner($e->requestor->ws_ou);
 +  $carousel->creator($e->requestor->id);
 +  $carousel->editor($e->requestor->id);
 +  $carousel->max_items(12);
 +  $carousel->bucket(30);
 +  
 +  # Then, start a transaction in the database.  This is
 +  # required any time you are changing data in the database
 +  $e->xact_begin;
 +  
 +  # Persist the carousel to the database
 +  $e->create_container_carousel($carousel) or return $e->event;
 +  
 +  # Commit the transaction.  It's a best practice to not leave
 +  # transactions open for a long time.
 +  $e->xact_commit or return $e->event;
 +  
 +  #############################
 +  # Retrieve a carousel by ID #
 +  #############################
 +  
 +  my $other_carousel = $e->retrieve_container_carousel(3); # Retrieve by id: 3
 +  print "The other carousel name is $other_carousel->name";
 +  
 +  #####################
 +  # Update a carousel #
 +  #####################
 +  
 +  # Again, make our changes in memory
 +  $carousel->bucket(40);
 +  
 +  # Open a transaction, persist our change to the database, and commit the transaction
 +  $e->xact_begin;
 +  $e->update_container_carousel($carousel) or return $e->event;
 +  $e->xact_commit or return $e->event;
 +  
 +  
 +  #####################
 +  # Delete a carousel #
 +  #####################
 +  
 +  # Similarly, open a transaction, call the delete method, and commit the transaction.
 +  # Note that the delete_container_carousel method accepts a Fieldmapper object, rather
 +  # than just an ID.  So, if you only have an ID, you'll need to retrieve the object
 +  # from the database before you can delete it.
 +  $e->xact_begin;
 +  $e->delete_container_carousel($carousel) or return $e->event;
 +  $e->xact_commit or return $e->event;
 +  
 +  ####################################
 +  # Search carousels by field values #
 +  ####################################
 +  
 +  # No transaction needed, since we aren't making changes
 +  my $carousels_with_bucket_forty = $e->search_container_carousel( { bucket => 30 });
 +  
 +  # The search_* methods return a reference.  To access our actual data, we'll need to dereference by
 +  # putting the array sigil (@) in front of our variable name.
 +  for my $found_carousel (@$carousels_with_bucket_forty) {
 +    print $found_carousel->name;
 +  }
 +  
 +  # We can turn it back into a scalar to find the number of matching rows.
 +  my $matching_rows = scalar @$carousels_with_bucket_forty;
 +  
 +  # Perl critic recommends putting curly braces around the reference for clarity
 +  $matching_rows = scalar @{ $carousels_with_bucket_forty };
 +  
 +  # You can also use the arrow operator and square brackets to get data directly from the array reference.
 +  print 'The name of the first carousel is: ' . $carousels_with_bucket_forty->[0]->name;
 +  
 +  1;
 +
 +===== Evergreen Conference Sessions =====
 +  * [[https://www.youtube.com/watch?v=fXrhpJUpFWE&ab_channel=EvergreenLibrarySystem|Making Perl Work for You in Evergreen, by Galen Charlton & Mike Rylander]]
 +
 +===== Further Reading =====
 +
 +  * [[http://www.perlmeme.org/howtos/using_perl/dereferencing.html|Dereferencing in Perl]] from perlmeme.org
newdevs/perl.1674078315.txt.gz · Last modified: 2023/01/18 16:45 by tmccanna
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.