Ponomar: an Application Programming Interface for Liturgical
Total Page:16
File Type:pdf, Size:1020Kb
PONOMAR An Application Programming Interface for Liturgical Computations in the Perl Language Created By Aleksandr Andreev Yuri Shardt Slavonic Computing Initiative St. Petersburg 2018 © 2012–2018 Aleksandr Andreev and Yuri Shardt This document is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit the CreativeCom- mons website. The software is provided “as is”, without warranty of any kind, express orim- plied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copy- right holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. 1 Contents 1 Introduction to the Ponomar API 3 2 The Ponomar Class 5 3 Ponomar::Bible 8 4 Ponomar::Cu 9 5 Ponomar::I18n 10 6 Ponomar::JDate 11 7 Ponomar::Reading 17 8 Ponomar::Saint 19 9 Ponomar::Service 21 10 Ponomar::Sunrise 23 11 Ponomar::Util 25 2 1 Introduction to the Ponomar API Ponomar is an Object Oriented API; the set of Ponomar classes is designed to eliminate the need for low-level interaction with XML (or YAML) data and CMDs (liturgical CoMmanDs). Basic implementations of calendar software can be writ- ten using this API with about 5 lines of code. More complex implementations will require array-based manipulation of Ponomar objects (as in, lots of grep, map and foreach); but it beats working with the XML directly. Note that the API is designed to be format independent. That is, data outputed by the API is strictly Unicode text; it lacks formatting or markup. (THIS IS NOT ACTUALLY TRUE: certain XML files in Ponomar contain markup, e.g., <SUP> tags. This is problematic and should be considered a defect of theAPI). Note that Ponomar works with Julian Dates (actually, Julian days). Unless a method specifically contains the words ‘Gregorian’ or ‘Milankovich’, all calcu- lations and dates are according to the Julian Calendar. The non-OOO Ponomar::Util class provides handy functions for generating common dates including Today and any year’s Pascha without having to deal with the Ponomar::JDate object. See the documentation for Ponomar::Util for details. SYNOPSIS use Ponomar; use Ponomar::JDate; $ponomar = new Ponomar(new Ponomar::JDate(1, 1, 2001), ’en’); print join(’; ’, map { $_->getKey(’Name’)->{Nominative} } $ponomar->getSaints(’menaion’)); Workflow Upon initialization, Ponomar immediately loads the Ponomar::I18n helper class, which handles all Internationalization (I18n) support for Ponomar. The load() method of Ponomar::I18n loads into memory Ponomar locale data. Locale data is stored in YAML (YAML A’int a Markup Language) format in the file locales.yml. The user begins by creating a Ponomar object. The Ponomar object takes two initial parameters, the $date and the $locale. The $locale is an ISO 639- 2 language code (string). The $date is an instance of the Ponomar::JDate class (see documentation for Ponomar::JDate), which is in essence a glorified Integer (Julian Day object). 3 The constructor of Ponomar calls the init() method, which loads XML data for the given day and locale. The reading of XML DATA proceeds in the following FIFO (First In First Out) order: Step 1. The relevant top-level saint files are read for Pentecostarion / Trio- dion. This creates a set of Ponomar::Saint objects with two properties: a. The CId (Commemoration Id) b. The associated JDate object c. The locale Important: Ponomar Saints are not date-independent entities: saint data may contain CMDs which are date dependent. b. and c., above, are inher- ited from the underlying Ponomar object. Step 2. At this stage, the Tone is set. Step 3. Loading of Saint data for Pentecostarion / Triodion Immediately upon construction, the Ponomar::Saint object loads all top- down XML files associated with CId. This will load the NAMEs of theSaint as well as the LIFEs and the SERVICEs. Step 4. Loading of service data for Pentecostarion / Triodion Presently, SERVICE tags are more or less wrappers. The only useful infor- mation obtained from the SERVICE tag is the Type (more properly, “rank”) of the service. This is used to set the Type property of the Saint object. SERVICE objects also handle Commands (see the documentation of Pono- mar::Service for details). Upon encountering individual services (VESPERS, MATINS, LITURGY, etc), Ponomar::Saint creates a new instance of Ponomar::Service. The Ser- vice object contains only two properties, the Type (which is type of ser- vice, more properly, the type of “office”, e.g., ‘vespers’, ‘matins’, ‘liturgy’, etc) and the dRank of the service (which is the rank and is inheretied from the Type property of the Ponomar::Saint parent). Note that dRank is not the same as the day’s dRank, computed below. The confusion in terminology is unfortunate. BUG NOTICE: As presently written, the API accepts only one SERVICE per Saint. That is, only one type of service may be read in, e.g., readinga 4 second VESPERS service into a Saint will create two Service objects that are completely indistinguishable. This means that subsequent Scripture readings, if any, will be assigned to both Service objects. This will have unforseen consequences, especially for the sorting algorithm of Scriptures. This is a bug. Step 5. Loading of Menaion data Steps 1, 3 and 4 are repeated for the Menaion-based data. Step 6. The dRank (rank of the day) is set. Presently, dRank is the max of all ranks available for a given day. As cur- rently written, the API does not allow the user to select between service or commemoration alternatives. Step 7. The day’s fasting information is computed. Initialization stops at this point and your Ponomar object is ready to work. NOTE: The initial initialization does not handle suppression or transfer of readings. This is handled by calling the executeCommands method of relevant Service objects. See the documentation for Ponomar::Service for details. 2 The Ponomar Class METHODS new($date, $language, [$GS] ) Creates a new Ponomar object for Julian date $date and language $language, using Gospel Selection algorithm $GS. Runs the initial initialization pro- cess, reading XML for this $date. Returns a reference to the new object. E.g.: $ponomar = new Ponomar(Ponomar::Util::getToday(), ’en’) The deprecated paramater $GS determines if the Lucan Jump is used in the selection of scriptures. As of August 2018, non-Lucan Jump implementa- tions are no longer supported ($GS is always treated as 1 regardless of user input). 5 getSaints( [$src] ) Returns the Array of Saint objects associated with the Ponomar object Op- tional parameter $src can take on one of two values: ’pentecostarion’ or ’menaion’ and conditions the returned array on the Source of the com- memoration. Note that for the purposes of Source, Triodion-based commemorations are called ’pentecostarion’, i.e., ’pentecostarion’ refers to everything based off the Paschal cycle. E.g.: $ponomar->getSaints( ’pentecostarion’ ); Returns those saints who came from the pentecostarion. getTone() Returns the Tone of the day as a String, based on the locale of the object. E.g.: In en locale, returns ’Tone VIII’ getFastingInstructions() Returns the Fasting instructions of the day as a String, basd on the locale of the object. E.g. In en locale, returns ’Xerophagy’ getFastingCode() Returns the raw code of the fasting instruction, e.g., 000001. E.g., the following test if meat is allowed on a given day: split(//, $ponomar->getFastingCode())[0] == 1 getReadings( [$type, $Src] ) Returns an array with references to all Readings objects associated with the date Optional parameters $type and $Src $Src limits returned array to source of commemoration (e.g., pentecostar- ion, menaion); $type limits returned array to type of service (e.g., vespers, liturgy) loadBible([$version]) 6 Loads the Bible in this language. Optional parameter $version specifies which version of the Bible to load if multiple versions are available in a language. If $version is not specified, the default version is used. You can get a list of available versions by calling getBibleVersions(). Returns a reference to a new Ponomar::Bible object. Constant: NO_LUCAN_JUMP Deprecated. Constant: LUCAN_JUMP Deprecated. setLectionaryStyle ( $style ) Deprecated. getLectionaryStyle() Deprecated. 7 3 Ponomar::Bible Ponomar::Bible - a Bible object for the Ponomar API METHODS new( Lang => $language ) Creates a new instance of the Bible. Parameter Lang specifies the language. Reads the appropriate bible.xml file and loads the Bible information for that language into memory. getBookNameShort( $book ) Returns the short form of the name of the book $book in the current Bible getBookName ( $book ) Returns the full form of the name of the book $book in the current Bible exists ( $book ) Returns true if the book $book exists in the current Bible getPassage ($reading) Returns a set of verse objects with the text of the Bible passage given by the Reading object $reading 8 4 Ponomar::Cu Ponomar::Cu -- Church Slavonic support in the Ponomar API DESCRIPTION This is not an Object Oriented class, but rather a set of utility functions forwork- ing with Church Slavonic texts. This code is DEPRECATED and will be deleted. Use Lingua::CU class instead. TODO: The Ponomar API needs to be rewritten so that everything uses Lingua::CU. METHODS hip2unicode ( $string ) Takes $string, a string in HIP (Hyperinvariant Presentation), and converts it to Unicode ucs2unicode ( $string ) Takes $string, a string in UCS (Universal Church Slavonic), and converts it to Unicode resolveTitli ( $string ) Takes $string, a string of Church Slavonic text in Unicode, and resolves any Titli present, including numerals. cu2arabic ( $string ) Takes $string, a numeral in Church Slavonic, and converts it to a numeral in Arabic numerals.