PONOMAR

An Application Programming Interfacefor Liturgical Computations

in the Perl Language

Created By

Aleksandr AndreevYuri Shardt

Slavonic Computing Initiative

St. Petersburg2018

© 2012–2018 Aleksandr Andreev and Yuri Shardt

This document is licensed under the Creative Commons Attribution-ShareAlike4.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 or im-plied, including but not limited to the warranties of merchantability, fitness for aparticular purpose and noninfringement. In no event shall the authors or copy-right holders be liable for any claim, damages or other liability, whether in anaction of contract, tort or otherwise, arising from, out of or in connection withthe 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 toeliminate 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 willrequire array-basedmanipulation of Ponomar objects (as in, lots of grep, map andforeach); but it beats working with the XML directly.

Note that theAPI is designed to be format independent.That is, data outputedby the API is strictly Unicode text; it lacks formatting or markup. (THIS IS NOTACTUALLY TRUE: certain XML files in Ponomar contain markup, e.g., <SUP>tags. This is problematic and should be considered a defect of the API).

Note that Ponomar works with Julian Dates (actually, Julian days). Unless amethod 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 generatingcommon dates including Today and any year’s Pascha without having to dealwith the Ponomar::JDate object. See the documentation for Ponomar::Util fordetails.

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 isstored in YAML (YAMLA’int aMarkup Language) format in the file locales.yml.

The user begins by creating a Ponomar object. The Ponomar object takestwo 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 datafor the given day and locale.The reading of XMLDATA proceeds in the followingFIFO (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 datamay 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 the Saintas 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 fromthe Type property of the Ponomar::Saint parent). Note that dRank is not thesame as the day’s dRank, computed below. The confusion in terminologyis unfortunate.BUG NOTICE: As presently written, the API accepts only one SERVICEper Saint. That is, only one type of service may be read in, e.g., reading a

4

second VESPERS service into a Saint will create two Service objects thatare completely indistinguishable. This means that subsequent Scripturereadings, if any, will be assigned to both Service objects. This will haveunforseen 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 serviceor 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 relevantService objects. See the documentation for Ponomar::Service for details.

2 The Ponomar Class

METHODS

new($date, $language, [$GS] )

Creates a newPonomar 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 theselection of scriptures. As of August 2018, non-Lucan Jump implementa-tions are no longer supported ($GS is always treated as 1 regardless of userinput).

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 arecalled ’pentecostarion’, i.e., ’pentecostarion’ refers to everything based offthe 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 localeof 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 withthe dateOptional 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 specifieswhich version of the Bible to load if multiple versions are available in alanguage. 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 forthat 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 bythe 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 for work-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 sothat everything uses Lingua::CU.

METHODS

hip2unicode ( $string )

Takes $string, a string inHIP (Hyperinvariant Presentation), and convertsit to Unicode

ucs2unicode ( $string )

Takes $string, a string in UCS (Universal Church Slavonic), and convertsit to Unicode

resolveTitli ( $string )

Takes $string, a string of Church Slavonic text in Unicode, and resolvesany Titli present, including numerals.

cu2arabic ( $string )

Takes $string, a numeral in Church Slavonic, and converts it to a numeralin Arabic numerals.

arabic2cu ( $number )

Takes $number, a number, and returns its representation in Slavonic nu-merals.

9

5 Ponomar::I18n

Ponomar::I18n - Internationalization components for Ponomar

DESCRIPTION

This class handles I18n in Ponomar. Note that at least Perl 5.007 is required, aswe must have Unicode support.

METHODS

load($location)

Loads the YAML data in the file, the path of which is $location

getLocaleKey($key, $locale)

Returns the appropriate $key in the given $language; e.g.:

Ponomar::I18n::getLocaleKey(’february’, ’en’)

returns ’February’

getAvailableLanguages()

Returns an array with the available languages in the Ponomar YAML file

unload()

Unloads the localization, freeing up the memory and destroying the inter-nal YAML::Tiny object.

dateToStringFull($jdate, [$locale])

Returns the fullstring representation of $jdate, a Ponomar::JDate object,in the specified locale. If locale is not specified, en is assumed.

dateToString($jdate, [$locale])

Returns a short string representation of $jdate, a Ponomar::JDate object,in the specified $locale. If $locale is not specified, ’en’ is assumed.

dateToStringGregorian($jdate, [$locale])

Returns a string representation of $jdate, a Ponomar::JDate object, in thespecified $locale on the Gregorian calendar. If $locale is not specified,en is assumed.

