Search Icon, Magnifying Glass

Graduation Cap Heart Question Mark Magnifying Glass

LectServe: An Online Lectionary

Back in late February of this year the Liturgy and Common Worship Task Force of the Anglican Church in North America (ACNA) released an initial version of a lectionary for the upcoming ACNA Book of Common Prayer (BCP). As an Anglican seminarian, I was, naturally, very intrigued by the new lectionary. Though my parish doesn’t — yet? — use the new lectionary, looking at the PDF document released by the Task Force made me immediately clear that anyone wanting to use the new lectionary would need something more. For the Revised Common Lectionary (RCL) there are several sites online and numerous applications to assist people with finding the readings for a given day. I knew people would want something similar for the ACNA lectionary.

Luckily, the new clearer air I’ve discovered at LifeWay means I don’t come home stressed and finally have bandwidth for personal projects again. In the months since the release of the ACNA lectionary, I’ve dusted off my trusty Perl skills and built some great resources for working with the new lectionary. And, because I’m going to Vanderbilt Divinity School and am a nice guy, I threw in resources for the RCL, too.

Today, nine months of work has come to a culmination, I released my tools to the Church and the world as LectServe!

LectServe is a collection of Perl modules, an API, and a website. Let me dig in deeper.

Date::Lectionary and Friends

Date::Lectionary is a public module released to CPAN that allows anyone to programmatically interact with the Western Christian liturgical calendar documented in the RCL and the ACNA lectionaries. Though this might seem like a simple problem to solve, let me assure you it is not. First you have to realize that the days of the Christian liturgical calendar are all relative, more or less, to two major days: the First Sunday of Advent and Easter.

The first day of the liturgical calendar is Advent I, so I naturally decided to start my journey there. To get the start of Advent you find Christmas — always December 25th, praise the Lord! — and count back four Sundays. So, I needed a way to move forward and backward in time relative to Sundays, hence Date::Lectionary::Time. With that little problem solved, figuring out the Sundays of Advent was easy and Date::Advent was quickly developed and released to CPAN. Easter was the next hurdle, but luckily a kind and much smarter soul than I — the Perl community rocks! — had already done the work for me and released Date::Easter to CPAN. I stood on the shoulders of giants and moved on.

With my anchor points in place, I was able to start work on Date::Lectionary proper. Finding my way in liturgical time was fairly straight forward once I got started. Moveable and fixed feasts gave me a bit of a problem for a while, but I was able to resolve that after a few tries. — Moveable feasts move to a Monday when they occur on a Sunday, fixed feasts override the normally assigned readings when they occur on a Sunday. — Once I had my days all sorted out, I hit my next obstacle, sometimes days have alternate names and the names used by the ACNA don’t always match those used by the RCL! I almost just forced everything into the ACNA naming scheme, but — again — I’m a nice guy, so I went back to the drawing board.

Date::Lectionary::Day solves the naming problem with a series of XML files. Basically, I have a master XML database that maps my internal “common” names for a day — pretty much a 1:1 mapping to the ACNA names — to the specific name used by the ACNA or the RCL. I also keep track of alternate names there. If you give Date::Lectionary::Day a Sunday, it’ll figure out where that day sits in the liturgical calendar and give you that day back how ever you need it called. It’s built so I can even add other lectionary naming schemes — hello Rome! — if I get the motivation/request.

With the day problems solved, grabbing the list of assigned readings was the next task. First, Western lectionaries follow the three year cycle established by the Roman Church. I built Date::Lectionary::Year to solve that problem. Give it a date and it’ll let you know which cycle year the date sits in. With the cycle year and the lectionary-relative name all figured out, all that need to happen next was to look-up the readings. A simple tasks if lectionaries were distributed in any sort of standardized format. Unfortunately, all I had was PDF and Word documents to work with. I spent untold hours manually copying the RCL and ACNA lectionaries into my own XML format. — Both lectionaries are available on GitHub as XML, should you need them for another project. [ACNA] [RCL] — Once the XML was populated, Date::Lectionary was ready to roll. I ran it through its paces, fixed some edge cases, and released it so CPAN as soon as I felt comfortable.

LectServe αlpha

Sadly, after nine full months of work, no one except a few Perl developers would ever be able to see, much less use, the fruits of my labor. Date::Lectionary and all of her friends were Perl modules trapped on CPAN. I needed to bring the ACNA lectionary to the Internet and, because I’m a grumpy old man, I needed to so with without any of that new-fangled HTML5 and Javascript.

Enter the excellent Perl community and the many amazing frameworks available there. I’ll share the details in an upcoming technical post, but in just a few hours I had a service and website leveraging Date::Lectionary up and running using the Dancer2 framework and Starman web server; LectServe was born. After a few more days of work, I had LectServe running inside a Docker container and deployed to an EC2 server on Amazon’s cloud infrastructure.

LectServe is still very αlpha. I’m certain my copy and past job means there are issues in the lectionary texts. The UX is horrible and lifted from this — rather plain — website. I don’t yet have an interface to look-up specific dates or easily access the RCL. I’m uncertain what kind of load my little Amazon server can take. I don’t really know if I setup caching in Starman correctly. But, even given all of this, LectServe is out in the world ready to serve anyone who’s looking to use the ACNA lectionary.

LectServe is my first public project and I’m really proud of it. It’s going to change and improve over the coming months and years and it’s going to do it out in the open. Please, take some time to play around with LectServe. If you see an issue, let me know. I look forward to serving the Church and our Common Lord with my mad Perl skills!