Differences

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

--- newdevs:perl [2024/01/17 16:40] – [Evergreen Conference Sessions] sandbergja
+++ newdevs:perl [2024/01/18 10:11] (current) – fix headings, add a link sandbergja
@@ Line 2: / Line 2: @@
 ====== The Perl Logic Layer ======
+===== Structure =====
-==== 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.
@@ Line 14: / Line 11: @@
 There are many Perl scripts throughout the project.  Perl scripts generally have the .pl file extension.
-==== Dependencies ====
+===== 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 ====
+===== 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 ''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]].  This is not a requirement (most perl code in Evergreen violates these rules), but it can be very instructive.
+  * 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 ====
+===== Using Cstore to interact with the database =====
-==== Evergreen Conference Sessions ====
+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;
+;
+===== 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