10

6 Ponomar::JDate

Ponomar::JDate - A module for working with dates on the (proleptic) Julian Cal-endar

SYNOPSIS

use Ponomar::JDate;$date = new Ponomar::JDate(2, 1, 2001); # RETURNS February 1, 2001$date2 = $date->addDays(1); # returns February 2, 2001$date2->equals(new Ponomar::JDate(2, 2, 2001)); # RETURNS true

By convention January is treated as Month 1. Sunday is treated as day ofweek 0. January 1 is treated as day of year 0.

METHODS

new($julian_day) OR new($month, $day, $year)

Creates a new instance of Ponomar::JDate either set to Month, Day, Yearwhere Month, Day, Year is a calendar date on the Julian Calendar or to theJulian Day.The months begin with 1 for January and run to 12 for December. Thoughyears BC are generally not used, if necessary, the code is defined so thatthe $year before AD 1 is -1 (NOT 0). The $day may have a fractional com-ponent.Note that Julian Days begin at Noon UTC, so we usually have a 0.5 around,which is a bit annoying, but is done this way to keep all formulae in thiscode the same as in Meuss, Astronomical Algorithms (1st edition).

getYear()

Returns the Year of the JDate objectExample:

$date = new Ponomar::JDate(2, 1, 2001);$date->getYear(); # returns 2001

getYearAM()

Returns the Year from the (Byzantine) Creation of theWorld (annomundi).The Creation of the World took place on March 1, 5508 BC.

11

getMonth()

Returns the Month of the JDate object.Example:

$date = new Ponomar::JDate(2, 1, 2001);$date->getMonth(); # returns 2

NB: January is month 1

getDay()

Returns the day of the month of the JDate object.Example:

$date = new Ponomar::JDate(2, 1, 2001);$date->getDay(); # returns 1

getHour()

Returns the hour component of the JDate object (which may be fractional).This is useful for such things as vernal equinox, sunrize and moon calcu-lations.The result is always in hours since midnight UTC, and by convention theJDay starts at noon UTC.

getMinute()

Returns the minute component of the JDate object (which may be frac-tional).This is useful for such things as vernal equinox, sunrize and moon calcu-lations.The result is always in minutes since the last hour UTC.

getSecond()

Returns the second component of the JDate object (which may be frac-tional).This is useful for such things as vernal equinox, sunrize and moon calcu-lations.The result is always in seconds since the last minute UTC.

12

getDayOfWeek()

Returns the day of the week of the JDate object.Example:

$date = new Ponomar::JDate(2, 1, 2001);$date->getDayOfWeek(); # returns 2

NB: Sunday is day of week 0.

getDayOfWeekString

Returns the day of the week as a string.

getDoy()

Returns the day of the year (doy) of a JDate object.Note that January 1 is doy 0. February 29, if it exists, is doy 366.

getYearGregorian()

Returns the year of the JDate object according to the (proleptic) Gregoriancalendar.

getMonthGregorian()

Returns the month of the JDate object according to the (proleptic) Grego-rian calendar.

getDayGregorian()

Returns the day of the Month of the JDate object according to the (prolep-tic) Gregorian calendar.

getDaysSince($date)

Returns the number of days since $date, another JDate object.

getDaysUntil($date)

Returns the number of days until $date, another JDate object.

getWeeksSince($date)

Returns the number of weeks since $date, another JDate object.

13

getWeeksUntil($date)

Returns the number of weeks until $date, another JDate object.

addDays($integer)

Returns a new JDate object, advanced by $integer days.

addOneDay()

Returns a new JDate object, advanced by one day.

addMonths($integer)

Returns a new JDate object, advanced by $integer months.

subtractDays($integer)

Returns a new JDate object, diminished by $integer days.

subtractOneDay()

Returns a new JDate object, diminished by one day.

subtractMonths($integer)

Returns a new JDate object, diminished by $integer months.

equals($date)

Returns true of this JDate object and the object $date are the same Julianday. Returns false otherwise.

before($date)

Returns true if self is before $date.

after($date)

Returns true if self is after $date.

getJulianDay()

Returns the Julian day of the object.

getNearestSunday()

Returns a new JDate object with the nearest Sunday to a JDate object. NB:if the JDate object is a Sunday, returns itself.

14

getPreviousSunday()

Returns a new JDate object with the previous Sunday to a JDate object.NB: if the JDate object is a Sunday, returns one week before.

getNextSunday()

Returns a new JDate object with the next Sunday to a JDate object. NB: ifthe JDate object is a Sunday, returns one week later.

