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

Both sides previous revisionPrevious revision
Next revision		Previous revision
newdevs:perl [2023/02/15 09:00] – [The Perl Logic Layer] smorrisonnewdevs:perl [2024/01/18 10:11] (current) – fix headings, add a link sandbergja
Line 2: Line 2:
 ====== 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.
  
-==== Evergreen Conference Sessions ====+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]]   * [[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.1676469631.txt.gz · Last modified: 2023/02/15 09:00 by smorrison
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.