Part 1 – The Elven Journals

Prologue

A Christmas ditty sung to the tune of Santa Claus is Coming to Town:

    He's making a list,









    He's checking it closely,









    He's gonna find out who's Rakuing mostly,









    Santa Claus is Rakuing along.

Santa Claus Operations Update 2021

Santa’s operations were much improved year-over-year since his IT crew adopted Raku as their go-to programming language (see the articles from Raku Advent 2020). In addition, he and his non-techy elves found the language so easy for beginners to use, he decided to see if he could use it for managing the many task reports and other documents needed by individuals as well as managers.

Note that one of the improvements he had instituted was issuing mobile tablets to all Elves. The tablets are provisioned with Raku apps that provide a Raku REPL (Read Eval Print Loop) for easy code snippet use as well as a browser to access websites where more code can be run. As well, the tablets are equipped with a Terminal app that enables remote logins to the powerful servers in the IT Department.

He also insituted a new policy on record-keeping that requires Elves to keep a digital journal and make at least two entries per work shift. They should log in to their own account on the server via a terminal app [‘termius’ is this author’s choice] in order to make an entry or check it. When something is to be noted use vi to open their text journal (file ‘$HOME/journal’, kept safe under central version control with git) and make an entry. The first format attempted was this:

    =Time 2021/4/22 1340



















    =Entry Designed a new toy I'll call 'Herby' the harp seal, a









    stuffed animal with a waterproof covering suitable









    for a bath toy for toddlers.

Note the entry is in a simple format (using pod abbreviated blocks, see https://docs.rakulang.site/language/pod#Abbreviated_blocks) to allow line parsing and further manipulation. One or more blank lines separate the new entry from any previous entry. Open the new entry with the year, month, and day number separated by slashes, one or more spaces, then the hour and minute in local time expressed in twenty-four hour format, followed by one or more blank lines. Then come the journal notes with paragraphs separated by one or more blank lines. (Of course since Raku will be processing the journals Unicode characters above the ASCII range are perfectly acceptable.)

Elves are expected to make a journal entry at the start and end of their work shift. (There is also a trial ongoing to use a voice-to-text system to ease the journaling effort, but its reliability is not very good at the moment. Also, the verbosity and silliness of the Elven people’s language makes filtering the sound quite a challenge for the IT system.)

Periodically all the journals are read and and converted to a format which makes it easier to find specific entries by date, time, and Elf. The process also creates reports detailing task progress and Elf efficiency. (Details will be in Part 2 of this article.)

The initial processing of all the Elven journals looked something like this:

    use SantaClaus::Utils;









    my %j; # or %journal









    for each elf









        %j<e> = [];









        read journal file









            for each line









                if empty









                    end current object









                elsif a datetime entry









                    create a DateTime object









            ...

That was not going to work–too much room for erroneous parsing and cowboy coding!

The second approach was to tightly control the Pod components allowed, extract the Pod programmatically with Raku, and fail early on problems with helpful comments. But one of Santa’s concerns was the strange nature of Pod blocks. Most have as a base class Pod::Block so those all have the following common attributes:

    my class Pod::Block {









        has %.config;









        has @.contents;









    }

Due to the @.contents array, Pod blocks can be nested infinitely deep, so handling unknown Pod can be tedious and error-prone. In addition, extracting Pod from another document requires more than a beginner’s knowledge of Raku. Thus it was decided to create a Raku journal management program which uses the Raku module Pod::Load to extract the Pod. Additionally, the current policy for journal entries precisely describes the journal entry format which can easily be extracted by Raku while reading the journal, so a helper program was added to initiate a a journal entry with a templated Pod chunk with embedded instructions to ease the Elve’s input.

Here is an example of that template block newly created at the end of the current journal file for an Elf computer user name of ‘jerzi’ and default task ID of ‘build-toy’:

    Z<Edit the following Entry as necessary. Add or delete Z comments as desired.>









    =begin Entry :time<2021-11-30T07:12>









      Z<Enter one of ':start' or ':end' in the following config line if applicable.>









      =begin Task :id<build-toy> :employee<jerzi> :status









        Z<Enter notes and comments here; use blank lines to separate paragraphs>









      =end Task



















      Z<Add another Task if applicable; ensure the ':id' is correct before doing so.>









    =end Entry

The user merely adds the appropriate data and (optionally) removes the Z<> Pod comments which are ignored by Santa’s journal reader (although they leave blank spaces after Pod::Load parsing, all text paragraphs are then normalized by the reader and blank paragraphs will disappear).

Let’s see what happens when the Elf starts a brand new journal which will look like the above and then edits it to look like this:

    =begin Entry :time<2021-11-30T07:12>









      =begin Task :id<build-toy> :employee<jerzi> :status



















      =end Task



















    =end Entry

Now run the check:

    $ check-journal









    ERROR: Task id<build-toy> has a ':status' config key but no explanation

Journal entries require an explanation when it is a ‘:status’ entry without a ‘:start’ or ‘:end’ config key.

The typical Elf’s work shift now looks something like this:

• Check messages for any special instructions
• Login to the system and make a journal entry

  
  
  
  
  
  
  
  
      $ add-event
  
  
  
  
  
  
  
  
  
      See new Entry appended to file: journal
  
  
  
  
  
  
  
  
  
      $ vi journal
  
  
  
  
  
  
  
  
  
      ...
  
  
  
  
  
  
  
  
  
      :wq
  
  
  
  
  
  
  
  
  
      $ check-journal
  
  
  
  
  
  
  
  
  
      # make necessary edits until the journal
  
  
  
  
  
  
  
  
  
      # checks okay
  
  
  
  
  
  

• Work the task(s)
• Login and update the journal as necessary
• Login and make the end-of-shift journal entry

Summary

The new system now creates a complete record of an Elf’s work and serves as an electronic time clock to replace the old punch cards and electro-mechanical clocks.

In addition, the individual journals provide the data for detailed operational and managerial reports for all supervisory levels.

Part 2 of this article will discuss those aspects of the new system and how Raku makes them easier to program for less experienced programmers.

Note: See all code used in this article in the repo at https://github.com/tbrowder/SantaClaus-Utils.

Santa’s Epilogue

Don’t forget the “reason for the season:” ✝

As I always end these jottings, in the words of Charles Dickens’ Tiny Tim, “may God bless Us , Every one!” [1]

Footnotes

1. A Christmas Carol, a short story by Charles Dickens (1812-1870), a well-known and popular Victorian author whose many works include The Pickwick Papers, Oliver Twist, David Copperfield, Bleak House, Great Expectations, and A Tale of Two Cities.