times($n)

Returns the a new JDate object with the Julian Day multiplied by $n. Prob-ably not very useful.

divide($n)

Returns the closest JDate object to the current JDate object divided by $n.This may be marginally useful in finding out things like midpoints of timeperiods.

module($n)

Returns the JDate object mod $n. Probably completely useless.

getSunrise($longitude, $latitude, $TimeZone, [$DST, $ALT])

Return the sunrise/sunset for a given day.

Eastern longitude is entered as a positive numberWestern longitude is entered as a negative numberNorthern latitude is entered as a positive numberSouthern latitude is entered as a negative number

Example:($sunrise, $sunset) = $date->getSunrise($longitude, $latitude, $TimeZone,$DST, $ALT);

Returns the sunrise and sunset times, in HH:MM format. Note: $Time Zoneis the offset from UTC and $<DST> is daylight saving time (1means DSTis in effect and 0means it is not). If $ALT is not specified, a default altitude of-.0833 is used. Note that adding 1 to $TimeZone during DST and specifying$DST as 0 is the same as indicating the Time Zone correctly and specifying$DST as 1.

15

There are a number of values of $ALT to choose from.The default is -0.833because this is what most countries use. Here is the list of other commonvalues:

0 degreesCenter of Sun’s disk touches a mathematical horizon

-0.25 degreesSun’s upper limb touches a mathematical horizon

-0.583 degreesCenter of Sun’s disk touches the horizon; atmospheric refraction ac-counted for

-0.833 degrees, DEFAULTSun’s supper limb touches the horizon; atmospheric refraction ac-counted for

-6 degrees, CIVILCivil twilight (one can no longer read outside without artificial illu-mination)

-12 degrees, NAUTICALNautical twilight (navigation using a sea horizon no longer possible)

-15 degrees, AMATEURAmateur astronomical twilight (the sky is dark enough for most as-tronomical observations)

-18 degrees, ASTRONOMICALAstronomical twilight (the sky is completely dark)

getMilankovichYear()

Returns the year of the JDate object according to the (proleptic) Mi-lankovich calendar.

getMilankovichMonth()

Returns the month of the JDate object according to the (proleptic) Mi-lankovich calendar.

getMilankovichDay()

Returns the day of the JDate object according to the (proleptic) Mi-lankovich calendar.

16

7 Ponomar::Reading

Ponomar::Reading - a scripture reading object for the Ponomar API.

METHODS

new( %attributes )

Creates a new Reading object.A Reading object has the following elements:Reading => The Reading (e.g., Gen_1:1-13) Pericope => The Pericopenumber (e.g., 103 -- OPTIONAL) EffWeek => The effective week of thereading (e.g., 17 -- OPTIONAL) Type => The Type of reading. This is use-less, except for Liturgy, where it must be one of apostol or gospel. saint=> The Assigned Saint or Commemoration ID.

getReading()

Returns the Reading of the object (e.g., Gen_1:1-13)

setReading($string)

Sets the Reading of the object to $string.

equals($other)

Tests to see if this Reading object is equal to another object $other.The following are equivalent:1. $ReadingsA is equal to $ReadingsB

2. $ReadingsA->{Reading} = $ReadingsB->{Reading} and $ReadingsA->{Saint}= $ReadingsB->{Saint}

Note that this method has been overloaded as ==; thus, you can write$ReadingsA == $ReadingsB.

notEquals($other)

Tests to see if this Reading object is not equal to another Reading object$other.The following are equivalent:1. $ReadingsA is not equal to $ReadingsB.

17

2. $ReadingsA->{Reading} != $ReadingsB->{Reading}OR $ReadingsA->{Saint}!= $ReadingsB->{Saint}

Note that this method has been overloaded as != Thus, you can write$ReadingsA != $ReadingsB.

18

8 Ponomar::Saint

Ponomar::Saint : a Commemoration / Saint object for the Ponomar API.

METHODS

new (%attrs)

Creates a new Saint object and runs init(), loading XML data for thisSaint.Saint objects have the following propertiesCId : the Commemoration ID. Name: A hash of Names for the Saint, whichcontains keys Nominative, Genetive, Short, etc. Src: the source of the com-memoration (one of triodion, pentecostarion, or menaion). Services: anarray containing the Services defined for this Saint.CURRENT LIMITATION: ONLY ONE SET OF SERVICES IS ALLOWEDFOR A SAINT. THIS NEEDS TO BE FIXED!

getKey($key)

Returns the value of the $key in this Saint, e.g.,

$self->getKey(’CId’)

returns the CId of the Saint

setKey($key, $value)

Sets the $key of the Saint equal to $value, e.g.,

$self->setKey(’CId’, 9000)

equals($other)

Tests to see if this saint is equal to $other saintThe following are equivalent:1. $saintA is equal to $saintB.2. $saintA->{Cid} is equal to $saintB->{Cid}.This method has been overloaded as ==, so you can write $saintA ==$saintB.

19

notEquals($other)

Tests to see if this saint is not equal to $other saintThe following are equivalent:1. $saintA is not equal to $saintB.2. $saintA->{Cid} is not equal to $saintB->{Cid}.This method has been overloaded as !=, so you can write $saintA !=$saintB.

stringify()

Returns a string. By definition, the stringification of the Saint is his CId.This method is overloaded as ””, so you can write ”$saint”.

addService($type)

Adds a Service object of type $type to self. Type here is the type of service,e.g., one of vespers, matins, liturgy, etc.

getServices( [$type] )

Returns an array of Service objects associated with this saint. If $type isspecified, returns only those Service objects of a particular $type. $type isthe Type of service, e.g., one of vespers, matins, liturgy, etc.

hasServices( [$type] )

Returns true if the Saint has associated Service objects and false otherwise.If $type is specified, returns true if Saint has associated Service of $typeand false otherwise.

hasIcons ( [$lang] )

Returns true if the Saint has associated Icons. If $lang is specified, returnstrue if the Saint has associated Icons in language $lang. Otherwise, returnsfalse.

20

9 Ponomar::Service

Ponomar::Service - A service object for the Ponomar API.

METHODS

new(%properties)

Creates a new Service objectService objects have the following propertiestype: The type of service (e.g., e.g., one of vespers, matins, liturgy, etc.)dRank: The Rank of this service (NOT the rank of the day). parent: a ref-erence to a Saint object which begat this Service object.

addReading($reading)

Assings a Reading object $reading to the service.

deleteReading($reading)

Removes a Reading object $reading from the service.

getReadings()

Returns the set of Readings objects assigned to the service

hasReadings()

Returns true if the Service has Readings objects assigned

getType()

Returns the Type of the service (e.g., one of vespers, matins, liturgy, etc.).

clearCommands ( [$commandName] )

Removes all liturgical commands named $commandName from this serviceobject. If $commandName is undef, removes all liturgical commands. Returnsnothing.

addCommands ( $name, $value )

Given a liturgical command with name $name and boolean test $value,adds this command to the list of available commands for this Service. Seethe documentation for DivineLiturgy.xml for the list of allowable com-mand names. Note that $value is not checked for correct syntax. (THIS IS

21

A BUG). If either $name or $value is undef, the method will croak. Returnsnothing.

execCommands( $dRank )

Given the $dRank of the day, executes a set of commands associated withthis service. These commands may generate instructions, rearrange read-ings or do other operations.Presently, only one set of Commands is supported, this is the set of com-mands recorded in DivineLiturgy.xml. Thus, if the type of the service ob-ject is liturgy, the file DivineLiturgy.xml is processed and readings aresuppressed or transferred as necessary.If the type is not liturgy, nothing is done and undef is returned.If $self->{parent} is not a reference to a Saint, which is the parent ofthis Service, the method will croak.

22

10 Ponomar::Sunrise

Ponomar::Sunrise - Module that provides functions for the computation of Sun-rise and Sunset. Do not call directly, rather use JDate::getSunrise().

DESCRIPTION

Modified version of Astro::Sunrise to work with dates on the Julian Calen-dar. Dependency on DateTime removed. Removed wrapper methods, which havebeen moved to Ponomar::JDate. Basic computation kept in tact.

SPECIAL THANKS

Modified from Astro::Sunrise, which is by Ron Hill rkhill@firstlight.net.

COPYRIGHT and LICENSE

Here is the copyright information provided by Ron Hill in Astro::Sunrise:Written as DAYLEN.C, 1989-08-16. Modified to SUNRISET.C, 1992-12-01.Copyright Paul Schlyter, 1989, 1992. Released to the public domain by Paul

Schlyter, December 1992.Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the ”Software”), to deal in theSoftware without restriction, including without limitation the rights to use, copy,modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,and to permit persons to whom the Software is furnished to do so, subject to thefollowing conditions:

The above copyright notice and this permission notice shall be included inall copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ”AS IS”, WITHOUT WARRANTY OF ANYKIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WAR-RANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSEAND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLEFOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN AC-TIONOF CONTRACT, TORTOROTHERWISE, ARISING FROM, OUTOF OR INCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGSIN THE SOFTWARE.

23

SEE ALSO

Astro::Sunrise

24

11 Ponomar::Util

Ponomar::Util - Exports utility functions for Ponomar API.

DESCRIPTION

This is not an Object Oriented class, but rather is a set of utility functions for thePonomar API. All useful methods are exported from this class via the Exporterinterface.

METHODS

findBottomUp ($language, $file)

THIS ALGORITHM IMPLEMENTS BOTTOM-UP READING OF FILES INTHEXML PATH. THE FULL IMPLEMENTATION IS DESCRIBED BY YURIIN ”A Description”, p. 27.Basically, we beginwith basepath/<language>/<script>/<locale>/fileand go until basepath/file, stopping at the first occurance of file, whichis then read.PARAMETERS PASSED TO HERE: $language is the locale, e.g. cu/ru orzh/Hans. $file is e.g., xml/01/01.xml or xml/pentecostarion/01.xml.Returns: the full path to the file if found. Croaks if no file was found in theBottom-up path

findTopDown ($language, $file)

THIS ALGORITHM IMPLEMENTS THE TOP-DOWN APPROACH FORREADING FILES DESCRIBED BY YURI IN op. cit., p. 28WE CREATE AN ARRAY OF ALL EXTANT FILES NAMED $file IN ALLPATHS BEGINNING WITH BASEPATH AND UP TO$basepath/<language>/<script>/<locale>/file

PARAMETERS: SAME AS ABOVE. Returns: an array of all files in the top-down path. Carps and returns an empty array if no files were found.

exists_saint($cid)

Checks if a saint with CId $cid exists in the file structure. Returns 1 if saintexists and 0 otherwise.

25

getPascha($year)

Returns a new Ponomar::JDate object with Pascha for the specified $year.

getGregorianOffset($year)

Returns an Integer indicating by how many days the Gregorian calendaris ahead of the (potentially proleptic) Julian calendar in $year.

getToday( [$timeshift] )

Returns a Ponomar::JDate object with the date of Today according to theSystem clock.Optional parameter $timeshift indicates a Time zone shift from UTC inhours.WARNING: Ponomar::Util relies on time to set Today. It assumes that thesystem’s epoch begins on 00:00:00 UTC, January 1, 1970 (GREGORIAN!).It has recently come to my attention that this is not true for all systems. Iknow of no way to get around this problem, so this should be considereda bug.

julianFromGregorian( $month, $day, $year )

Given a $month, $day, and $year on theGregorian calendar, returns a JDateobject with the Julian day for this date. If date is before 1582, the functioncroaks.The formulae are from Meuss, p. 61.

getNextYearWithSamePascha ( $year )

Given $year, a year AD, returns the next year when Pascha occurs on thesame date as this year.

getPreviousYearWithSamePascha ($year)

Given $year, a year AD, returns the previous year when Pascha occurs onthe same day

getNextYearWithBoundary ($i, $Year)

Solves a reverse computus problem by returning the next year after $Yearwhen pascha occurs $i days after March 22.

26

getThisDayNextYear ($jdate)

Given $jdate, a date on the Julian calendar, returns a date next year thatis same number of days away from next year’s Pascha.

getThisDayPreviousYear ($jdate)

Given $jdate, a date on the Julian calendar, returns a date in the previ-ous year that is the same number of days away from the previous year’sPascha.

max(@array)

Given an @array of real numbers, returns the maximum.

argmax($code, @array)

Given an @array of objects, returns the object that maximizes the functiongiven by $code (the argument of the maximum).Note that $code need not specify a function that is injective. However, ifthe argmax is not unique, only the first maximizer will be returned (this isa bug?).If the argmax is the empty set, undef is returned. However, by construc-tion this would never occur, unless $code returns something that is notcomparable or @array is undef, since the argmax on an empty domain isnecessarily empty (or is it?). I should have paid attention in Analysis …E.g.:

argmax { $_->getKey(’Type’) } $ponomar->getSaints();

Returns the highest-ranked Saint of the day.

isNumeric($variable)

Given a $variable returns true if $variable is a real number.

getMatinsGospel($reading)

Given a $reading, which a String of the type returned by a Reading object,returns the Matins Gospel number. If the reading is not a matins gospel,returns undef.FIXME: THIS SHOULD ACTUALLY TAKE THE READING OBJECT ANDCHECK IF IT’S SUNDAY AND MATINS‼

27

getIndiction( $year )

Given $year, a year AD, returns the Indiction of the year. Carps if $yearis before 313 AD.

getSolarCycle( $year )

Given $year, a year AD, returns the solar cycle of the year.

getConcurrent( $year )

Given $year, a year AD, returns the concurrent (a number from 1 to 7).Theconcurrent numbers are associated with the Slavonic вруцелѣто letters sothat 1 = А, 2 = В, etc.

getLunarCycle( $year )

Given $year, a year AD, returns the lunar (Metonic) cycle number

getFoundation( $year )

Given $year, a year AD, returns the foundation (the “age of the moon” onMarch 1 of that year)

getEpacta( $year )

Given $year, a year AD, returns the Epacta. Note that this is not the RomanEpacta (the age of the moon on January 1). Rather, this is the number thatneeds to be added to make the Foundation 21 (or 51).

getKeyOfBoundaries( $year )

Given $year, a year AD, returns the Key of Boundaries, a letter indicatingthe structure of the year.

getGregorianEaster( $year )

Given $year, a year AD, returns the date of theGregorian Easter (accordingto the Julian calendar). If $year is less than 1583, this routine croaks. Thisroutine uses the formulae as given by Meuss, Astronomical Algorithms,Chapter 8.

getPassover( $year )

Given $year, a year AD, returns the date of the Jewish Passover (15 Nisan)according to the Julian calendar. The formulae are due to Meeus, Astro-nomical Algorithms, Chapter 9.

28

Note that this is the actual, modern Jewish Pesach, not the ecclesiasticalOld Testament Passover. The ecclesiastical old testament Passover can beobtained from the Epacta.

getNextFullMoon( $date )

Given $date, a JDate object, returns the Date and Time (Universal Time)of the next astronomical full moon. Used in Milankovic calculations.Formulae due to Meuss, p. 350ff.

getVernalEquinox ( $year )

Given $year, a year between AD 1000 and AD 3000, returns the date of theMarch equinoxFormulae due to Meuss, Astronomical Algorithms, pp. 177-182.

isMilankovichLeap ($year)

Given $year, a year, returns 0 unless it is a leap year on the Milankovichcalendar.

getJulianDayFromMilankovich ($month, $day, $year)

Given $month, $day, $year, a date according to the (proleptic) Milankovichcalendar, returns the Julian Day, that is the number of days since January1, 4713 BC on the proleptic Julian calendar.

getDeltaT ( $date )

Give $date, a JDate object with year between 1999 BC and 3000 ADon the (proleptic) Julian calendar, returns Delta T, that is, the offset (inseconds) between Dynamic Time and Universal Time. Note that UT =TD - DeltaT. These formulae are by Fred Espenak and Jean Meeus, seehttp://eclipse.gsfc.nasa.gov/SEcat5/deltatpoly.html formore in-formation.

getMilankovichPascha ( $year )

Wrapper sub for Milankovich calculations. Given a $year AD, returns thePascha according to the Milankovich specification.The Milankovich Pascha is defined as the Sunday after the midnight-to-midnight day at the meridian of the Church of the Holy Sepulchre inJerusalem during which the first full moon after the vernal equinox oc-curs.

29

Method for computing Milankovich Pascha

Compute the date and time of the Vernal Equinox for $year (returns $EQ,a Julian Day)

Compute the date and time of the full moon that occurs after $EQ (re-turns $MOON, a Julian Day in Dynamic Time)

Get the Date part of $MOON (returns $DAY, $MONTH, a date on the Juliancalendar)

Convert the time part of $MOON to Universal Time using the polynomi-als here:http://eclipse.gsfc.nasa.gov/SEcat5/deltatpoly.html.

Convert the Universal Time to local time at theChurchof theHoly Sepul-chre. For simplicity, assume the Holy Sepulchre is always twohours ahead of UT. (This is $TIME in Hours, including a fractionalcomponent).

If $TIME > 24, add 1 to $DAY (note this may also push $MONTH up).

Compute the next Sunday after $DAY ($PDAY). This is the date of Pascha.

The method returns a JDate object containing the Julian Day of the Mi-lankovich Pascha.NOTE: the resulting JDate object is a Julian Day. Since you’re workingwith the Milankovich calendar, you will probably want the date accordingto the Milankovich calendar. Use the getMilankovich... functions of theJDate class, e.g.:

$pascha = getMilankovichPascha(2100);print $pascha->getMilankovichDay();

30